प्रलेखन

Agent Harness

lean-ctx के साथ AI एजेंटों के लिए भूमिका-आधारित एक्सेस नियंत्रण, बजट और शासन।

Agent Harness नियंत्रित करता है कि AI एजेंट क्या कर सकते हैं, कितना खर्च कर सकते हैं और कौन से टूल उपयोग कर सकते हैं।

Agent Harness क्या है?

The Agent Harness is lean-ctx's governance layer. It assigns roles to agents, enforces tool policies, and tracks budgets (tokens, shell invocations, cost). When limits are approached, warnings are emitted. LeanCTX never blocks by default - it always helps your AI, even when budgets are exceeded. Blocking can be enabled explicitly for strict governance scenarios.

अंतर्निहित भूमिकाएँ

lean-ctx ships with 5 built-in roles. Each role defines tool access, shell policy, and resource limits. The default role is coder.

coder

Full tool access for code implementation. 200K token budget, 100 shell invocations, $5 cost limit.

reviewer

Read-only access for code review. No shell, no editing. 150K tokens, $3 cost limit.

debugger

Debug-focused with extended shell access. 150K tokens, 200 shell invocations, $5 cost limit.

ops

Infrastructure and CI/CD operations. Shell-heavy, no editing. 100K tokens, 300 shell invocations, $3 cost limit.

admin

Unrestricted access with high limits. 500K tokens, 500 shell invocations, $50 cost limit.

बजट प्रवर्तन

Every tool call is tracked against the active role's budget. The budget has three dimensions:

Budget[coder]: tokens 50000/200000 (25%) | shell 5/100 (5%) | cost $0.50/$5.00 (10%) → OK

Budget Dimensions

  • Context Tokens - total tokens consumed by tool outputs
  • Shell Invocations - number of ctx_shell / ctx_execute calls
  • Estimated Cost - approximate USD cost of the session

Budget Signals

The harness emits signals based on budget consumption:

  • OK - usage below warn threshold (default: 80%)
  • WARNING - usage between warn (80%) and block (100%) thresholds. A warning is appended to tool responses.
  • EXHAUSTED - usage at or above threshold. By default, LeanCTX continues working with warnings (never blocks). For strict governance, set block_at_percent: 100 in the role config to enable blocking.

टूल नीतियाँ

Each role defines which tools are allowed and denied. Denied tools always override allowed tools. Use * as a wildcard.

[tools]
allowed = ["ctx_read", "ctx_search", "ctx_tree", "ctx_session"]
denied = ["ctx_edit", "ctx_shell"]

Shell Policy

  • track - shell allowed, commands are logged (default)
  • compress - shell allowed, output is compressed
  • deny - shell access completely blocked

Harness इवेंट

The Agent Harness emits structured events to the event bus and JSONL log:

  • BudgetWarning - a budget dimension crossed the warning threshold
  • BudgetExhausted - a budget dimension is fully consumed
  • PolicyViolation - an agent attempted to use a blocked tool
  • RoleChanged - the active role was switched at runtime

कस्टम भूमिकाएँ

Create TOML files in .lean-ctx/roles/ (project-local) or ~/.lean-ctx/roles/ (global). Roles support inheritance via the inherits field.

[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.0

Check current role with ctx_session action=role. Switch roles with ctx_session action=role value=<name>.

भूमिका सक्रिय करें

Set the LEAN_CTX_ROLE environment variable:

export LEAN_CTX_ROLE=reviewer

Or switch at runtime via MCP:

ctx_session action=role value=debugger

Check budget status:

ctx_session action=budget