Handler

Un handler implémente un tool dans le langage de votre application : JavaScript avec @touba/sdk ou Python avec touba_sdk.

Étape	JavaScript	Python
Installer	touba sdk install javascript	touba sdk install python
Définir le handler	defineTool	define_tool
Adapter la fonction métier	run({ request, context })	run(request, context)
Tester et exécuter	Tutoriel JavaScript	Tutoriel Python

Les extraits ci-dessous illustrent l’API JavaScript. Pour obtenir un fichier complet relié à votre tool, choisissez le langage dans le projet puis lancez touba prepare --mode write.

Le handler n’est pas la source d’autorité principale. Le runtime vérifie le contrat avant et après son appel.

Forme SDK

handler.mjs

import { defineTool } from "@touba/sdk";

await defineTool({
  toolRef: "tool:module.name/ToolName",
  inputSignature: [{ name: "request", type_ref: "type:module.name/Input" }],
  outputType: "type:module.name/Output",
  run: async ({ request, context }) => {
    return await runHostCode(request, context);
  },
});

toolRef identifie le tool attendu. La fonction métier reçoit request et context, pendant que le SDK gère l’enveloppe protocolaire.

Cas simple

search_datasets.handler.mjs

import { defineTool } from "@touba/sdk";

await defineTool({
  toolRef: "tool:examples.tool_simple/SearchDatasets",
  inputSignature: [{ name: "request", type_ref: "type:examples.tool_simple/DatasetSearchRequest" }],
  outputType: "type:examples.tool_simple/DatasetSearchResult",
  requiredGrants: ["network"],
  run: async ({ request }) => {
    const result = await searchDatasets(request.query);

    return {
      title: result.title,
    };
  },
});

Le handler exécute l’appel concret. Le runtime reste responsable de vérifier que l’entrée correspond au takes et que la sortie correspond au gives.

Cas avancé

summarize_with_context.handler.mjs

import { defineTool } from "@touba/sdk";

await defineTool({
  toolRef: "tool:examples.tool_advanced/SummarizeWithContext",
  inputSignature: [{ name: "request", type_ref: "type:examples.tool_advanced/SearchRequest" }],
  outputType: "type:examples.tool_advanced/Summary",
  requiredGrants: ["network", "secret_read", "memory_read"],
  requiredSecretHandles: ["LLM_API_KEY"],
  run: async ({ request, context }) => {
    const apiKey = context.env.LLM_API_KEY;
    const knowledge = await readProjectKnowledge(request.query);
    const summary = await callLlm(apiKey, {
      query: request.query,
      context: knowledge,
    });

    return {
      text: summary.text,
    };
  },
});

Ce cas montre un handler qui consomme une valeur de secret injectée par l’environnement minimal du runtime et appelle un backend hôte.

La valeur du secret ne doit pas être écrite dans la sortie, la trace, le prompt affiché ou les erreurs.

Ce que le handler absorbe

Le handler garde les détails non portables hors du fichier .tb :

• client HTTP ;
• SDK fournisseur ;
• accès base de données ;
• format spécifique d’une API ;
• adaptation d’un backend existant.

Touba garde le contrat dans le source et l’AIR ; le handler garde l’effet réel côté hôte.

Supply chain

Un handler peut être rattaché à un lock supply chain. Le lock vérifie son chemin, son digest, sa commande, son protocole SDK et son identité handler_package. Avec l’extension artefacts de dépendances (SC-2), il peut aussi vérifier les fichiers de paquet handler et les artefacts de dépendances déclarés sous cette identité.

Cette identité aide à organiser les handlers sans scan du workspace. Elle n’est pas une registry, une signature, une installation de package ou une preuve que le handler est sûr.

Contrat runtime et distribution

• Le handler reste du code hôte à auditer.
• Le runtime reste l’autorité sur les checks de contrat.
• Un handler autorisé relève aussi des pratiques normales de revue et de sécurité hôte.
• La résolution de graphe de dépendances, l’audit de vulnérabilités et l’installation automatique de packages handlers complètent le registry statique publié.