Manifest

The manifest connects a Touba tool to a host handler. It also declares the grants, secrets, limits, and memory access provided by the execution environment.

It is supplied explicitly to the runtime. The runtime does not discover manifests automatically.

The manifest can also activate a trigger declared in AIR. Without an explicit entry, the trigger remains inactive.

The handler is launched without an implicit shell and with a minimal environment. For a JavaScript handler, touba prepare writes the absolute path of the current Node executable into handler.command.

Minimal Shape

touba.manifest.json

{
  "manifest_version": "touba-manifest-v1",
  "bindings": {
    "tool:examples.tool_simple/SearchDatasets": {
      "handler": {
        "kind": "process",
        "command": "/absolute/path/to/node",
        "args": ["handlers/search_datasets.handler.mjs"],
        "cwd": "."
      },
      "grants": ["network"],
      "effect_contract": { "kind": "none" },
      "timeout_ms": 5000,
      "max_payload_bytes": 1048576
    }
  }
}

The manifest does not grant a capability the tool did not request. It explicitly grants what AIR requires.

Explicit effect contract

touba-manifest-v1 is the only admitted format. Every binding must declare effect_contract: { "kind": "none" } for a non-writing operation, or { "kind": "external_write", "retry_mode": "none" } for an external write without safe retry support. The other retry modes, idempotency_key and reconcile, require real support from the external service.

An external write may also declare compensation: { "entry_ref": "strategy:orders/CancelOrder" }. The inverse must be an eligible strategy in the exact AIR and remains subject to its own authority checks.

The generator leaves effect_contract: null until the developer reviews the handler behavior. This draft is not executable. Unknown fields, missing contracts and retired formats are refused before dispatch. CLI writes require --effect-journal <path.effect-journal.sqlite>; JavaScript runs use the effectJournal option. All handlers use touba-tool-handler-v1, with operation: invoke or operation: compensate.

Simple Case

A tool that requires only network can have a simple binding:

touba.manifest.json

{
  "manifest_version": "touba-manifest-v1",
  "bindings": {
    "tool:examples.tool_simple/SearchDatasets": {
      "handler": {
        "kind": "process",
        "command": "/absolute/path/to/node",
        "args": ["handlers/search_datasets.handler.mjs"],
        "cwd": "."
      },
      "grants": ["network"],
      "effect_contract": { "kind": "none" },
      "timeout_ms": 5000,
      "max_payload_bytes": 1048576
    }
  }
}

If the binding is missing, or if network is not granted, the runtime refuses before the handler.

Advanced Case

touba.manifest.json

{
  "manifest_version": "touba-manifest-v1",
  "agent_secret_scopes": {
    "agent:examples.tool_advanced/Analyst": ["LLM_API_KEY"]
  },
  "bindings": {
    "tool:examples.tool_advanced/SummarizeWithContext": {
      "handler": {
        "kind": "process",
        "command": "/absolute/path/to/node",
        "args": ["handlers/summarize_with_context.handler.mjs"],
        "cwd": "."
      },
      "grants": ["network", "secret_read", "memory_read"],
      "effect_contract": { "kind": "none" },
      "secrets": ["LLM_API_KEY"],
      "memories": [
        { "ref": "memory:examples.tool_advanced/ProjectKnowledge", "access": "read" }
      ],
      "timeout_ms": 10000,
      "max_payload_bytes": 1048576
    }
  }
}

This manifest connects three decisions:

• which handler process is launched;
• which grants and handles are provided;
• which memory access is granted to the binding.

The per-agent secret scope also limits handle usage inside an agentic boundary.

What the Manifest Carries

Without an explicit manifest, the connection between a tool name, a handler file, local rights, and limits becomes a project convention.

With the manifest, that convention becomes an artifact reviewed by the runtime. Binding, grant, secret, or memory errors can produce observable refusals.

Runtime Contract

• A manifest is not a system sandbox.
• A grant is not an end-to-end operating-system permission.
• A secret is referenced by handle; its value lives in a separate explicit resolution source.
• A generated manifest remains reviewable.
• The supply-chain lock can verify the coherence of the manifest, handlers, SDK, handler_package, handler package files, and declared dependency artifacts, but it does not grant runtime authority.