@vascend/talos 0.1.0

package/dist/tools/discovery.js

@@ -0,0 +1,205 @@
+export const DISCOVERY_TOOL_NAMES = new Set([
+    "tool_list",
+    "tool_search",
+    "tool_describe",
+    "tool_invoke",
+]);
+// tool_search lists, finds and activates tools. The older entry points remain
+// callable for integrations and saved sessions, without occupying every prompt.
+export const LEGACY_DISCOVERY_TOOL_NAMES = new Set([
+    "tool_list", "tool_describe", "tool_invoke",
+]);
+// Primitives needed throughout a task, including resuming and checking work.
+// Keep these available in CLI and Horizon; optional capabilities stay discoverable.
+export const ESSENTIAL_TOOL_NAMES = new Set([
+    "tool_search",
+    "read_file", "write_file", "edit_file",
+    "bash", "bash_output", "run_program", "output_page", "recall", "ask_user",
+    "vascend_plan", "vascend_mark", "vascend_status",
+    "workspace_sessions",
+    "team_engage",
+]);
+// The terminal handles routine discovery. Specialized tools remain callable
+// through tool_search/run_program without sending their schemas on every turn.
+export const CLI_DIRECT_TOOL_NAMES = new Set([
+    ...ESSENTIAL_TOOL_NAMES, "skill_search", "skill_load",
+]);
+export const FILE_DISCOVERY_TOOL_NAMES = ["list_dir", "glob", "grep", "file_activity"];
+// Tool esposti DIRETTAMENTE nel profilo Horizon, oltre ai meta-tool. Tutto il
+// resto resta nel catalogo, scopribile con tool_search.
+//
+// Perche' un hot set e non solo i meta-tool: con la sola discovery ogni azione
+// reale costa da due a tre tool call (search -> eventuale describe -> invoke).
+// Su un lavoro di venti azioni sono cinquanta chiamate al posto di venti, e il
+// giro finisce il proprio budget di turni prima di completare il task. Il
+// risparmio di token nel prompt e' inoltre apparente: i loro schemi entrano nel
+// prefisso cacheabile una volta, mentre ogni risposta di tool_search ripaga lo
+// stesso schema a ogni ricerca, fuori dalla cache.
+//
+// Il criterio di ammissione e' duplice:
+//   1. lavoro quotidiano: leggere, scrivere, modificare, cercare, eseguire;
+//   2. tool CITATI dai messaggi dell'harness (marker di paginazione, pack di
+//      memoria, esito di bash in background): se il testo che il modello legge
+//      nomina un tool, quel tool deve essere invocabile senza una discovery.
+export const HORIZON_DIRECT_TOOL_NAMES = new Set([
+    ...ESSENTIAL_TOOL_NAMES,
+    // lavoro quotidiano
+    "read_file",
+    "write_file",
+    "edit_file",
+    "bash",
+    // Programmatic Tool Calling: N azioni collegate in UN turno, con i risultati
+    // intermedi nel kernel invece che nel contesto. E' l'antidoto all'inflazione
+    // di tool call (il caso da 72 chiamate senza completare): dietro discovery
+    // non verrebbe mai scelto proprio nei lavori lunghi in cui serve.
+    "run_program",
+    // citati dai messaggi dell'harness
+    "output_page",
+    "bash_output",
+    "recall",
+    // Il piano E' un'interfaccia: in Horizon i passaggi compaiono in tempo reale
+    // nella board affiancata alla chat, dove l'utente li vede e li modifica.
+    // Tenere questi due nel catalogo significava board vuota, perche' il modello
+    // pianifica solo se pianificare e' a portata di mano.
+    "vascend_plan",
+    "vascend_mark",
+    // Chiedere una mano deve essere a portata di mano, per lo stesso motivo per
+    // cui lo e' pianificare: un modello ingaggia dei collaboratori solo se
+    // ingaggiarli e' una mossa che ha davanti, non qualcosa da scoprire con
+    // tool_search mentre sta gia' decidendo come procedere. Con questi nel
+    // catalogo l'agente o faceva tutto da solo, o si affidava alla vecchia
+    // delega automatica. Stessa cosa per parlarci: una squadra che non si puo'
+    // interpellare senza una discovery non e' una squadra.
+    "team_engage",
+    "team_say",
+    "team_inbox",
+    // Dove e' arrivato un piano lungo: e' la prima domanda di una sessione che
+    // riprende un lavoro a rami, e deve poterla fare senza cercare il tool.
+    "ram_status",
+    // E il piano a rami deve stare accanto a vascend_plan, non dietro una
+    // discovery: se l'unica pianificazione a portata di mano e' quella dei
+    // passaggi di questa sessione, un lavoro lungo verra' sempre spezzato in
+    // passaggi di questa sessione. La scelta fra i due la decide la durata del
+    // lavoro, e va potuta fare nel momento in cui si pianifica.
+    "ram_plan",
+    // Lettura del web: leggere una fonte e' un gesto quotidiano quanto leggere un
+    // file. Dietro una discovery il modello preferiva indovinare invece di leggere.
+    // Sono gli strumenti dell'host (smart fetch), non il web_fetch del core.
+    "smart_fetch",
+    "smart_fetch_many",
+    // Il browser interno si APRE da qui; gli altri strumenti browser restano
+    // dietro la discovery e vengono nominati dalla descrizione di browser_open.
+    "browser_open",
+    // Excalidraw MCP: il modello deve poter disegnare subito. Lasciarli dietro
+    // tool_search ricreerebbe il ciclo discovery -> schema -> invoke a ogni
+    // revisione e renderebbe improbabile l'uso del checkpoint incrementale.
+    "read_me",
+    "create_view",
+    // read_view va accanto a create_view, non dietro una discovery. La guida di
+    // read_me e il blocco di sistema dicono "ALWAYS call read_view before
+    // updating a whiteboard you did not just write": un obbligo che costa una
+    // tool_search ogni volta viene disatteso, e disattenderlo qui significa
+    // SOVRASCRIVERE le modifiche manuali dell'utente — esattamente il danno che
+    // quella guida esiste per evitare. Un tool che il prompt rende obbligatorio
+    // deve essere a portata di chiamata.
+    "read_view",
+    "mermaid_to_excalidraw",
+    // Visual Creation Suite dell'host Horizon. La guida widget usa un nome
+    // distinto da read_me (riservato a Excalidraw) e la consegna deve essere
+    // invocabile senza il giro tool_search -> tool_describe -> tool_invoke.
+    "widget_read_me",
+    "show_widget",
+    "visualize",
+    // DLACT: cercare e usare uno strumento custom e' quotidiano; crearlo e
+    // promuoverlo (dlact_forge, dlact_promote) restano nel catalogo, sono rari.
+    "dlact_search",
+    "dlact_invoke",
+    // Computer Use dell'host Horizon. La catena reale e' una sola: trovare
+    // l'applicazione, collegarla, leggere i controlli, agire. Dietro la discovery
+    // OGNI passo costava una tool_search con lo schema intero: in una sessione su
+    // Spotify sono state sei ricerche di catalogo su trentatre turni, e nel
+    // frattempo il modello ha ripiegato su tasklist via bash e su click a
+    // coordinate indovinate. Il resto (snapshot, click, type, drag, wait, key,
+    // scroll, launch, detach) resta scopribile ed e' nominato da questi.
+    "computer_processes",
+    "computer_launch",
+    "computer_attach",
+    "computer_snapshot",
+    "computer_inspect",
+    "computer_wait",
+    // MCP-RAC deve essere nel prefisso iniziale: se resta deferred il modello
+    // paga una tool_search prima della prima action e tende a ripiegare su
+    // run_program, perdendo i delta nativi che costituiscono la frontiera di
+    // partial commit.
+    "computer_control",
+    "computer_activate",
+    "computer_fill",
+    "computer_batch",
+]);
+// Inventario autoritativo: un tool diretto e uno deferred sono entrambi
+// disponibili. In precedenza list/search guardavano soltanto catalog(), quindi
+// una verifica esplicita di "widget" rispondeva falsamente che show_widget non
+// esisteva proprio perche' era gia' diretto. Manteniamo la compatibilita' con i
+// vecchi host che non espongono ancora defs().
+export function toolInventory(tools) {
+    const direct = typeof tools.defs === "function" ? tools.defs() : [];
+    const byName = new Map();
+    for (const tool of [...direct, ...tools.catalog()])
+        byName.set(tool.name, tool);
+    return [...byName.values()];
+}
+// Vista compatta dell'intero registro. Non copia ne' attiva i tool: rende
+// semplicemente consultabile cio' che il modello puo davvero usare.
+export const toolListTool = {
+    name: "tool_list",
+    description: "Elenca tutti i tool disponibili, sia diretti sia on demand. Usa tool_describe per lo schema.",
+    schema: {
+        type: "object",
+        properties: {
+            limit: { type: "number", description: "numero massimo di nomi (default 100)" },
+            offset: { type: "integer", minimum: 0, description: "riprende l'inventario da next_offset (default 0)" },
+        },
+    },
+    handler: async (input, ctx) => {
+        if (!ctx.tools)
+            return "catalogo non disponibile in questo contesto";
+        const requested = typeof input["limit"] === "number" && Number.isFinite(input["limit"]) ? Math.floor(input["limit"]) : 100;
+        const limit = Math.max(1, Math.min(requested, 200));
+        const rawOffset = input["offset"] ?? 0;
+        if (typeof rawOffset !== "number" || !Number.isSafeInteger(rawOffset) || rawOffset < 0) {
+            return { output: "errore: offset deve essere un intero non negativo", isError: true };
+        }
+        const offset = rawOffset;
+        const catalog = [...toolInventory(ctx.tools)].sort((a, b) => a.name.localeCompare(b.name));
+        const end = Math.min(offset + limit, catalog.length);
+        const truncated = end < catalog.length;
+        return JSON.stringify({
+            total: catalog.length,
+            tools: catalog.slice(offset, end).map((tool) => tool.name),
+            truncated,
+            ...(truncated || offset ? { next_offset: truncated ? end : null } : {}),
+        });
+    },
+};
+export const toolDescribeTool = {
+    name: "tool_describe",
+    description: "Restituisce descrizione e schema di un tool trovato con tool_list o tool_search.",
+    schema: {
+        type: "object",
+        properties: {
+            name: { type: "string", description: "nome esatto del tool" },
+        },
+        required: ["name"],
+    },
+    handler: async (input, ctx) => {
+        if (!ctx.tools)
+            return "catalogo non disponibile in questo contesto";
+        const name = String(input["name"] ?? "").trim();
+        if (!name)
+            return "errore: nome strumento mancante";
+        const found = toolInventory(ctx.tools).find((tool) => tool.name === name);
+        if (!found)
+            return `strumento non disponibile: ${name} (usa tool_list o tool_search)`;
+        return JSON.stringify(found, null, 2);
+    },
+};

