@vascend/talos 0.1.0

package/dist/core/storage-retention.js

@@ -0,0 +1,227 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { talosConfigDir } from "./env-paths.js";
+import { withLockSync } from "../vascend/file-lock.js";
+const DAY = 86_400_000;
+const PROJECT = /^[a-zA-Z0-9._-]+-[a-f0-9]{24}$/;
+const INTERVAL = 3_600_000;
+function value(raw, fallback) {
+    const n = raw?.trim() ? Number(raw) : NaN;
+    return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+export function storageRetentionPolicy(env) {
+    return { days: value(env.TALOS_RETENTION_DAYS, 90),
+        maxBytes: value(env.TALOS_STORAGE_MAX_MB, 2_048) * 1_048_576 };
+}
+function paths(env, cwd = process.cwd()) {
+    const base = resolve(cwd, talosConfigDir(env));
+    return { projects: join(base, "projects"), leases: join(base, "storage-leases"), state: join(base, "storage-retention.json") };
+}
+function contained(root, path) {
+    const rel = relative(root, path);
+    return Boolean(rel) && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+function regularDirectory(path) {
+    try {
+        const stat = lstatSync(path);
+        return stat.isDirectory() && !stat.isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+function managedStore(store, projects) {
+    const rel = relative(projects, resolve(store)).split(sep);
+    return rel.length === 2 && PROJECT.test(rel[0]) && rel[1] === "sessions"
+        && regularDirectory(projects) && regularDirectory(dirname(store)) && regularDirectory(store);
+}
+// Dots in custom session IDs deliberately coalesce retention groups. Keeping
+// related data longer is preferable to evicting only part of a conversation.
+function ownerOf(name) { return name.split(".")[0] || name; }
+function scan(projects) {
+    const groups = new Map();
+    if (!regularDirectory(projects))
+        return [];
+    for (const project of readdirSync(projects)) {
+        const store = join(projects, project, "sessions");
+        if (!managedStore(store, projects))
+            continue;
+        const walk = (dir, owner) => {
+            for (const name of readdirSync(dir)) {
+                if (name.startsWith(".") || name.endsWith(".lock") || (dir === store && name === "user-profile.json"))
+                    continue;
+                const path = join(dir, name);
+                const stat = lstatSync(path);
+                if (stat.isSymbolicLink())
+                    continue;
+                // One level contains artifact categories (usage, tool-outputs, ...),
+                // the next identifies the session/scope owning all nested payloads.
+                const groupOwner = owner ?? (dir === store && stat.isDirectory() ? undefined : ownerOf(name));
+                if (stat.isDirectory()) {
+                    walk(path, groupOwner);
+                    continue;
+                }
+                if (!stat.isFile() || !groupOwner)
+                    continue;
+                const key = `${store}\n${groupOwner}`;
+                const group = groups.get(key) ?? { store, owner: groupOwner, files: [], bytes: 0, updated: 0 };
+                group.files.push({ path, size: stat.size, mtimeMs: stat.mtimeMs });
+                group.bytes += stat.size;
+                group.updated = Math.max(group.updated, stat.mtimeMs);
+                groups.set(key, group);
+            }
+        };
+        walk(store);
+    }
+    return [...groups.values()];
+}
+function readLeases(directory, dryRun = false) {
+    if (!regularDirectory(directory))
+        return [];
+    const leases = [];
+    for (const name of readdirSync(directory)) {
+        if (!/^[a-f0-9-]{36}\.json$/.test(name))
+            continue;
+        const path = join(directory, name);
+        try {
+            const stat = lstatSync(path);
+            if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 16_384)
+                continue;
+            const row = JSON.parse(readFileSync(path, "utf8"));
+            if (!Number.isInteger(row.pid) || row.pid <= 0 || typeof row.store !== "string"
+                || !Array.isArray(row.owners) || row.owners.some(owner => typeof owner !== "string"))
+                continue;
+            try {
+                process.kill(row.pid, 0);
+            }
+            catch (error) {
+                if (error.code !== "ESRCH") {
+                    leases.push(row);
+                    continue;
+                }
+                if (!dryRun)
+                    unlinkSync(path);
+                continue;
+            }
+            leases.push(row);
+        }
+        catch { /* A corrupt lease must not make maintenance fail. */ }
+    }
+    return leases;
+}
+function isProtected(group, leases) {
+    const key = (path) => {
+        let canonical = resolve(path);
+        try {
+            canonical = realpathSync.native(canonical);
+        }
+        catch { /* Missing store cannot be active. */ }
+        return process.platform === "win32" ? canonical.toLowerCase() : canonical;
+    };
+    return leases.some(lease => key(lease.store) === key(group.store) && lease.owners.some(id => group.owner === ownerOf(id) || group.owner.startsWith(`kw-${ownerOf(id)}`)));
+}
+function removeGroup(group, projects) {
+    // Recheck every path before deleting anything. Never follow symlinks or
+    // delete a group that changed since the inventory was taken.
+    for (const file of group.files) {
+        const stat = lstatSync(file.path);
+        if (!contained(projects, file.path) || !contained(realpathSync(group.store), realpathSync(file.path))
+            || stat.isSymbolicLink() || !stat.isFile() || stat.size !== file.size || stat.mtimeMs !== file.mtimeMs)
+            return { bytes: 0, files: 0 };
+    }
+    let bytes = 0, files = 0;
+    for (const file of group.files) {
+        try {
+            unlinkSync(file.path);
+        }
+        catch {
+            break;
+        }
+        bytes += file.size;
+        files++;
+        for (let dir = dirname(file.path); contained(group.store, dir); dir = dirname(dir)) {
+            try {
+                rmdirSync(dir);
+            }
+            catch {
+                break;
+            } // Only empty artifact directories.
+        }
+    }
+    return { bytes, files };
+}
+export function cleanSessionStorage(env, options = {}) {
+    if (env.TALOS_STORAGE_CLEANUP === "0")
+        return null;
+    const path = paths(env, options.cwd);
+    if (!regularDirectory(path.projects))
+        return null;
+    const now = options.now ?? Date.now();
+    const policy = storageRetentionPolicy(env);
+    return withLockSync(path.state, () => {
+        if (existsSync(path.state) && lstatSync(path.state).isSymbolicLink())
+            return null;
+        if (!options.force && !options.dryRun && existsSync(path.state)) {
+            try {
+                if (now - JSON.parse(readFileSync(path.state, "utf8")).at < INTERVAL)
+                    return null;
+            }
+            catch { /* Retry invalid metadata. */ }
+        }
+        const groups = scan(path.projects).sort((a, b) => a.updated - b.updated);
+        const leases = readLeases(path.leases, options.dryRun);
+        const beforeBytes = groups.reduce((sum, group) => sum + group.bytes, 0);
+        let afterBytes = beforeBytes, removedGroups = 0, removedFiles = 0, protectedBytes = 0;
+        for (const group of groups) {
+            // The recent-write grace period also protects older runtime versions
+            // that do not yet register leases, and just-created conversations.
+            if (isProtected(group, leases) || now - group.updated < DAY) {
+                protectedBytes += group.bytes;
+                continue;
+            }
+            const expired = policy.days > 0 && now - group.updated >= policy.days * DAY;
+            if (!expired && !(policy.maxBytes > 0 && afterBytes > policy.maxBytes))
+                continue;
+            try {
+                const removed = options.dryRun ? { bytes: group.bytes, files: group.files.length } : removeGroup(group, path.projects);
+                afterBytes -= removed.bytes;
+                removedFiles += removed.files;
+                if (removed.files === group.files.length)
+                    removedGroups++;
+            }
+            catch { /* Locked/changing files are retained for the next pass. */ }
+        }
+        const report = { beforeBytes, afterBytes, removedGroups, removedFiles, protectedBytes,
+            overBudget: policy.maxBytes > 0 && afterBytes > policy.maxBytes };
+        if (!options.dryRun)
+            writeFileSync(path.state, JSON.stringify({ at: now, ...report }), { mode: 0o600 });
+        return report;
+    }, { timeoutMs: 5_000, staleMs: 300_000 });
+}
+// Leases are independent of the optional workspace messaging bus. Cleanup and
+// lease registration share the lock, so a resumed session cannot be evicted.
+export function protectSessionStorage(store, owners, env, cwd) {
+    const path = paths(env, cwd);
+    if (!managedStore(store, path.projects))
+        return () => { };
+    const file = join(path.leases, `${randomUUID()}.json`);
+    withLockSync(path.state, () => {
+        if (existsSync(path.leases) && !regularDirectory(path.leases))
+            throw new Error("Directory lease sessioni non valida");
+        mkdirSync(path.leases, { recursive: true, mode: 0o700 });
+        writeFileSync(file, JSON.stringify({ pid: process.pid, store: resolve(store), owners }), { flag: "wx", mode: 0o600 });
+    });
+    return () => { try {
+        unlinkSync(file);
+    }
+    catch { /* Already released. */ } };
+}
+export function maintainSessionStorage(env, cwd) {
+    try {
+        const report = cleanSessionStorage(env, { cwd });
+        if (report?.overBudget)
+            process.stderr.write("[talos] quota storico superata: sessioni attive/recenti protette; pulizia rinviata.\n");
+    }
+    catch { /* Maintenance must never prevent a conversation from opening. */ }
+}

package/dist/core/text-sanitize.d.ts

@@ -0,0 +1 @@
+export declare function sanitizeText(value: string): string;

package/dist/core/text-sanitize.js

@@ -0,0 +1,35 @@
+// Sanitizzazione del testo che entra in MEMORIA/CONTEXT (metodo Danilov).
+//
+// Output di tool (bash, web_fetch, ...), incolla da terminale e contenuti
+// esterni possono trascinare sequenze di escape ANSI (es. \x1b[31m), OSC
+// (hyperlink), e byte di controllo non-stampabili. Se finiscono nei title/
+// terms/body delle stanze o nei summary degli eventi, vengono iniettati TALI
+// E QUALI nel memory packet -> system prompt: sono i "caratteri strani" che
+// si leggono nel context e che lo sporcano (e gonfiano inutilmente i token).
+//
+// Questa funzione e' PURA e DETERMINISTICA: strip ANSI/OSC + caratteri di
+// controllo, preservando solo \n e \t (la collassatura degli spazi resta agli
+// helper oneLine/escapeValue gia' esistenti).
+// OSC (Operating System Command): ESC ] ... terminato da BEL (\x07) o ST
+// (ESC \). Es. hyperlink: ESC ]8;;URL BEL testo ESC ]8;; BEL. Va tolto INTERO,
+// URL incluso. Il corpo non contiene mai ESC ne' BEL, quindi terminiamo al
+// primo di essi: con ST il backslash residuo viene rimosso dal pass CSI/ESC
+// (ESC + un byte). Deve venire PRIMA del pattern CSI nel replace.
+// eslint-disable-next-line no-control-regex
+const OSC_RE = /[\u001b\u009d]\][^\u0007\u001b]*(?:\u0007|\u001b\\?)/g;
+// CSI: ESC [ ... lettera finale.  Piu' singoli ESC + intro a 1/2 byte
+// (es. ESC ( B, ESC =). Non include ] (gestito da OSC_RE).
+const ANSI_RE = 
+// eslint-disable-next-line no-control-regex
+/[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-PR-TZcf-ntqry=><~]|\u001b[@-Z\\-_]/g;
+// Caratteri di controllo C0/C1 non-stampabili, ESCLUSI \t (0x09) e \n (0x0a).
+// Anche \r (0x0d) viene rimosso: lo normalizziamo via newline a monte.
+// eslint-disable-next-line no-control-regex
+const CONTROL_RE = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g;
+// Rimuove escape ANSI/OSC e byte di controllo non-stampabili dal testo.
+// Mantiene \n e \t. Non collassa gli spazi (lo fanno oneLine/escapeValue).
+export function sanitizeText(value) {
+    if (!value)
+        return "";
+    return value.replace(OSC_RE, "").replace(ANSI_RE, "").replace(CONTROL_RE, "");
+}

package/dist/core/tool-artifacts.d.ts

@@ -0,0 +1,6 @@
+import type { Message, ToolResultPart } from "./types.js";
+import { ToolOutputStore } from "./tool-result-store.js";
+import { type ToolCompressOptions } from "./tool-compress.js";
+export declare function projectToolResult(result: ToolResultPart, producer: string, store: ToolOutputStore | null, minTokens: number, compression: ToolCompressOptions, retrievedId?: string): ToolResultPart;
+/** Only suppress repeats when the requested page is still visible in this request. */
+export declare function visibleOutputPages(messages: readonly Message[]): ReadonlySet<string>;

package/dist/core/tool-artifacts.js

@@ -0,0 +1,51 @@
+import { ToolOutputStore } from "./tool-result-store.js";
+import { compressToolOutput } from "./tool-compress.js";
+import { estimateTokens } from "./compaction.js";
+import { createHash } from "node:crypto";
+import { effectiveToolName } from "./effort.js";
+export function projectToolResult(result, producer, store, minTokens, compression, retrievedId = "") {
+    if (result.isError || !store)
+        return result;
+    const compressed = compressToolOutput(result.output, producer, compression);
+    const pages = [...new Set([...result.output.matchAll(/output_page id="(tr\d+)"/g)].map((match) => match[1]))];
+    const inherited = result._meta?.["talosArtifact"];
+    const inheritedEntry = inherited?.id ? store.entry(inherited.id) : null;
+    const sameContent = inheritedEntry?.sha256 === createHash("sha256").update(result.output).digest("hex");
+    const alias = retrievedId || (pages.length === 1 ? pages[0] : "") || (sameContent ? inheritedEntry.id : "");
+    const entry = alias ? store.alias(result.callId, alias)
+        : compressed !== result.output || estimateTokens(result.output) >= minTokens
+            ? store.put(result.callId, producer, result.output, result) : null;
+    if (!entry)
+        return result;
+    return {
+        ...result,
+        output: compressed === result.output ? result.output
+            : compressed + '\n[output integrale: output_page id="' + entry.id + '"]',
+        _meta: { ...result._meta, talosArtifact: { id: entry.id, scope: store.scope, name: entry.name, sha256: entry.sha256 ?? "", chars: entry.chars } },
+    };
+}
+/** Only suppress repeats when the requested page is still visible in this request. */
+export function visibleOutputPages(messages) {
+    const calls = new Map();
+    const visible = new Set();
+    for (const message of messages)
+        for (const part of message.content) {
+            if (part.type === "tool_call" && effectiveToolName(part.name, part.input) === "output_page") {
+                const args = part.name === "execute" || part.name === "tool_invoke" ? part.input["args"] : part.input;
+                if (args && typeof args === "object" && !Array.isArray(args)) {
+                    const input = args;
+                    if (typeof input["id"] === "string") {
+                        const id = input["id"];
+                        calls.set(part.id, { id, page: Number(input["page"]) || (id.startsWith("tr") ? 1 : 2) });
+                    }
+                }
+            }
+            if (part.type !== "tool_result" || part.isError)
+                continue;
+            const call = calls.get(part.callId);
+            if (call && /pagina\s+\d+\/\d+/.test(part.output) && !/\[TOOL_RESULT_REF/.test(part.output)) {
+                visible.add(call.id + ":" + call.page);
+            }
+        }
+    return visible;
+}

package/dist/core/tool-compress.d.ts

@@ -0,0 +1,8 @@
+export interface ToolCompressOptions {
+    readonly enabled: boolean;
+    readonly minChars: number;
+    readonly targetChars: number;
+}
+export declare function toolCompressOptions(env: NodeJS.ProcessEnv): ToolCompressOptions;
+export declare const NO_COMPRESS_TOOLS: ReadonlySet<string>;
+export declare function compressToolOutput(output: string, toolName?: string, opts?: ToolCompressOptions): string;

package/dist/core/tool-compress.js

@@ -0,0 +1,111 @@
+// Compressione content-aware degli output dei tool PRIMA che entrino nel
+// contesto del modello (ispirato a headroom, ma nativo e senza dipendenze).
+// Obiettivo: tagliare i token su output voluminosi (bash, read_file, web_fetch,
+// list_dir) preservando struttura e informazione utile, invece del semplice
+// troncamento a coda. Modulo PURO e testabile.
+export function toolCompressOptions(env) {
+    const flag = (env["TALOS_TOOLOUT_COMPRESS"] ?? "").trim().toLowerCase();
+    const enabled = !(flag === "0" || flag === "off" || flag === "false" || flag === "no");
+    const min = Number(env["TALOS_TOOLOUT_COMPRESS_MIN"]);
+    const target = Number(env["TALOS_TOOLOUT_COMPRESS_TARGET"]);
+    return {
+        enabled,
+        minChars: Number.isFinite(min) && min > 0 ? min : 2000,
+        targetChars: Number.isFinite(target) && target > 0 ? target : 6000,
+    };
+}
+// Tool il cui output NON va compresso: o e' gia' breve, o e' un recupero
+// esplicito che l'agente vuole integrale (recall, bash_output, ask_user), o e'
+// metadato del regno che altri parser leggono testualmente.
+export const NO_COMPRESS_TOOLS = new Set([
+    // Tool di CONTENUTO: il modello ne vuole il testo verbatim; la dimensione e'
+    // gestita dalla paginazione (output_page), non dalla compressione lossy.
+    "read_file",
+    "web_fetch",
+    "grep",
+    "glob",
+    "recall",
+    "bash_output",
+    "output_page",
+    "ask_user",
+    "image_generate",
+    "vascend_plan",
+    "vascend_mark",
+    "vascend_note",
+    "vascend_skill",
+    "vascend_addtasks",
+]);
+function tryCompressJson(output) {
+    const trimmed = output.trim();
+    if (!(trimmed.startsWith("{") || trimmed.startsWith("[")))
+        return null;
+    try {
+        // JSON is a data contract: removing rows or changing strings corrupts it.
+        // Whitespace is the only generic reduction that preserves values/cursors.
+        return JSON.stringify(JSON.parse(trimmed));
+    }
+    catch {
+        return null;
+    }
+}
+// Compressione testo/log: collassa righe vuote multiple, deduplica righe
+// consecutive identiche (×N), e se ancora troppo lungo tiene testa+coda.
+function compressText(output, target) {
+    const rawLines = output.split("\n");
+    const lines = [];
+    let blank = 0;
+    for (const line of rawLines) {
+        if (line.trim() === "") {
+            blank += 1;
+            if (blank > 1)
+                continue;
+        }
+        else {
+            blank = 0;
+        }
+        const prev = lines[lines.length - 1];
+        if (prev !== undefined) {
+            const m = /^(.*?)(?:  ×(\d+))?$/.exec(prev);
+            const prevText = m?.[1] ?? prev;
+            if (prevText === line) {
+                const n = m?.[2] ? Number(m[2]) + 1 : 2;
+                lines[lines.length - 1] = `${line}  ×${n}`;
+                continue;
+            }
+        }
+        lines.push(line);
+    }
+    let text = lines.join("\n");
+    if (text.length <= target)
+        return text;
+    // Testa + coda con elisione del centro.
+    const headChars = Math.floor(target * 0.6);
+    const tailChars = target - headChars;
+    const head = text.slice(0, headChars);
+    const tail = text.slice(-tailChars);
+    const omitted = text.length - headChars - tailChars;
+    return `${head}\n…(${omitted} caratteri omessi nel mezzo)…\n${tail}`;
+}
+// Comprime l'output di un tool se conviene. Ritorna l'originale se sotto soglia,
+// nella denylist, disabilitato, o se la compressione non riduce abbastanza.
+export function compressToolOutput(output, toolName, opts) {
+    const o = opts ?? toolCompressOptions(process.env);
+    if (!o.enabled)
+        return output;
+    if (toolName && NO_COMPRESS_TOOLS.has(toolName))
+        return output;
+    // Gia' paginato: non ricomprimere (il modello pagina con output_page).
+    if (/output_page id="(?:pg|tr)\d+"/.test(output))
+        return output;
+    if (output.length <= o.minChars)
+        return output;
+    const json = tryCompressJson(output);
+    const compressed = json ?? compressText(output, o.targetChars);
+    // Solo se riduce in modo sensibile (almeno 10%).
+    if (compressed.length >= output.length * 0.9)
+        return output;
+    if (json !== null)
+        return json;
+    const marker = `\n[output compresso: ${output.length}→${compressed.length} char]`;
+    return compressed + marker;
+}

package/dist/core/tool-executor.d.ts

@@ -0,0 +1,16 @@
+import type { ToolCallPart, ToolContext, ToolResultPart } from "./types.js";
+export interface ToolExecutionHooks {
+    readonly before?: (call: ToolCallPart) => Promise<{
+        readonly block?: boolean;
+        readonly reason?: string;
+    } | void>;
+    readonly after?: (call: ToolCallPart, result: ToolResultPart) => Promise<ToolResultPart>;
+    readonly finalize?: (call: ToolCallPart, result: ToolResultPart) => ToolResultPart;
+    readonly onCall?: (call: ToolCallPart, parentId?: string) => void;
+    readonly onResult?: (call: ToolCallPart, result: ToolResultPart, parentId?: string) => void;
+}
+export type ToolExecutor = (call: ToolCallPart) => Promise<ToolResultPart>;
+/** One execution contract for direct calls, compatibility wrappers and programs. */
+export declare function createToolExecutor(ctx: ToolContext, hooks?: ToolExecutionHooks): ToolExecutor;
+/** Standalone hosts can use the same normalization without installing an agent. */
+export declare function invokeToolCall(call: ToolCallPart, ctx: ToolContext): Promise<ToolResultPart>;

package/dist/core/tool-executor.js

@@ -0,0 +1,97 @@
+import { normalizeMcpToolResult, textFromMcpToolResult } from "../mcp/protocol.js";
+import { normalizeToolInput } from "../tools/normalize-input.js";
+/** One execution contract for direct calls, compatibility wrappers and programs. */
+export function createToolExecutor(ctx, hooks = {}) {
+    const execute = async (call, parentId, depth = 0, signal = ctx.signal, guards = ctx.guardToolCall ? [ctx.guardToolCall] : []) => {
+        hooks.onCall?.(call, parentId);
+        let result;
+        try {
+            if (signal.aborted)
+                throw new Error("chiamata annullata prima dell'esecuzione");
+            if (depth > 16)
+                throw new Error("limite di annidamento dei tool raggiunto");
+            const gate = await hooks.before?.(call);
+            if (gate?.block)
+                throw new Error("bloccato dall'estensione" + (gate.reason ? ": " + gate.reason : ""));
+            if (call.inputTruncatedChars)
+                throw new Error("argomenti troncati: " + call.inputTruncatedChars + " caratteri di JSON incompleto. "
+                    + "Rifai la chiamata con un payload piu' piccolo (write_file con append=true oppure edit_file).");
+            const tool = ctx.tools?.get(call.name);
+            if (!tool)
+                throw new Error("strumento sconosciuto: " + call.name);
+            for (const guard of guards)
+                guard(call);
+            signal.throwIfAborted();
+            const handled = await tool.handler(normalizeToolInput(call.input, tool.inputSchema), {
+                ...ctx, signal, guardToolCall: undefined,
+                invokeTool: (nested, nestedSignal, guard) => execute(nested, call.id, depth + 1, nestedSignal && nestedSignal !== signal ? AbortSignal.any([signal, nestedSignal]) : signal, guard && !guards.includes(guard) ? [...guards, guard] : guards),
+                emitToolEvent: (event) => {
+                    if (event.type === "tool_call")
+                        hooks.onCall?.(event.call, call.id);
+                    else
+                        hooks.onResult?.(event.call, event.result, call.id);
+                },
+            });
+            const mcp = normalizeMcpToolResult(handled);
+            const legacyMedia = typeof handled === "object" && handled !== null && "media" in handled
+                ? handled.media : undefined;
+            const media = normalizedToolMedia(legacyMedia ?? mcp.content);
+            result = {
+                type: "tool_result", callId: call.id,
+                output: textFromMcpToolResult(mcp), content: mcp.content, isError: mcp.isError === true,
+                ...(mcp.structuredContent ? { structuredContent: mcp.structuredContent } : {}),
+                ...(mcp._meta ? { _meta: mcp._meta } : {}),
+                ...(media ? { media } : {}),
+            };
+        }
+        catch (error) {
+            const output = "eccezione: " + (error instanceof Error ? error.message : String(error));
+            result = { type: "tool_result", callId: call.id, output, isError: true, content: [{ type: "text", text: output }] };
+        }
+        // Result hooks run for errors too.
+        try {
+            if (hooks.after)
+                result = await hooks.after(call, result);
+            result = hooks.finalize?.(call, result) ?? result;
+        }
+        catch (error) {
+            // The action already ran: preserve evidence and never encourage an automatic replay.
+            const note = "Post-elaborazione del risultato fallita: " + (error instanceof Error ? error.message : String(error))
+                + ". L'azione potrebbe essere gia' completata: verificane l'esito prima di ripeterla.";
+            result = { ...result, isError: true, output: result.output + "\n" + note,
+                content: [...(result.content ?? [{ type: "text", text: result.output }]), { type: "text", text: note }],
+                _meta: { ...result._meta, talosPostprocessingError: true } };
+        }
+        hooks.onResult?.(call, result, parentId);
+        return result;
+    };
+    return (call) => execute(call);
+}
+/** Standalone hosts can use the same normalization without installing an agent. */
+export async function invokeToolCall(call, ctx) {
+    if (ctx.invokeTool) {
+        return ctx.invokeTool(call, ctx.signal, ctx.guardToolCall);
+    }
+    return createToolExecutor(ctx, {
+        onCall: (nested) => ctx.emitToolEvent?.({ type: "tool_call", call: nested }),
+        onResult: (nested, result) => ctx.emitToolEvent?.({ type: "tool_result", call: nested, result }),
+    })(call);
+}
+function normalizedToolMedia(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const media = value.filter((item) => item && typeof item === "object").flatMap((item) => {
+        const row = item;
+        const mime = String(row["mimeType"] ?? row["mime"] ?? "").toLowerCase();
+        const data = String(row["data"] ?? "").replace(/\s+/g, "");
+        if (!/^image\/(?:png|jpeg|jpg|webp|gif)$/.test(mime) || !data || !/^[A-Za-z0-9+/=]+$/.test(data))
+            return [];
+        if (data.length * 0.75 > 5 * 1024 * 1024)
+            return [];
+        return [{
+                type: "image", mime: mime === "image/jpg" ? "image/jpeg" : mime, data,
+                ...(row["source"] ? { source: String(row["source"]).slice(0, 160) } : {}),
+            }];
+    }).slice(0, 4);
+    return media.length ? media : undefined;
+}

package/dist/core/tool-result-index.d.ts

@@ -0,0 +1,52 @@
+import type { Message, ToolResultPart } from "./types.js";
+export interface ToolIndexPolicy {
+    readonly enabled: boolean;
+    readonly triggerTokens: number;
+    readonly keepTokens: number;
+    readonly keepRecent: number;
+    readonly minTokens: number;
+}
+export declare const DEFAULT_TOOL_INDEX: ToolIndexPolicy;
+export declare function toolIndexPolicy(env: NodeJS.ProcessEnv, contextWindow?: number): ToolIndexPolicy;
+export interface DemotedRef {
+    readonly callId: string;
+    readonly storedId: string;
+    readonly name: string;
+    readonly tokens: number;
+    readonly images: number;
+}
+export interface ToolIndexPlan {
+    readonly refs: readonly DemotedRef[];
+    readonly freedTokens: number;
+    readonly verbatimTokens: number;
+}
+export declare const EMPTY_PLAN: ToolIndexPlan;
+export interface ToolIndexInput {
+    readonly messages: readonly Message[];
+    readonly policy: ToolIndexPolicy;
+    readonly archivedId: (callId: string) => string | null;
+}
+export declare function planToolResultDemotion(input: ToolIndexInput): ToolIndexPlan;
+export declare function applyToolResultDemotion(messages: readonly Message[], plan: ToolIndexPlan): readonly Message[];
+export declare function isDemoted(output: string): boolean;
+export declare function demotedText(ref: DemotedRef, output: string): string;
+export declare function slimToolResultForSession(part: ToolResultPart): ToolResultPart;
+export declare function slimMessageForSession(message: Message): Message;
+export interface MediaBudgetPolicy {
+    readonly enabled: boolean;
+    readonly keepImages: number;
+}
+export declare const DEFAULT_MEDIA_BUDGET: MediaBudgetPolicy;
+export declare function mediaBudgetPolicy(env: NodeJS.ProcessEnv): MediaBudgetPolicy;
+export interface MediaEvictionPlan {
+    readonly callIds: readonly string[];
+    readonly images: number;
+    readonly bytes: number;
+    readonly totalImages: number;
+}
+export declare const EMPTY_MEDIA_PLAN: MediaEvictionPlan;
+export declare function planMediaEviction(input: {
+    readonly messages: readonly Message[];
+    readonly policy: MediaBudgetPolicy;
+}): MediaEvictionPlan;
+export declare function applyMediaEviction(messages: readonly Message[], plan: MediaEvictionPlan): readonly Message[];