AIR, runtime et traces

Touba se lit en trois temps :

Définition

AIR     = contrat compilé
runtime = exécution du contrat
trace   = observation de l’exécution

AIR

L’AIR est produit à partir du fichier .tb.

Il contient les déclarations, graphes, expressions, tools, agents, stratégies, mémoires, capacités requises, handles de secrets et règles d’invocation.

Il porte aussi les informations qui permettent au runtime de construire le catalogue de ressources d’un agent : uses, signatures, sous-capacités, handles de secrets et règles callable_by.

L’AIR décrit le programme avant son exécution. Les secrets sont résolus par l’hôte et le code des handlers reste séparé ; les réponses à ask sont des données d’exécution, pas des déclarations compilées.

Forme source :

source.tb

strategy StrategyName
    uses AgentName
    do
        AgentName

Extrait source :

source.tb

strategy RunReview
    uses Reviewer
    do
        Reviewer

Après compilation, l’AIR porte une référence structurée à la stratégie, à son graphe et à l’appel d’agent. L’objectif est que la CLI, le runtime et les surfaces Touba lisent le même contrat.

Runtime

Le runtime exécute l’AIR avec des artefacts explicites : inputs, manifest, secrets, décisions humaines et entrées utilisateur.

Quand un contrat n’est pas satisfait, il refuse avant d’appeler le handler concerné.

Quand un agent passe par un provider de décision, le runtime prépare une entrée modèle structurée, expose le catalogue seulement au besoin, vérifie la capacité choisie, exécute ou refuse, puis peut retourner le résultat comme observation pour la décision suivante.

Forme d’exécution :

Structure

source .tb -> AIR JSON -> runtime -> trace

Exemple de contrôle runtime :

Sortie

RunReview -> Reviewer
runtime vérifie que RunReview est autorisé par callable_by
runtime exécute seulement si le contrat est satisfait

Trace

La trace est le résultat observable d’une exécution.

Elle permet de voir :

• quel point d’entrée a été lancé ;
• quels appels ont commencé et terminé ;
• quels tools ont été autorisés ;
• quels agents ont été autorisés ou refusés ;
• quelles capacités agentiques ont été listées, sélectionnées ou refusées ;
• quand une observation runtime est disponible pour la décision suivante ;
• quand un review humain est demandé par un agent ;
• où le runtime a mis l’exécution en pause ;
• pourquoi un refus s’est produit.
• quel trigger a été reçu, accepté ou refusé quand une exécution est déclenchée par événement.

La trace n’est pas un stockage de données sensibles.

Forme d’événement :

trace.json

{
  "kind": "event_name",
  "payload": {}
}

Extrait simplifié :

trace.json

{
  "kind": "agent_invocation_authorized",
  "payload": {
    "caller_ref": "strategy:examples/RunReview",
    "agent_ref": "agent:examples/Reviewer",
    "authority_source": "callable_by"
  }
}

La trace dit qu’une autorisation a eu lieu. Elle ne contient pas la valeur d’un secret ou une réponse utilisateur sensible.

Extrait de décision agentique :

trace.json

{
  "kind": "agent_capability_result_returned",
  "payload": {
    "agent_ref": "agent:examples/Researcher",
    "selected_ref": "skill:examples/BuildBrief",
    "result_available": true,
    "result_type": "object"
  }
}

La trace indique que le résultat est disponible. Elle ne sérialise pas le résultat brut dans cet événement.

Inspection

Terminal

touba inspect program.air.json
touba inspect trace.json

L’inspecteur affiche une vue texte des artefacts sans exécuter le programme et sans lire de secrets.

Audit des traces

Quand une trace doit être conservée avec plus de contexte, l’audit des traces peut relier explicitement la trace, l’AIR, la source et le manifest :

Terminal

touba audit \
  --trace trace.json \
  --air program.air.json \
  --source source.tb \
  --manifest touba.manifest.json \
  --export trace-audit.export.json

Cet audit produit un rapport et des digests locaux. Il n’ajoute pas de garantie juridique ou réglementaire ; il rend les artefacts fournis plus faciles à relire et à comparer.