package/dist/tools/execute.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from "../core/types.js";
+export declare const executeTool: Tool;

package/dist/tools/execute.js

@@ -0,0 +1,73 @@
+import { randomUUID } from "node:crypto";
+import { invokeToolCall } from "../core/tool-executor.js";
+import { catalogRevision, nativeCall, protocolCatalog, protocolError } from "./protocol-catalog.js";
+const RECURSIVE = new Set(["execute", "run_program", "tool_invoke"]);
+export const executeTool = {
+    name: "execute",
+    description: "Execute a known contract using the revision returned by resolve. mode=call invokes tool(args) "
+        + "directly without a JS kernel; prefer it for shell scripts and file edits. mode=program runs async JavaScript with tools, state, console and return "
+        + "in a persistent kernel; await all operations, return only useful output. Tools return text; "
+        + "tools.$result(name,args) preserves structuredContent/content/isError. Native-only tools must be called "
+        + "directly. Pass scripts and multiline text in data, read via tools.$data, instead of embedding them in code. "
+        + "A stale_contract error requires resolving again; never replay completed effects blindly.",
+    schema: { type: "object", properties: {
+            mode: { type: "string", enum: ["call", "program"] }, revision: { type: "string" },
+            tool: { type: "string" }, args: { type: "object" }, code: { type: "string" },
+            data: { type: "object", description: "Program input as JSON, available at tools.$data; keeps scripts/text out of JavaScript string literals" },
+            timeout_s: { type: "number" }, reset: { type: "boolean" },
+        }, required: ["mode", "revision"] },
+    handler: async (input, ctx) => {
+        if (ctx.signal.aborted)
+            return protocolError("cancelled", "Execution cancelled.");
+        if (!ctx.tools)
+            return protocolError("unavailable", "Tool registry unavailable.");
+        const registry = ctx.tools;
+        const revision = input["revision"];
+        if (typeof revision !== "string" || revision !== catalogRevision(registry)) {
+            return protocolError("stale_contract", "Resolve the needed contracts before execution. No operation started.");
+        }
+        const mode = input["mode"];
+        const check = (name) => {
+            if (catalogRevision(registry) !== revision)
+                return "stale_contract: resolve again; earlier operations may already have completed";
+            const tool = registry.get(name);
+            if (!tool || !protocolCatalog(registry).tools.has(name))
+                return `unavailable: ${name}`;
+            if (nativeCall(tool))
+                return `native_required: call ${name} directly`;
+            return undefined;
+        };
+        // Run inside the common executor, after hooks and before every handler.
+        const guarded = { ...ctx, guardToolCall: call => {
+                ctx.guardToolCall?.(call);
+                const problem = check(call.name);
+                if (problem)
+                    throw new Error(problem);
+            } };
+        if (mode === "call") {
+            if (typeof input["tool"] !== "string" || !input["tool"].trim() || input["code"] !== undefined || input["data"] !== undefined
+                || input["args"] !== undefined && (input["args"] === null || typeof input["args"] !== "object" || Array.isArray(input["args"]))) {
+                return protocolError("invalid_input", "call requires a tool name and object args; code and data belong to program mode.");
+            }
+            const name = input["tool"].trim();
+            if (RECURSIVE.has(name))
+                return protocolError("invalid_input", "Use program mode for code; do not nest execution wrappers.");
+            const error = check(name);
+            if (error)
+                return protocolError("unavailable", error);
+            return invokeToolCall({ type: "tool_call", id: "exec-" + randomUUID(), name,
+                input: (input["args"] ?? {}) }, guarded);
+        }
+        if (mode !== "program" || typeof input["code"] !== "string" || !input["code"].trim()
+            || input["tool"] !== undefined || input["args"] !== undefined) {
+            return protocolError("invalid_input", "program requires nonempty code; tool and args belong to call mode.");
+        }
+        const error = check("run_program");
+        if (error)
+            return protocolError("unavailable", error);
+        // The existing executor still owns hooks, permissions, media and cancellation.
+        // Check catalog freshness again at each bridge call, including after an await.
+        return invokeToolCall({ type: "tool_call", id: "exec-" + randomUUID(), name: "run_program",
+            input: { code: input["code"], data: input["data"], timeout_s: input["timeout_s"], reset: input["reset"] } }, guarded);
+    },
+};

