Tool binding, handler et manifest
Ce guide explique comment un tool Touba exécute du code réel sans mettre ce code dans le fichier .tb.
Vue d’ensemble
source .tb
déclare un tool
|
v
AIR
porte les requirements
|
v
runtime
vérifie le manifest
|
v
handler
exécute l’effet réel
|
v
trace
observe autorisation, refus ou succès
Déclarer le tool
Forme :
tool Name
takes input as InputType
gives OutputType
requires capability
Exemple :
tool SearchDatasets
takes request as DatasetSearchRequest
gives DatasetSearchResult
requires network
Cette déclaration ne donne pas accès au réseau. Elle dit que le tool exige la capacité network.
Capacités de tools
La liste V1 est fermée : network, filesystem_read, filesystem_write,
process, external_api, secret_read, human_approval, memory_read
et memory_write. Toute autre valeur produit UnknownToolCapability.
process couvre les opérations de processus hôte, par exemple appeler Docker.
Séparez ReadLogs et RestartService en deux tools pour que uses puisse
accorder l'un sans l'autre. Ces grants sont des contrôles d'admission, pas
un sandbox système. La capacité human_approval ne crée pas à elle seule
une pause : placez human.approve avant l'effet à protéger.
Générer le manifest
Forme :
touba compile program.tb --out program.air.json
touba manifest generate program.air.json --out touba.manifest.json
Dans un projet Touba, le workflow recommandé est :
touba prepare --mode plan
touba prepare --mode write
touba prepare --mode check
prepare produit ou vérifie le manifest projet et les stubs de handlers à partir de l’AIR. Les commandes touba compile, touba manifest generate et touba handler stub restent utiles pour comprendre chaque transformation séparément.
Exemple :
touba compile search.tb --out search.air.json
touba manifest generate search.air.json --out touba.manifest.json
Le manifest est un template à relire. Il relie un tool à un handler et déclare les grants, secrets et limites accordés.
Créer un handler
Forme :
touba handler stub program.air.json \
--tool-ref tool:module.name/ToolName \
--handler-root handlers
Exemple :
touba handler stub search.air.json \
--tool-ref tool:examples.search/SearchDatasets \
--handler-root handlers
Le fichier généré est un squelette. Le développeur y ajoute le code métier.
Écrire le handler avec le SDK
Forme :
await defineTool({
toolRef: "tool:module.name/ToolName",
inputSignature: [{ name: "request", type_ref: "type:module.name/Input" }],
outputType: "type:module.name/Output",
requiredGrants: ["network"],
run: async ({ request, context }) => {
return await runHostCode(request, context);
},
});
Exemple :
import { defineTool } from "@touba/sdk";
await defineTool({
toolRef: "tool:examples.search/SearchDatasets",
inputSignature: [{ name: "request", type_ref: "type:examples.search/SearchRequest" }],
outputType: "type:examples.search/SearchResult",
requiredGrants: ["network"],
run: async ({ request }) => {
return await searchDatasets(request);
},
});
Le SDK gère le protocole process côté handler. Le runtime reste l’autorité principale pour les grants, secrets, scopes, limites et payloads.
Exécuter avec manifest explicite
Forme :
touba run program.air.json \
--manifest touba.manifest.json \
--inputs-json '{"input":{"field":"value"}}' \
--trace-out trace.json
Exemple :
touba run search.air.json \
--manifest touba.manifest.json \
--inputs-json '{"request":{"query":"parks"}}' \
--trace-out trace.json
Le runtime refuse avant handler si le manifest ne satisfait pas le contrat AIR. Par défaut, la sortie standard affiche les messages show. Utilisez --output result pour afficher la valeur retournée, ou --output trace pour écrire la trace JSON sur la sortie standard.
Même si le manifest a été généré par touba prepare, il doit être fourni explicitement au runtime avec --manifest.
Vérifier la supply chain du handler
Pour un run strict, ajoutez un lock supply chain cohérent avec l’AIR, le manifest,
le handler, le SDK, l’identité déclarée handler_package, les fichiers de paquet
handler et les artefacts de dépendances déclarés :
touba run search.air.json \
--manifest touba.manifest.json \
--supply-chain-lock touba.lock.json \
--require-supply-chain-lock \
--inputs-json '{"request":{"query":"parks"}}'
Le lock ne donne aucun grant. Il refuse seulement un drift avant le lancement du handler.
Refus observables
Le runtime peut refuser si :
- aucun binding n’existe pour le tool ;
- le grant requis manque ;
- un secret requis manque ;
- le payload d’entrée ne respecte pas la signature ;
- le payload de sortie ne respecte pas le
gives; - le handler dépasse le timeout ;
- le payload dépasse la limite déclarée.
Diagnostiquer un handler en développement
Une erreur non contrôlée garde un diagnostic public borné, sans sa stack ni son message arbitraire. Pour trouver la ligne fautive dans un projet préparé :
touba run --project . --profile dev --handler-diagnostics diagnostic-local.jsonl
Ajoutez les entrées et providers nécessaires à votre programme. Le fichier
cible doit être nouveau. Sur macOS/Linux, il est créé en mode privé 0600,
sans écraser un fichier ou suivre un lien final. Il contient le code d'échec,
les identifiants run/appel, la classe d'exception et, avec le SDK, la ligne et
la colonne dans un fichier des arguments du handler (handler_arg_index).
Une fonction appelée dans un autre fichier peut ne pas fournir de position.
Ce canal n'enregistre ni message d'exception, ni stack brute, ni stderr,
ni payload ni valeur secrète. Limites : 4 KiB par réponse privée, 128 événements
et 64 KiB par fichier ; un avertissement signale un diagnostic incomplet.
Une donnée privée malformée est écartée sans devenir une sortie publique.
Le diagnostic n'atteste pas un effet métier et n'est pas exporté dans les
traces, l'API serveur ou SSE. Reproduisez ensuite le défaut avec un test métier
ciblé ; pour un diagnostic public maîtrisé, utilisez ToubaHandlerError.
L'option exige un run plan explicite de profil dev, résolu par --project
ou passé avec --run-plan. Production, lock obligatoire, profil durci et
Windows sont refusés ; l'option ne s'active pas via une variable d'environnement
ni un fichier .env. Ne publiez pas ce fichier de développement.
Périmètre runtime
Le tool binding fournit un chemin explicite entre contrat source et effet hôte : tool déclaré, binding manifest, handler, vérifications runtime et trace.
L’isolation de plateforme requise se configure par binding. Les systèmes de permissions complets, l’installation automatique de packages handlers, l’audit de vulnérabilités et la résolution de graphe de dépendances complètent le registry statique publié. Le runtime ne découvre pas les handlers automatiquement.