@vascend/talos 0.1.0

package/dist/tools/program.js

@@ -0,0 +1,567 @@
+// run_program: Programmatic Tool Calling su kernel JS persistente per sessione.
+//
+// Perche' esiste: una catena di N azioni strumentali costa N giri di modello, e
+// ogni risultato intermedio entra nel contesto anche quando serve solo come
+// input del passo successivo (caso documentato: 72 tool call senza completare
+// il task). Qui il modello scrive UN programma che chiama i tool come funzioni
+// (`await tools.read_file({...})`, `Promise.all` per il fan-out): i risultati
+// intermedi vivono nel kernel — contesto come variabile, non come cronologia —
+// e nel contesto entra solo cio' che il programma stampa o ritorna.
+//
+// Il kernel e' un processo figlio (bun/node/Electron-as-node) che sopravvive
+// alla singola chiamata: `state` e le assegnazioni globali persistono tra
+// esecuzioni della stessa sessione, come un REPL. Le tool call del programma
+// rientrano nel parent via protocollo JSON-line e passano dallo STESSO
+// ToolContext del turno corrente: il choke point dei permessi (confirm dei
+// singoli tool) resta intatto. Il programma in se' e' codice arbitrario con il
+// livello di fiducia di `bash`, quindi come bash e' dietro ctx.confirm.
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, realpathSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { invokeToolCall } from "../core/tool-executor.js";
+import { executionPathKey, executionTargetKey, localExecutionTarget } from "../core/execution-target.js";
+import { textFromMcpToolResult } from "../mcp/protocol.js";
+import { DISCOVERY_TOOL_NAMES } from "./discovery.js";
+import { normalizeToolInput } from "./normalize-input.js";
+import { programSyntaxError } from "./program-input.js";
+const DEFAULT_TIMEOUT_S = 120;
+const MAX_TIMEOUT_S = 600;
+// Tetto ai log e al valore di ritorno consegnati al modello: il resto e' gia'
+// nel kernel e si recupera con un programma successivo (state/paginazione).
+const MAX_LOG_CHARS = 20_000;
+const MAX_VALUE_CHARS = 20_000;
+// Kernel inattivo da troppo: si spegne da solo (lo stato si perde, il modello
+// viene avvisato alla prossima esecuzione dal fatto che state e' vuoto).
+const KERNEL_IDLE_MS = 10 * 60 * 1000;
+// Piu' sessioni vive (kingdoms): tetto ai processi kernel, il piu' vecchio muore.
+const MAX_KERNELS = 8;
+// Tetto all'output delle chiamate interne DENTRO GLI EVENTI verso l'host: il
+// kernel riceve sempre l'output integrale (e' il suo scopo), ma l'evento serve
+// alla chat, non al modello, e non deve gonfiare l'IPC.
+const NESTED_EVENT_OUTPUT_MAX = 16_000;
+// Id univoci per le chiamate annidate in tutto il processo: il seq del kernel
+// riparte a ogni reset e produrrebbe collisioni nella stessa chat.
+let nestedCallCounter = 0;
+// Tool non chiamabili dal programma: i meta-tool della discovery non servono
+// (dal kernel OGNI tool del registro e' gia' chiamabile per nome, anche quelli
+// on-demand) e run_program dentro run_program creerebbe solo ricorsione.
+const BRIDGE_DENYLIST = new Set([
+    ...DISCOVERY_TOOL_NAMES,
+    "run_program",
+    "execute",
+    // Questi due tool dipendono dai delta nativi della function call del
+    // provider. Invocarli dal kernel renderebbe atomico l'intero programma e
+    // falserebbe sia la partial commit sia la telemetria RAC.
+    "computer_control",
+    "computer_batch",
+]);
+// ---------------------------------------------------------------------------
+// Kernel script (processo figlio). Sorgente incorporato e scritto in un file
+// temporaneo content-addressed: niente asset da impacchettare in dist, stesso
+// comportamento sotto bun, node ed Electron main.
+// ---------------------------------------------------------------------------
+const KERNEL_SOURCE = `"use strict";
+const util = require("node:util");
+let buf = "";
+let seq = 0;
+const pending = new Map();
+const state = {};
+let inputData = {};
+
+function send(msg) { process.stdout.write(JSON.stringify(msg) + "\\n"); }
+
+function render(value) {
+  if (value === undefined) return "";
+  if (typeof value === "string") return value;
+  try { return util.inspect(value, { depth: 5, maxArrayLength: 200, maxStringLength: 8000 }); }
+  catch { return String(value); }
+}
+
+function callTool(name, args, structured = false) {
+  return new Promise((resolve, reject) => {
+    seq += 1;
+    pending.set(seq, { resolve, reject, structured });
+    send({ t: "call", seq, name, args: args === undefined ? {} : args });
+  });
+}
+
+// Qualsiasi proprieta' e' una funzione-tool: tools.read_file({...}),
+// tools["nome-con-trattini"]({...}). "then" escluso per non sembrare thenable.
+const tools = new Proxy({}, {
+  get(_t, prop) {
+    if (typeof prop !== "string" || prop === "then" || prop === "toJSON") return undefined;
+    if (prop === "$data") return inputData;
+    if (prop === "$result") return (name, args) => callTool(name, args, true);
+    return (args) => callTool(prop, args);
+  },
+});
+
+const fakeConsole = {};
+for (const level of ["log", "info", "warn", "error", "debug", "trace"]) {
+  fakeConsole[level] = (...parts) => send({
+    t: "log",
+    line: parts.map((p) => (typeof p === "string" ? p : render(p))).join(" "),
+  });
+}
+
+async function execute(msg) {
+  inputData = msg.data ?? {};
+  const AsyncFunction = (async () => {}).constructor;
+  try {
+    // require/process oscurati: e' un invito a passare dai tool (che portano i
+    // permessi), non un confine di sicurezza — il confine e' la conferma utente.
+    const fn = new AsyncFunction("tools", "state", "console", "require", "process", msg.code);
+    const value = await fn(tools, state, fakeConsole, undefined, undefined);
+    send({ t: "done", id: msg.id, value: render(value) });
+  } catch (err) {
+    send({ t: "done", id: msg.id, error: err instanceof Error ? (err.stack || err.message) : String(err) });
+  }
+}
+
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  buf += chunk;
+  let idx;
+  while ((idx = buf.indexOf("\\n")) >= 0) {
+    const line = buf.slice(0, idx);
+    buf = buf.slice(idx + 1);
+    if (!line.trim()) continue;
+    let msg;
+    try { msg = JSON.parse(line); } catch { continue; }
+    if (msg.t === "exec") void execute(msg);
+    else if (msg.t === "call_result") {
+      const p = pending.get(msg.seq);
+      if (!p) continue;
+      pending.delete(msg.seq);
+      if (p.structured) p.resolve(msg.result);
+      else if (msg.isError) p.reject(new Error(String(msg.output ?? "errore tool")));
+      else p.resolve(String(msg.output ?? ""));
+    }
+  }
+});
+// Il parent muore -> stdin si chiude -> il kernel esce: nessun orfano.
+process.stdin.on("end", () => process.exit(0));
+process.stdin.resume();
+`;
+function unrefStream(stream) {
+    stream?.unref?.();
+}
+function ensureKernelScript() {
+    const hash = createHash("sha256").update(KERNEL_SOURCE).digest("hex").slice(0, 12);
+    const dir = join(tmpdir(), "talos-program-kernel");
+    const path = join(dir, `kernel-${hash}.cjs`);
+    if (!existsSync(path)) {
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(path, KERNEL_SOURCE, "utf8");
+    }
+    return path;
+}
+class ProgramKernel {
+    key;
+    child = null;
+    stdoutBuf = "";
+    stderrTail = "";
+    nextExecId = 1;
+    current = null;
+    chain = Promise.resolve();
+    idleTimer = null;
+    constructor(key) {
+        this.key = key;
+    }
+    get alive() {
+        return this.child !== null && this.child.exitCode === null && !this.child.killed;
+    }
+    // Serializza le esecuzioni: il kernel e' uno solo e lo stato e' condiviso.
+    exec(code, ctx, timeoutMs, data) {
+        const run = this.chain.then(() => this.execNow(code, ctx, timeoutMs, data));
+        this.chain = run.catch(() => undefined);
+        return run;
+    }
+    kill() {
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = null;
+        }
+        const child = this.child;
+        this.child = null;
+        if (child && child.exitCode === null) {
+            try {
+                child.kill();
+            }
+            catch { /* gia' morto */ }
+        }
+        if (this.current) {
+            this.current.settle({ error: "kernel terminato", kernelLost: true });
+            this.current = null;
+        }
+    }
+    ensureChild(cwd) {
+        if (this.child && this.alive)
+            return this.child;
+        const script = ensureKernelScript();
+        const env = { ...process.env };
+        // Sotto Electron process.execPath e' l'app: la fuse runAsNode (attiva per
+        // requisito di build) la fa partire come Node puro.
+        if (process.versions["electron"])
+            env["ELECTRON_RUN_AS_NODE"] = "1";
+        const child = spawn(process.execPath, [script], { cwd, windowsHide: true, env, stdio: ["pipe", "pipe", "pipe"] });
+        child.stdout?.setEncoding("utf8");
+        child.stderr?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => { if (this.child === child)
+            this.onStdout(chunk); });
+        child.stderr?.on("data", (chunk) => {
+            this.stderrTail = (this.stderrTail + chunk).slice(-2000);
+        });
+        // Un EPIPE su stdin (kernel appena morto) non deve abbattere talos.
+        child.stdin?.on("error", () => { });
+        const fail = (reason) => {
+            if (this.child !== child)
+                return;
+            this.child = null;
+            if (this.current) {
+                this.current.settle({ error: reason, kernelLost: true });
+                this.current = null;
+            }
+        };
+        child.on("exit", () => {
+            const detail = this.stderrTail.trim();
+            fail(`il kernel e' uscito in modo inatteso${detail ? `: ${detail}` : ""}`);
+        });
+        child.on("error", (err) => fail(`kernel non avviabile: ${err.message}`));
+        this.child = child;
+        this.stdoutBuf = "";
+        this.stderrTail = "";
+        return child;
+    }
+    onStdout(chunk) {
+        this.stdoutBuf += chunk;
+        let idx;
+        while ((idx = this.stdoutBuf.indexOf("\n")) >= 0) {
+            const line = this.stdoutBuf.slice(0, idx);
+            this.stdoutBuf = this.stdoutBuf.slice(idx + 1);
+            if (!line.trim())
+                continue;
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            void this.onMessage(msg);
+        }
+    }
+    async onMessage(msg) {
+        const cur = this.current;
+        if (!cur)
+            return;
+        if (msg["t"] === "log") {
+            this.appendLog(cur, String(msg["line"] ?? ""));
+            return;
+        }
+        if (msg["t"] === "call") {
+            const seq = Number(msg["seq"]);
+            const name = String(msg["name"] ?? "");
+            const args = msg["args"];
+            const result = await this.dispatchTool(cur, name, args);
+            if (this.current !== cur)
+                return;
+            this.send({ t: "call_result", seq, output: result.output, isError: result.isError, result });
+            return;
+        }
+        if (msg["t"] === "done" && Number(msg["id"]) === cur.id) {
+            const error = msg["error"] === undefined ? undefined : String(msg["error"]);
+            cur.settle(error !== undefined ? { error } : { value: String(msg["value"] ?? "") });
+        }
+    }
+    // Esegue il tool richiesto dal programma con il ToolContext del turno: i
+    // permessi (confirm di write_file, bash, ...) valgono identici al dispatch
+    // diretto. Un errore diventa un'eccezione NEL programma, catturabile.
+    //
+    // Ogni chiamata interna viene anche EMESSA all'host come coppia annidata
+    // tool_call/tool_result (via ctx.emitToolEvent): la chat mostra cosa sta
+    // facendo il programma e i trigger che ascoltano gli eventi tool (pannello
+    // revisione, badge sui file, schede) scattano come per una call diretta.
+    async dispatchTool(cur, name, rawArgs) {
+        const id = "prog-" + (++nestedCallCounter);
+        const failure = (output) => ({ type: "tool_result", callId: id, output, isError: true });
+        if (cur.ctx.signal.aborted)
+            return failure("programma interrotto");
+        if (BRIDGE_DENYLIST.has(name))
+            return failure("il tool " + name + " non e' chiamabile da un programma");
+        const tool = cur.ctx.tools?.get(name);
+        if (tool?.requiresNativeCall)
+            return failure("il tool " + name + " richiede una chiamata nativa");
+        if (!tool)
+            return failure("strumento sconosciuto: " + name);
+        cur.callCounts.set(name, (cur.callCounts.get(name) ?? 0) + 1);
+        const call = { type: "tool_call", id, name, input: normalizeToolInput(rawArgs, tool.inputSchema) };
+        const result = await invokeToolCall(call, cur.ctx);
+        // Programs compute on the canonical result; only the model/UI view is compressed.
+        return result.content ? { ...result, output: textFromMcpToolResult({ content: result.content }) } : result;
+    }
+    appendLog(cur, line) {
+        if (cur.logChars >= MAX_LOG_CHARS) {
+            cur.logsTruncatedLines += 1;
+            return;
+        }
+        cur.logs.push(line);
+        cur.logChars += line.length + 1;
+    }
+    send(msg) {
+        try {
+            this.child?.stdin?.write(`${JSON.stringify(msg)}\n`);
+        }
+        catch { /* kernel morto tra dispatch e risposta: l'exit ha gia' chiuso il giro */ }
+    }
+    touchIdle() {
+        if (this.idleTimer)
+            clearTimeout(this.idleTimer);
+        this.idleTimer = setTimeout(() => kernels.dispose(this.key), KERNEL_IDLE_MS);
+        // I timer e il figlio non devono tenere in vita il processo talos a fine
+        // sessione: il kernel muore comunque alla chiusura di stdin.
+        this.idleTimer.unref?.();
+        this.child?.unref();
+        // Le pipe stdio sono Socket a runtime, ma tipizzate Writable/Readable:
+        // unref esiste e va chiamato, altrimenti tengono vivo l'event loop.
+        unrefStream(this.child?.stdin);
+        unrefStream(this.child?.stdout);
+        unrefStream(this.child?.stderr);
+    }
+    execNow(code, ctx, timeoutMs, data) {
+        return new Promise((resolve) => {
+            if (ctx.signal.aborted) {
+                resolve({ logs: "", logsTruncatedLines: 0, value: "", error: "programma interrotto", callCounts: new Map() });
+                return;
+            }
+            let child;
+            try {
+                child = this.ensureChild(ctx.cwd);
+            }
+            catch (err) {
+                resolve({
+                    logs: "", logsTruncatedLines: 0, value: "",
+                    error: `impossibile avviare il kernel: ${err.message}`,
+                    kernelLost: true, callCounts: new Map(),
+                });
+                return;
+            }
+            if (this.idleTimer) {
+                clearTimeout(this.idleTimer);
+                this.idleTimer = null;
+            }
+            const id = this.nextExecId;
+            this.nextExecId += 1;
+            let settled = false;
+            let timer = null;
+            const execution = new AbortController();
+            const cur = {
+                id, ctx: { ...ctx, signal: execution.signal },
+                logs: [], logChars: 0, logsTruncatedLines: 0,
+                callCounts: new Map(),
+                settle: (outcome) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    if (timer)
+                        clearTimeout(timer);
+                    ctx.signal.removeEventListener("abort", onAbort);
+                    if (this.current === cur)
+                        this.current = null;
+                    // Il timeout/kill del kernel deve fermare anche i tool nel parent.
+                    // A fine programma non possono sopravvivere chiamate non attese.
+                    execution.abort();
+                    if (!outcome.kernelLost)
+                        this.touchIdle();
+                    resolve({
+                        logs: cur.logs.join("\n"),
+                        logsTruncatedLines: cur.logsTruncatedLines,
+                        value: outcome.value ?? "",
+                        ...(outcome.error !== undefined ? { error: outcome.error } : {}),
+                        ...(outcome.kernelLost ? { kernelLost: true } : {}),
+                        callCounts: cur.callCounts,
+                    });
+                },
+            };
+            const onAbort = () => {
+                // Non c'e' interruzione pulita di un AsyncFunction in corsa: si uccide
+                // il processo. Meglio uno stato perso che un kernel zombie che continua
+                // a chiamare tool dopo lo stop dell'utente.
+                cur.settle({ error: "programma interrotto", kernelLost: true });
+                this.kill();
+            };
+            timer = setTimeout(() => {
+                cur.settle({
+                    error: `timeout dopo ${Math.round(timeoutMs / 1000)}s: il kernel e' stato terminato e lo stato e' perso. `
+                        + "Spezza il lavoro in programmi piu' brevi o alza timeout_s.",
+                    kernelLost: true,
+                });
+                this.kill();
+            }, timeoutMs);
+            ctx.signal.addEventListener("abort", onAbort, { once: true });
+            this.current = cur;
+            try {
+                // write=false e' solo backpressure (payload piccoli); un throw invece
+                // significa stdin gia' distrutto e va chiuso subito.
+                child.stdin?.write(`${JSON.stringify({ t: "exec", id, code, data })}\n`);
+            }
+            catch (err) {
+                cur.settle({ error: `kernel non raggiungibile: ${err.message}`, kernelLost: true });
+                this.kill();
+            }
+        });
+    }
+}
+class KernelStore {
+    byKey = new Map();
+    acquire(key) {
+        const existing = this.byKey.get(key);
+        if (existing) {
+            // Riordina per LRU: l'ultimo usato e' l'ultimo a morire.
+            this.byKey.delete(key);
+            this.byKey.set(key, existing);
+            return existing;
+        }
+        while (this.byKey.size >= MAX_KERNELS) {
+            const oldest = this.byKey.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.dispose(oldest);
+        }
+        const kernel = new ProgramKernel(key);
+        this.byKey.set(key, kernel);
+        return kernel;
+    }
+    dispose(key) {
+        const kernel = this.byKey.get(key);
+        if (!kernel)
+            return;
+        this.byKey.delete(key);
+        kernel.kill();
+    }
+    disposeAll() {
+        for (const key of [...this.byKey.keys()])
+            this.dispose(key);
+    }
+}
+const kernels = new KernelStore();
+// Esposto per i test e per gli host che vogliono spegnere i kernel (es. chiusura app).
+export function disposeProgramKernels() {
+    kernels.disposeAll();
+}
+function kernelKey(ctx) {
+    const target = ctx.executionTarget ?? localExecutionTarget();
+    // Il figlio usa cwd locale: realpath unifica alias e symlink, non workspace diversi.
+    const workspace = executionPathKey(target, realpathSync(ctx.cwd));
+    return JSON.stringify([executionTargetKey(target), workspace, ctx.sessionId ?? null]);
+}
+function clampTimeoutMs(raw) {
+    const s = typeof raw === "number" && Number.isFinite(raw) ? raw : DEFAULT_TIMEOUT_S;
+    return Math.min(Math.max(Math.floor(s), 1), MAX_TIMEOUT_S) * 1000;
+}
+function truncateValue(value) {
+    if (value.length <= MAX_VALUE_CHARS)
+        return value;
+    return `${value.slice(0, MAX_VALUE_CHARS)}\n[valore troncato a ${MAX_VALUE_CHARS} caratteri: `
+        + "salva il resto in state e leggilo a pezzi con un programma successivo]";
+}
+function callSummary(counts) {
+    if (!counts.size)
+        return "";
+    const parts = [...counts.entries()].map(([name, n]) => (n > 1 ? `${name}×${n}` : name));
+    return `(tool usati: ${parts.join(", ")})`;
+}
+function composeOutput(outcome) {
+    const sections = [];
+    if (outcome.logs)
+        sections.push(outcome.logs);
+    if (outcome.logsTruncatedLines > 0) {
+        sections.push(`[log troncati: ${outcome.logsTruncatedLines} righe omesse]`);
+    }
+    if (outcome.error !== undefined) {
+        sections.push(`errore programma: ${outcome.error}`);
+        sections.push(outcome.kernelLost
+            ? "(kernel terminato: `state` e le variabili globali sono persi)"
+            : "(il kernel e' vivo: `state` e le variabili globali sono conservati, correggi e riesegui)");
+        const summary = callSummary(outcome.callCounts);
+        if (summary)
+            sections.push(summary);
+        return { output: sections.join("\n"), isError: true };
+    }
+    sections.push(outcome.value ? `→ ${truncateValue(outcome.value)}` : "→ (nessun valore di ritorno)");
+    const summary = callSummary(outcome.callCounts);
+    if (summary)
+        sections.push(summary);
+    return { output: sections.join("\n"), isError: false };
+}
+export const runProgramTool = {
+    name: "run_program",
+    description: "Esegue un programma JavaScript in un kernel persistente della sessione, con i tool come funzioni async: "
+        + "`const src = await tools.read_file({path:\"src/a.ts\"})`. Tutti i tool del catalogo sono chiamabili per "
+        + "nome, anche quelli on-demand, senza tool_search. Usalo quando servono piu' azioni collegate "
+        + "(leggi-filtra-scrivi, fan-out con Promise.all, cicli su molti file): un programma sostituisce molte tool "
+        + "call e i risultati intermedi restano nel kernel, fuori dal contesto. `state` conserva valori tra "
+        + "esecuzioni; le assegnazioni senza const/let persistono; `return` produce il risultato; console.log per il "
+        + "progresso; un tool fallito lancia un'eccezione (try/catch). "
+        + "`await tools.$result(nome, argomenti)` restituisce output, structuredContent, content e isError senza perdere i dati. "
+        + "Passa script e testi multilinea nel parametro JSON data e leggili con tools.$data, senza annidarli nel codice. "
+        + "Richiede conferma dell'utente, come bash. "
+        + "Per una singola azione chiama il tool direttamente.",
+    schema: {
+        type: "object",
+        properties: {
+            code: {
+                type: "string",
+                description: "programma JavaScript (corpo di funzione async: await disponibile, return per il risultato)",
+            },
+            timeout_s: {
+                type: "number",
+                description: `tetto in secondi (default ${DEFAULT_TIMEOUT_S}, max ${MAX_TIMEOUT_S})`,
+            },
+            data: { type: "object", description: "Dati JSON del programma, accessibili con tools.$data; script e testi passano senza escaping JavaScript" },
+            reset: {
+                type: "boolean",
+                description: "riavvia il kernel della sessione prima di eseguire (state e globali persi)",
+            },
+        },
+        required: ["code"],
+    },
+    handler: async (input, ctx) => {
+        if (ctx.signal.aborted)
+            return { output: "programma interrotto", isError: true };
+        const code = String(input["code"] ?? "").trim();
+        if (!code) {
+            return { output: "indica `code`: il programma JavaScript da eseguire "
+                    + '(es. {"code":"const out = await tools.grep({pattern:\\"TODO\\"}); return out"})', isError: true };
+        }
+        const syntax = programSyntaxError(code);
+        if (syntax)
+            return syntax;
+        const supplied = input["data"];
+        if (supplied !== undefined && (!supplied || typeof supplied !== "object" || Array.isArray(supplied))) {
+            return { output: "data deve essere un oggetto JSON", isError: true };
+        }
+        let data;
+        try {
+            data = JSON.parse(JSON.stringify(supplied ?? {}));
+        }
+        catch {
+            return { output: "data deve essere serializzabile in JSON", isError: true };
+        }
+        const ok = await ctx.confirm("run_program", code + (supplied === undefined ? "" : "\n\n[data]\n" + JSON.stringify(data, null, 2)));
+        if (ctx.signal.aborted)
+            return { output: "programma interrotto", isError: true };
+        if (!ok)
+            return { output: "programma rifiutato dall'utente", isError: true };
+        const key = kernelKey(ctx);
+        if (input["reset"] === true)
+            kernels.dispose(key);
+        const kernel = kernels.acquire(key);
+        const outcome = await kernel.exec(code, ctx, clampTimeoutMs(input["timeout_s"]), data);
+        if (outcome.kernelLost)
+            kernels.dispose(key);
+        return composeOutput(outcome);
+    },
+};