package/dist/tools/normalize-input.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Riconduce l'input di una tool call alla forma dichiarata dal suo schema.
+ * Non lancia mai: un input inutilizzabile diventa `{}` e il tool produrra' il
+ * proprio errore diagnostico.
+ */
+export declare function normalizeToolInput(raw: unknown, schema?: Readonly<Record<string, unknown>>): Record<string, unknown>;
+/**
+ * Elenco leggibile delle chiavi effettivamente ricevute, per messaggi d'errore
+ * che dicano al modello cosa ha sbagliato invece di un "parametro mancante"
+ * secco (che lo porta a ritentare identico).
+ */
+export declare function describeReceivedKeys(input: unknown): string;
+/**
+ * Errore diagnostico standard per un parametro obbligatorio mancante: dice il
+ * parametro atteso, cosa e' arrivato e un esempio di chiamata corretta.
+ */
+export declare function missingParamError(param: string, input: unknown, example: string): string;

package/dist/tools/normalize-input.js

@@ -0,0 +1,174 @@
+// Normalizzazione degli argomenti di una tool call. Modulo PURO.
+//
+// Perche' esiste: i modelli non consegnano sempre gli argomenti nella forma
+// dichiarata dallo schema. Le deviazioni osservate in produzione sono sempre le
+// stesse tre:
+//
+//   1. impacchettamento: {"args": "{\"command\":\"...\"}"} invece di
+//      {"command": "..."} (tipico quando lo schema di un parametro e' `object`
+//      senza properties, o quando un gateway ri-serializza la chiamata);
+//   2. annidamento: {"args": {"args": {...}}};
+//   3. tipi stringati: {"page": "3"} per un parametro dichiarato number,
+//      {"castles": "[...]"} per uno dichiarato array.
+//
+// Senza normalizzazione il tool riceve {} , risponde "parametro mancante", e il
+// modello ritenta la stessa chiamata in un ciclo che brucia turni senza mai
+// completare il task. Qui l'input viene ricondotto allo schema una volta sola,
+// nel punto di dispatch, per TUTTI i tool.
+// Chiavi usate dai modelli per impacchettare gli argomenti veri. Vengono
+// srotolate SOLO se il tool non dichiara quella property nel proprio schema
+// (tool_invoke, per esempio, ha un `args` legittimo).
+const WRAPPER_KEYS = [
+    "args",
+    "arguments",
+    "argument",
+    "input",
+    "inputs",
+    "parameters",
+    "params",
+    "kwargs",
+    "tool_input",
+];
+// Tetto agli srotolamenti: protegge da input costruiti in modo patologico.
+const MAX_UNWRAP_DEPTH = 3;
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// Parsing tollerante: ritorna il valore solo se il JSON e' valido.
+function parseJson(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return undefined;
+    if (!/^[[{"]|^-?\d|^true$|^false$|^null$/.test(trimmed))
+        return undefined;
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return undefined;
+    }
+}
+// Le properties dichiarate dallo schema del tool (vuoto se lo schema non le
+// dichiara: in quel caso nessuna coercizione tipata, solo lo srotolamento).
+function schemaProperties(schema) {
+    const props = schema?.["properties"];
+    return isPlainObject(props) ? props : {};
+}
+function declaredType(prop) {
+    if (!isPlainObject(prop))
+        return "";
+    const t = prop["type"];
+    if (typeof t === "string")
+        return t;
+    // union ["string","null"]: conta il primo tipo concreto
+    if (Array.isArray(t)) {
+        const first = t.find((x) => typeof x === "string" && x !== "null");
+        return typeof first === "string" ? first : "";
+    }
+    return "";
+}
+// Riconduce un valore stringa al tipo dichiarato dallo schema. Non forza nulla:
+// se la conversione non e' certa, il valore originale resta intatto.
+function coerceValue(value, type) {
+    if (typeof value !== "string")
+        return value;
+    if (type === "object" || type === "array") {
+        const parsed = parseJson(value);
+        if (type === "object" && isPlainObject(parsed))
+            return parsed;
+        if (type === "array" && Array.isArray(parsed))
+            return parsed;
+        return value;
+    }
+    if (type === "number" || type === "integer") {
+        const trimmed = value.trim();
+        if (!trimmed)
+            return value;
+        const n = Number(trimmed);
+        return Number.isFinite(n) ? n : value;
+    }
+    if (type === "boolean") {
+        const v = value.trim().toLowerCase();
+        if (v === "true")
+            return true;
+        if (v === "false")
+            return false;
+        return value;
+    }
+    return value;
+}
+// Srotola un livello di impacchettamento. Ritorna null se non c'e' nulla da
+// srotolare a questo livello.
+function unwrapOnce(input, known) {
+    for (const key of WRAPPER_KEYS) {
+        if (!(key in input))
+            continue;
+        // Il tool dichiara questa property: e' un argomento vero, non un involucro.
+        if (key in known)
+            continue;
+        const raw = input[key];
+        const value = typeof raw === "string" ? parseJson(raw) : raw;
+        if (!isPlainObject(value))
+            continue;
+        const rest = { ...input };
+        delete rest[key];
+        // Gli argomenti interni vincono su quelli esterni: sono la forma esplicita
+        // che il modello intendeva passare al tool.
+        return { ...rest, ...value };
+    }
+    return null;
+}
+/**
+ * Riconduce l'input di una tool call alla forma dichiarata dal suo schema.
+ * Non lancia mai: un input inutilizzabile diventa `{}` e il tool produrra' il
+ * proprio errore diagnostico.
+ */
+export function normalizeToolInput(raw, schema) {
+    const known = schemaProperties(schema);
+    // L'intera call consegnata come stringa JSON.
+    let current = raw;
+    if (typeof current === "string")
+        current = parseJson(current);
+    if (!isPlainObject(current))
+        return {};
+    let out = current;
+    for (let i = 0; i < MAX_UNWRAP_DEPTH; i += 1) {
+        const next = unwrapOnce(out, known);
+        if (!next)
+            break;
+        out = next;
+    }
+    // Coercizione tipata sulle property dichiarate.
+    let coerced = null;
+    for (const [key, value] of Object.entries(out)) {
+        const type = declaredType(known[key]);
+        if (!type)
+            continue;
+        const next = coerceValue(value, type);
+        if (next !== value) {
+            coerced = coerced ?? { ...out };
+            coerced[key] = next;
+        }
+    }
+    return coerced ?? out;
+}
+/**
+ * Elenco leggibile delle chiavi effettivamente ricevute, per messaggi d'errore
+ * che dicano al modello cosa ha sbagliato invece di un "parametro mancante"
+ * secco (che lo porta a ritentare identico).
+ */
+export function describeReceivedKeys(input) {
+    if (!isPlainObject(input))
+        return typeof input === "undefined" ? "nessuna" : `valore ${typeof input}`;
+    const keys = Object.keys(input);
+    return keys.length ? keys.join(", ") : "nessuna";
+}
+/**
+ * Errore diagnostico standard per un parametro obbligatorio mancante: dice il
+ * parametro atteso, cosa e' arrivato e un esempio di chiamata corretta.
+ */
+export function missingParamError(param, input, example) {
+    return (`errore: parametro \`${param}\` mancante o vuoto. ` +
+        `Chiavi ricevute: ${describeReceivedKeys(input)}. ` +
+        `Passa gli argomenti come oggetto piatto, es. ${example}`);
+}

package/dist/tools/output-artifact.d.ts

@@ -0,0 +1,3 @@
+import type { ToolContext, ToolHandlerOutput } from "../core/types.js";
+/** Scoped artifact reads, with bounded search/slices and a canonical structured route for programs. */
+export declare function outputArtifact(input: Record<string, unknown>, ctx: ToolContext): ToolHandlerOutput;

package/dist/tools/output-artifact.js

@@ -0,0 +1,80 @@
+import { ToolOutputStore } from "../core/tool-result-store.js";
+import { readTeamHandoff } from "../vascend/team-handoff.js";
+import { teamForSession, teamByKingdom } from "../vascend/team-session.js";
+import { pageOf } from "./pagination.js";
+import { createHash } from "node:crypto";
+/** Scoped artifact reads, with bounded search/slices and a canonical structured route for programs. */
+export function outputArtifact(input, ctx) {
+    const id = String(input["id"] ?? "");
+    const fail = (output) => ({ output, isError: true });
+    if (!ctx.sessionDir || !ctx.sessionId)
+        return fail(`archivio non disponibile in questo contesto: ${id}`);
+    const own = ctx.roomStoreId ?? ctx.sessionId;
+    const scope = String(input["scope"] ?? own);
+    const team = ctx.kingdom?.id ? teamByKingdom(ctx.kingdom.id) : teamForSession(ctx.sessionId);
+    const saved = readTeamHandoff(ctx.sessionDir, ctx.sessionId, scope) ?? readTeamHandoff(ctx.sessionDir, ctx.sessionId);
+    const scopes = new Set([own, ctx.sessionId, ctx.kingdom?.id, team?.id, saved?.id,
+        ...(team?.members ?? []).flatMap((member) => (member.artifacts ?? []).map((ref) => ref.scope)),
+        ...(saved?.members ?? []).flatMap((member) => (member.artifacts ?? []).map((ref) => ref.scope))]);
+    if (!scopes.has(scope))
+        return fail("scope non associato a questa sessione o al suo team");
+    const source = ToolOutputStore.open(ctx.sessionDir, scope);
+    const text = source.text(id);
+    let entry = source.entry(id);
+    if (text === null || !entry)
+        return fail(`risultato archiviato non trovato: ${id} (riesegui lo strumento)`);
+    if (scope !== own) {
+        // Import into the reader's scope so subsequent pages and compaction use an unambiguous local id.
+        const importKey = createHash("sha256").update(JSON.stringify([scope, id, entry.sha256 ?? entry.at])).digest("hex");
+        entry = ToolOutputStore.open(ctx.sessionDir, own).put(`import-${importKey}`, entry.name, text, source.result(id) ?? undefined);
+        if (!entry)
+            return fail("impossibile conservare il riferimento condiviso nella sessione");
+    }
+    const ref = { id: entry.id, scope: own, name: entry.name, sha256: entry.sha256 ?? "", chars: entry.chars };
+    const meta = { talosArtifact: ref, talosRetrievedId: entry.id };
+    if (input["format"] === "metadata")
+        return { output: JSON.stringify(ref), structuredContent: ref, _meta: meta };
+    if (input["format"] === "structured") {
+        const canonical = source.result(id);
+        let data = canonical?.structuredContent;
+        if (!data) {
+            try {
+                data = { value: JSON.parse(text) };
+            }
+            catch {
+                return fail("questo artefatto non contiene dati strutturati: usa page, query oppure offset/limit");
+            }
+        }
+        return { output: `Dati strutturati di ${entry.id} disponibili in structuredContent (tools.$result).`,
+            structuredContent: data, _meta: meta };
+    }
+    const bounded = (value, fallback, max) => typeof value === "number" && Number.isFinite(value) ? Math.min(max, Math.max(0, Math.floor(value))) : fallback;
+    const offset = bounded(input["offset"], 0, text.length);
+    const limit = Math.max(1, bounded(input["limit"], 8000, 30000));
+    if (typeof input["query"] === "string" && input["query"].length) {
+        const query = input["query"];
+        const matches = [];
+        let cursor = offset, chars = 0;
+        while (matches.length < 50 && chars < limit) {
+            const at = text.indexOf(query, cursor);
+            if (at < 0) {
+                cursor = text.length;
+                break;
+            }
+            const start = Math.max(0, at - 120);
+            const excerpt = text.slice(start, Math.min(text.length, at + query.length + 240, start + limit - chars));
+            matches.push({ offset: at, text: excerpt });
+            chars += excerpt.length;
+            cursor = at + Math.max(1, query.length);
+        }
+        const data = { ...ref, matches, next_offset: cursor < text.length ? cursor : null };
+        return { output: JSON.stringify(data), structuredContent: data, _meta: meta };
+    }
+    if (input["offset"] !== undefined || input["limit"] !== undefined) {
+        const end = Math.min(text.length, offset + limit);
+        const data = { ...ref, offset, next_offset: end < text.length ? end : null, text: text.slice(offset, end) };
+        return { output: JSON.stringify(data), structuredContent: data, _meta: meta };
+    }
+    const page = Math.max(1, bounded(input["page"], 1, Number.MAX_SAFE_INTEGER));
+    return { output: pageOf(text, `${entry.name} archiviato`, page, entry.id), _meta: meta };
+}

package/dist/tools/pagination.d.ts

@@ -0,0 +1,15 @@
+import type { ToolContext } from "../core/types.js";
+declare class PageStore {
+    private readonly map;
+    private readonly order;
+    private seq;
+    store(text: string, label: string): string;
+    totalPages(id: string): number;
+    page(id: string, page: number): string | null;
+}
+export declare function stripPageMarkers(text: string): string;
+export declare function pageOf(text: string, label: string, page: number, id: string): string;
+export declare const pageStore: PageStore;
+export declare function paginate(text: string, label?: string, ctx?: ToolContext): string;
+export declare function isPaginated(output: string): boolean;
+export {};