Manifest

Le manifest relie un tool Touba à un handler hôte. Il déclare aussi les grants, secrets, limites et accès mémoire accordés par l’environnement d’exécution.

Il est fourni explicitement au runtime. Le runtime ne découvre pas automatiquement les manifests.

Le manifest peut aussi activer un trigger déclaré dans l’AIR. Sans entrée explicite, le trigger reste inactif.

Le handler est lancé sans shell implicite et avec un environnement minimal. Pour un handler JavaScript, touba prepare écrit le chemin absolu du Node courant dans handler.command.

Forme minimale

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
    }
  }
}

Le manifest ne donne pas une capacité que le tool n’a pas demandée. Il accorde explicitement ce que l’AIR exige.

Contrat des effets externes

Le format unique touba-manifest-v1 exige un contrat d'effet explicite pour chaque binding. Celui-ci déclare soit effect_contract: { "kind": "none" }, soit une écriture external_write et son mode réel de retry : idempotency_key, reconcile ou none.

Le générateur laisse effect_contract: null tant que le développeur n'a pas qualifié le comportement réel du handler. Ce brouillon n'est pas exécutable. Voir Effets externes et idempotence bornée pour les reçus et le journal durable requis par les écritures.

Une écriture externe peut aussi déclarer une seule stratégie inverse :

Déclaration d'une inverse

"effect_contract": {
  "kind": "external_write",
  "retry_mode": "idempotency_key",
  "compensation": {
    "entry_ref": "strategy:orders/CancelOrder"
  }
}

Cette relation ne déclenche rien automatiquement et n'accorde aucun droit à la stratégie inverse. Une demande de compensation explicite doit encore revalider son autorité, son approbation éventuelle, ses budgets et le binding du tool inverse.

Cas simple

Un tool qui demande seulement network peut avoir un binding simple :

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
    }
  }
}

Si le binding manque ou si network n’est pas accordé, le runtime refuse avant handler.

Cas avancé

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
    }
  }
}

Ce manifest relie trois décisions :

• quel handler process est lancé ;
• quels grants et handles sont accordés ;
• quel accès mémoire est accordé au binding.

Le scope de secret par agent limite aussi l’usage du handle dans un périmètre agentique.

Ce que le manifest absorbe

Sans manifest explicite, le raccordement entre un nom de tool, un fichier handler, des droits locaux et des limites peut devenir une convention de projet.

Avec le manifest, cette convention devient un artefact relu par le runtime. Les erreurs de binding, grants, secrets ou mémoire peuvent produire des refus observables.

Contrat runtime

• Un manifest n’est pas une sandbox système.
• Un grant n’est pas une permission forte de bout en bout.
• Un secret est référencé par handle ; sa valeur vit dans un fichier de résolution ou une source explicite séparée.
• Un manifest généré reste à relire.
• Le lock supply chain peut vérifier la cohérence du manifest, des handlers, du SDK, de handler_package, des fichiers de paquet handler et des artefacts de dépendances déclarés, mais il ne donne pas de droit runtime.