AIR, Runtime, and Traces

Touba is read in three stages:

Definition

AIR     = compiled contract
runtime = execution of the contract
trace   = observation of the execution

AIR

AIR is produced from a .tb file.

It contains declarations, graphs, expressions, tools, agents, strategies, memories, required capabilities, secret handles, and invocation rules.

It also carries the information that lets the runtime build an agent resource catalog: uses, signatures, sub-capabilities, secret handles, and callable_by rules.

AIR describes the program before execution. The host resolves secrets and handler code remains separate. Answers to ask are execution data, not compiled declarations.

Source form:

source.tb

strategy StrategyName
    uses AgentName
    do
        AgentName

Source excerpt:

source.tb

strategy RunReview
    uses Reviewer
    do
        Reviewer

After compilation, AIR carries a structured reference to the strategy, its graph, and the agent call. The goal is that the CLI, runtime, and Touba surfaces read the same contract.

Runtime

The runtime executes AIR with explicit artifacts: inputs, manifest, secrets, human decisions, and user inputs.

When a contract is not satisfied, it refuses before calling the relevant handler.

When an agent uses a decision provider, the runtime prepares a structured model input, exposes the catalog only when needed, verifies the selected capability, executes or refuses, and can return the result as an observation for the next decision.

Execution shape:

Structure

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

Runtime control example:

Output

RunReview -> Reviewer
runtime verifies that RunReview is authorized by callable_by
runtime executes only when the contract is satisfied

Trace

The trace is the observable result of a run.

It shows:

• which entry point was started;
• which calls started and completed;
• which tools were authorized;
• which agents were authorized or refused;
• which agentic capabilities were listed, selected, or refused;
• when a runtime observation is available for the next decision;
• when human review is requested by an agent;
• where the runtime paused execution;
• why a refusal happened;
• which trigger was received, accepted, or refused when a run is event-driven.

The trace is not a store for sensitive data.

Event shape:

trace.json

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

Simplified excerpt:

trace.json

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

The trace records that authorization occurred. It does not contain a secret value or a sensitive user answer.

Agentic decision excerpt:

trace.json

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

The trace indicates that the result is available. It does not serialize the raw result in this event.

Inspection

Terminal

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

The inspector renders a textual view of artifacts without executing the program and without reading secrets.

Trace Audit

When a trace must be retained with more context, trace audit can explicitly connect the trace, AIR, source, and manifest:

Terminal

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

This audit produces a report and local digests. It is an engineering audit artifact: it makes the supplied artifacts easier to review, compare, and preserve.