Documentation

Agent Harness

Contrôle d'accès basé sur les rôles, budgets et gouvernance pour les agents IA avec lean-ctx.

L'Agent Harness contrôle ce que les agents IA peuvent faire, combien ils peuvent dépenser et quels outils ils peuvent utiliser. Il applique un contrôle d'accès basé sur les rôles avec un suivi budgétaire en temps réel.

Qu'est-ce que l'Agent Harness ?

L'Agent Harness est la couche de gouvernance de lean-ctx. Il attribue des rôles aux agents, applique des politiques d'outils et suit les budgets (tokens, invocations shell, coût). Lorsque les limites approchent, des avertissements sont émis ; lorsqu'elles sont dépassées, les outils sont bloqués.

Rôles intégrés

lean-ctx est livré avec 5 rôles intégrés. Chaque rôle définit l'accès aux outils, la politique shell et les limites de ressources. Le rôle par défaut est coder.

coder

Accès complet aux outils pour l'implémentation. Budget de 200K tokens, 100 invocations shell, limite de coût de $5.

reviewer

Accès en lecture seule pour la revue de code. Pas de shell, pas d'édition. 150K tokens, limite de coût de $3.

debugger

Orienté débogage avec accès shell étendu. 150K tokens, 200 invocations shell, limite de coût de $5.

ops

Opérations d'infrastructure et CI/CD. Intensif en shell, pas d'édition. 100K tokens, 300 invocations shell, limite de coût de $3.

admin

Accès illimité avec des limites élevées. 500K tokens, 500 invocations shell, limite de coût de $50.

Application des budgets

Chaque appel d'outil est suivi par rapport au budget du rôle actif. Le budget a trois dimensions :

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

Dimensions du budget

  • Tokens de contexte - tokens totaux consommés par les sorties d'outils
  • Invocations shell - nombre d'appels ctx_shell / ctx_execute
  • Coût estimé - coût approximatif en USD de la session

Signaux budgétaires

Le harness émet des signaux basés sur la consommation du budget :

  • OK - utilisation sous le seuil d'alerte (par défaut : 80%)
  • WARNING - utilisation entre les seuils d'alerte (80%) et de blocage (100%). Un avertissement est ajouté aux réponses des outils.
  • EXHAUSTED - utilisation au seuil de blocage ou au-delà. Les appels d'outils suivants sont bloqués (sauf ctx_session).

Politiques d'outils

Chaque rôle définit quels outils sont autorisés et refusés. Les outils refusés remplacent toujours les outils autorisés. Utilisez * comme joker.

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

Politique shell

  • track - shell autorisé, les commandes sont enregistrées (par défaut)
  • compress - shell autorisé, la sortie est compressée
  • deny - accès shell complètement bloqué

Événements du Harness

L'Agent Harness émet des événements structurés vers le bus d'événements et le log JSONL :

  • BudgetWarning - une dimension du budget a franchi le seuil d'alerte
  • BudgetExhausted - une dimension du budget est entièrement consommée
  • PolicyViolation - un agent a tenté d'utiliser un outil bloqué
  • RoleChanged - le rôle actif a été changé à l'exécution

Rôles personnalisés

Créez des fichiers TOML dans .lean-ctx/roles/ (local au projet) ou ~/.lean-ctx/roles/ (global). Les rôles supportent l'héritage via le champ 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.0

Vérifiez le rôle actuel avec ctx_session action=role. Changez de rôle avec ctx_session action=role value=<name>.

Activer un rôle

Définissez la variable d'environnement LEAN_CTX_ROLE :

export LEAN_CTX_ROLE=reviewer

Ou changez à l'exécution via MCP :

ctx_session action=role value=debugger

Vérifier le statut du budget :

ctx_session action=budget