El Agent Harness controla lo que los agentes de IA pueden hacer, cuánto pueden gastar y qué herramientas pueden usar. Aplica control de acceso basado en roles con seguimiento de presupuesto en tiempo real.
¿Qué es el Agent Harness?
El Agent Harness es la capa de gobernanza de lean-ctx. Asigna roles a los agentes, aplica políticas de herramientas y rastrea presupuestos (tokens, invocaciones de shell, costo). Cuando se acercan los límites, se emiten advertencias; cuando se exceden, las herramientas se bloquean.
Roles integrados
lean-ctx incluye 5 roles integrados. Cada rol define acceso a herramientas, política de shell y límites de recursos. El rol predeterminado es coder.
coder
Acceso completo a herramientas para implementación. Presupuesto de 200K tokens, 100 invocaciones de shell, límite de costo de $5.
reviewer
Acceso de solo lectura para revisión de código. Sin shell, sin edición. 150K tokens, límite de costo de $3.
debugger
Enfocado en depuración con acceso shell extendido. 150K tokens, 200 invocaciones de shell, límite de costo de $5.
ops
Operaciones de infraestructura y CI/CD. Intensivo en shell, sin edición. 100K tokens, 300 invocaciones de shell, límite de costo de $3.
admin
Acceso sin restricciones con límites altos. 500K tokens, 500 invocaciones de shell, límite de costo de $50.
Aplicación de presupuestos
Cada llamada de herramienta se rastrea contra el presupuesto del rol activo. El presupuesto tiene tres dimensiones:
Budget[coder]: tokens 50000/200000 (25%) | shell 5/100 (5%) | cost $0.50/$5.00 (10%) → OKDimensiones del presupuesto
- Tokens de contexto - tokens totales consumidos por las salidas de herramientas
- Invocaciones de shell - número de llamadas
ctx_shell/ctx_execute - Costo estimado - costo aproximado en USD de la sesión
Señales de presupuesto
El harness emite señales basadas en el consumo del presupuesto:
- OK - uso por debajo del umbral de advertencia (predeterminado: 80%)
- WARNING - uso entre los umbrales de advertencia (80%) y bloqueo (100%). Se agrega una advertencia a las respuestas de herramientas.
- EXHAUSTED - uso en o por encima del umbral de bloqueo. Las llamadas de herramientas posteriores se bloquean (excepto
ctx_session).
Políticas de herramientas
Cada rol define qué herramientas están permitidas y denegadas. Las herramientas denegadas siempre anulan las permitidas. Use * como comodín.
[tools]
allowed = ["ctx_read", "ctx_search", "ctx_tree", "ctx_session"]
denied = ["ctx_edit", "ctx_shell"]Política de shell
track- shell permitido, los comandos se registran (predeterminado)compress- shell permitido, la salida se comprimedeny- acceso shell completamente bloqueado
Eventos del Harness
El Agent Harness emite eventos estructurados al bus de eventos y al log JSONL:
- BudgetWarning - una dimensión del presupuesto cruzó el umbral de advertencia
- BudgetExhausted - una dimensión del presupuesto está completamente consumida
- PolicyViolation - un agente intentó usar una herramienta bloqueada
- RoleChanged - el rol activo se cambió en tiempo de ejecución
Roles personalizados
Cree archivos TOML en .lean-ctx/roles/ (local al proyecto) o ~/.lean-ctx/roles/ (global). Los roles soportan herencia mediante el campo inherits.
[role]
name = "security-auditor"
inherits = "reviewer"
description = "Security-focused code review"
shell_policy = "deny"
[tools]
allowed = ["ctx_read", "ctx_search", "ctx_tree", "ctx_review", "ctx_session"]
denied = ["ctx_edit", "ctx_shell", "ctx_execute"]
[limits]
max_context_tokens = 100000
max_shell_invocations = 0
max_cost_usd = 2.0Verifique el rol actual con ctx_session action=role. Cambie de rol con ctx_session action=role value=<name>.
Activar un rol
Establezca la variable de entorno LEAN_CTX_ROLE:
export LEAN_CTX_ROLE=reviewerO cambie en tiempo de ejecución vía MCP:
ctx_session action=role value=debuggerVerificar estado del presupuesto:
ctx_session action=budget