package/dist/tools/protocol-catalog.d.ts

@@ -0,0 +1,12 @@
+import type { RegisteredTool, ToolContext, ToolDef, ToolHandlerOutput } from "../core/types.js";
+export type ProtocolRegistry = NonNullable<ToolContext["tools"]>;
+export interface ProtocolCatalog {
+    readonly revision: string;
+    readonly tools: ReadonlyMap<string, ToolDef>;
+    readonly capabilities: ReadonlyMap<string, readonly string[]>;
+}
+export declare function catalogRevision(registry: ProtocolRegistry): string;
+export declare function protocolCatalog(registry: ProtocolRegistry): ProtocolCatalog;
+export declare function nativeCall(tool: RegisteredTool): boolean;
+export declare function protocolResult(data: Record<string, unknown>, isError?: boolean): ToolHandlerOutput;
+export declare function protocolError(status: string, detail: string, fields?: Record<string, unknown>): ToolHandlerOutput;

package/dist/tools/protocol-catalog.js

@@ -0,0 +1,46 @@
+import { createHash } from "node:crypto";
+import { toolInventory } from "./discovery.js";
+import { NATIVE_CALL_TOOLS } from "./capabilities.js";
+const cache = new WeakMap();
+const identities = new WeakMap();
+let nextIdentity = 0;
+export function catalogRevision(registry) {
+    if (registry.revision)
+        return registry.revision;
+    // Older SDK hosts: include handler registration identity, not only schema text.
+    const rows = toolInventory(registry).map(def => {
+        const tool = registry.get(def.name);
+        if (tool && !identities.has(tool))
+            identities.set(tool, ++nextIdentity);
+        return [def.name, def.description, def.inputSchema, def.outputSchema, tool && identities.get(tool)];
+    }).sort((a, b) => String(a[0]).localeCompare(String(b[0])));
+    return createHash("sha256").update(JSON.stringify(rows)).digest("hex").slice(0, 20);
+}
+export function protocolCatalog(registry) {
+    const revision = catalogRevision(registry);
+    const previous = cache.get(registry);
+    if (previous?.revision === revision)
+        return previous;
+    const tools = new Map([...toolInventory(registry)].sort((a, b) => a.name.localeCompare(b.name))
+        .map(tool => [tool.name, tool]));
+    const capabilities = new Map();
+    for (const [name] of tools) {
+        for (const capability of registry.get(name)?.capabilities ?? []) {
+            if (!/^[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*)+$/.test(capability))
+                continue;
+            capabilities.set(capability, [...(capabilities.get(capability) ?? []), name]);
+        }
+    }
+    const catalog = { revision, tools, capabilities };
+    cache.set(registry, catalog);
+    return catalog;
+}
+export function nativeCall(tool) {
+    return tool.requiresNativeCall === true || NATIVE_CALL_TOOLS.has(tool.name);
+}
+export function protocolResult(data, isError = false) {
+    return { output: JSON.stringify(data), structuredContent: data, isError };
+}
+export function protocolError(status, detail, fields = {}) {
+    return protocolResult({ status, detail, ...fields }, true);
+}

package/dist/tools/ramification-tools.d.ts

@@ -0,0 +1,12 @@
+import type { Tool } from "../core/types.js";
+export declare const ramPlanTool: Tool;
+export declare const ramStatusTool: Tool;
+export declare const ramTakeTool: Tool;
+export declare const ramSubmitTool: Tool;
+export declare const ramAskTool: Tool;
+export declare const ramJudgeTool: Tool;
+export declare const ramProposeTool: Tool;
+export declare const ramDecideTool: Tool;
+export declare const ramTellTool: Tool;
+export declare const ramHearTool: Tool;
+export declare const ramificationTools: readonly Tool[];