@vascend/talos 0.1.5 → 0.1.6

package/dist/remote/sessione-remota.js

@@ -0,0 +1,266 @@
+// Una sessione di controllo remoto: il ponte fra l'agente di Talos e il relay.
+//
+// Verso il telefono (eventi, cifrati, direzione "ev"):
+//   message     {role: "user"|"assistant", text}
+//   delta       {text}                      testo mentre il modello scrive
+//   tool_call   {id, name, input, parent?}  parent: chiamata che la contiene
+//   tool_result {id, error, output, parent?}
+//   permission  {id, action, detail}        Talos chiede un'approvazione
+//   status      {state, label?, permission?: {id, outcome, by}}
+//   end         {}
+// Dal telefono (comandi, cifrati, direzione "cmd"): il contenuto porta anche
+// il proprio cid e l'ora (ts, ms), cosi' il relay non puo' riusarlo ne'
+// spostarlo su un altro comando.
+//   message   {text}          come se fosse scritto nella TUI (mai un "/")
+//   interrupt {text?}         con testo: consegna subito; senza: stop
+//   stop      {}
+//   approve   {permission}    deny {permission}
+//
+// Gli eventi si cifrano e si accodano in ordine (una catena di promesse): il
+// seq del relay e' contiguo e non deve mai saltare.
+import { hostname } from "node:os";
+import { basename } from "node:path";
+import { randomBytes } from "node:crypto";
+import { CifraturaError, cifra, decifra, nuovaChiave } from "./cifratura.js";
+import { RelayHost } from "./relay-client.js";
+export const VIEWER_URL = "https://vascend.it/remoto";
+const MAX_TESTO = 64_000;
+const MAX_ANTEPRIMA = 4_000;
+const RITMO_DELTA_MS = 120;
+const FINESTRA_COMANDI_MS = 10 * 60_000;
+function tronca(testo, max) {
+    return testo.length <= max ? testo : `${testo.slice(0, max)}\n[... ${testo.length - max} caratteri non inviati]`;
+}
+function anteprimaInput(input) {
+    try {
+        return tronca(JSON.stringify(input) ?? "", MAX_ANTEPRIMA);
+    }
+    catch {
+        return "";
+    }
+}
+export class SessioneRemota {
+    relay;
+    chiave;
+    link;
+    mani;
+    now;
+    catena = Promise.resolve();
+    delta = "";
+    timerDelta = null;
+    risposta = "";
+    viewer = 0;
+    permessi = new Map();
+    constructor(relay, chiave, link, mani, now) {
+        this.relay = relay;
+        this.chiave = chiave;
+        this.link = link;
+        this.mani = mani;
+        this.now = now;
+    }
+    static async avvia(opts) {
+        const { chiave, testo } = await nuovaChiave();
+        let sessione = null;
+        const relay = await RelayHost.apri(opts.base, {
+            title: basename(opts.cwd) || "Talos",
+            agent: "talos",
+            device: hostname().slice(0, 80),
+        }, {
+            ...opts.relayDeps,
+            token: opts.token,
+            onStato: opts.onStato,
+            onPresenza: (n) => { if (sessione)
+                sessione.viewer = n; opts.onPresenza?.(n); },
+            onComando: (c) => sessione ? sessione.comando(c) : Promise.resolve(),
+        });
+        const link = `${VIEWER_URL}#s=${relay.sessione}&k=${testo}`;
+        sessione = new SessioneRemota(relay, chiave, link, opts.mani, opts.now ?? Date.now);
+        sessione.stato({ state: "idle" });
+        return sessione;
+    }
+    get id() { return this.relay.sessione; }
+    statoRelay() { return this.relay.statoAttuale(); }
+    dispositivi() { return this.viewer; }
+    // --- dall'agente al telefono --------------------------------------------------
+    // Adattatore per gli eventi dell'agente di Talos.
+    osserva(event) {
+        switch (event.type) {
+            case "turn_start":
+                this.statoAgente("thinking");
+                return;
+            case "text":
+                this.testo(event.delta);
+                return;
+            case "tool_call":
+                this.chiamataTool({ id: event.call.id, name: event.call.name, input: event.call.input, parent: event.parentId });
+                return;
+            case "tool_result":
+                this.risultatoTool({ id: event.result.callId, error: event.result.isError, output: event.result.output ?? "", parent: event.parentId });
+                return;
+            case "status":
+                this.statoAgente("working", event.label);
+                return;
+            case "turn_end":
+                this.rispostaCompleta();
+                return;
+            case "done":
+                this.rispostaCompleta();
+                this.statoAgente("idle");
+                return;
+            case "error":
+                this.rispostaCompleta();
+                this.statoAgente("error", event.message);
+                return;
+            default: return;
+        }
+    }
+    // --- API generica: per chi non ha gli eventi di Talos (l'IDE con Claude,
+    // Codex e gli altri motori traduce i suoi eventi in queste chiamate) -------
+    // Un pezzo della risposta mentre il modello scrive.
+    testo(delta) {
+        if (!delta)
+            return;
+        this.risposta += delta;
+        this.delta += delta;
+        if (this.delta.length >= 2_048)
+            this.svuotaDelta();
+        else if (!this.timerDelta)
+            this.timerDelta = setTimeout(() => this.svuotaDelta(), RITMO_DELTA_MS);
+    }
+    // Fine della risposta in corso: diventa un messaggio completo.
+    rispostaCompleta() {
+        this.chiudiRisposta();
+    }
+    chiamataTool(c) {
+        this.chiudiRisposta();
+        this.evento("tool_call", {
+            id: c.id, name: tronca(c.name, 200), input: typeof c.input === "string" ? tronca(c.input, MAX_ANTEPRIMA) : anteprimaInput(c.input),
+            ...(c.parent ? { parent: c.parent } : {}),
+        });
+    }
+    risultatoTool(r) {
+        this.evento("tool_result", {
+            id: r.id, error: r.error, output: tronca(r.output, MAX_ANTEPRIMA), ...(r.parent ? { parent: r.parent } : {}),
+        });
+    }
+    statoAgente(state, label) {
+        this.stato(label ? { state, label: tronca(label, state === "error" ? 500 : 200) } : { state });
+    }
+    messaggioUtente(testo) {
+        this.chiudiRisposta();
+        this.evento("message", { role: "user", text: tronca(testo, MAX_TESTO) });
+    }
+    // Richiesta di permesso in gara con la TUI: vince la prima risposta. La TUI
+    // riceve un segnale che si annulla quando risponde il telefono (e viceversa).
+    async permessoConGara(azione, dettaglio, signal, tui) {
+        const id = randomBytes(12).toString("hex");
+        const locale = new AbortController();
+        const entrambi = AbortSignal.any([signal, locale.signal]);
+        const dalTelefono = new Promise((resolve) => {
+            this.permessi.set(id, (valore) => resolve({ valore, da: "remote" }));
+            entrambi.addEventListener("abort", () => this.permessi.delete(id), { once: true });
+        });
+        this.chiudiRisposta();
+        this.evento("permission", { id, action: tronca(azione, 200), detail: tronca(dettaglio, MAX_ANTEPRIMA) });
+        this.stato({ state: "waiting", label: tronca(azione, 200) });
+        let esito;
+        try {
+            esito = await Promise.race([tui(entrambi).then((valore) => ({ valore, da: "talos" })), dalTelefono]);
+        }
+        finally {
+            locale.abort();
+            this.permessi.delete(id);
+        }
+        const outcome = signal.aborted ? "cancelled" : esito.valore ? "allowed" : "denied";
+        this.stato({ state: "working", permission: { id, outcome, by: esito.da } });
+        return esito.valore;
+    }
+    // Fine: ultimo stato, "end", poi la sessione si chiude per tutti.
+    async chiudi() {
+        this.chiudiRisposta();
+        for (const risolvi of this.permessi.values())
+            risolvi(false);
+        this.permessi.clear();
+        this.evento("end", {});
+        await this.catena;
+        await this.relay.chiudi();
+    }
+    // --- dal telefono all'agente --------------------------------------------------
+    async comando(c) {
+        if (!c.b)
+            return;
+        let dati;
+        try {
+            const v = await decifra(this.chiave, this.relay.sessione, "cmd", c.b);
+            if (!v || typeof v !== "object" || Array.isArray(v))
+                return;
+            dati = v;
+        }
+        catch (e) {
+            if (e instanceof CifraturaError)
+                return; // non viene da un dispositivo abbinato
+            throw e;
+        }
+        // Il contenuto cifrato deve riguardare proprio questo comando e essere recente.
+        const ts = Number(dati["ts"]);
+        if (dati["cid"] !== c.cid || !Number.isFinite(ts) || Math.abs(this.now() - ts) > FINESTRA_COMANDI_MS)
+            return;
+        const testo = typeof dati["text"] === "string" ? dati["text"].slice(0, MAX_TESTO) : "";
+        switch (c.k) {
+            case "message":
+                if (testo.trim() && !this.mani.invia(testo, false))
+                    this.stato({ state: "working", label: "comando non accettato" });
+                return;
+            case "interrupt":
+                if (testo.trim())
+                    this.mani.invia(testo, true);
+                else
+                    this.mani.ferma();
+                return;
+            case "stop":
+                this.mani.ferma();
+                return;
+            case "approve":
+            case "deny": {
+                const id = typeof dati["permission"] === "string" ? dati["permission"] : "";
+                this.permessi.get(id)?.(c.k === "approve");
+                return;
+            }
+            default:
+                return;
+        }
+    }
+    // --- invio ordinato -----------------------------------------------------------
+    svuotaDelta() {
+        if (this.timerDelta) {
+            clearTimeout(this.timerDelta);
+            this.timerDelta = null;
+        }
+        if (!this.delta)
+            return;
+        const testo = this.delta;
+        this.delta = "";
+        this.accoda("delta", { text: testo });
+    }
+    chiudiRisposta() {
+        this.svuotaDelta();
+        const testo = this.risposta.trim();
+        this.risposta = "";
+        if (testo)
+            this.accoda("message", { role: "assistant", text: tronca(testo, MAX_TESTO) });
+    }
+    stato(dati) {
+        this.accoda("status", dati);
+    }
+    evento(k, dati) {
+        this.svuotaDelta();
+        this.accoda(k, dati);
+    }
+    accoda(k, dati) {
+        const sessione = this.relay.sessione;
+        this.catena = this.catena
+            .then(() => cifra(this.chiave, sessione, "ev", dati))
+            .then((b) => { this.relay.invia(k, b); })
+            .catch(() => { });
+    }
+}

package/dist/sdk.d.ts

@@ -1,5 +1,10 @@
 export { bootstrap } from "./core/bootstrap.js";
 export type { Harness } from "./core/bootstrap.js";
+export type { FusionConfig, FusionGateMode, FusionAvailability } from "./core/fusion.js";
+export { DEFAULT_FUSION, fusionAvailability, isPaidTier, parseFusion } from "./core/fusion.js";
+export type { StepDirective, StepPolicy } from "./core/step-policy.js";
+export { createJevClient, isDevChannel, parseJevResponse, resolveJevTransport } from "./fusion/jev.js";
+export type { JevAnswer, JevClient, JevOutcome, JevQuestion, JevResult, JevTransport } from "./fusion/jev.js";
 export { runTurn } from "./core/agent.js";
 export type { AgentDeps } from "./core/agent.js";
 export { FileCoordinationHub, fileActor, formatFileConflicts, withFileActor } from "./core/file-coordination.js";
@@ -52,8 +57,8 @@ export { buildArchitectureMap, renderArchitectureMap, scanArchitectureMap, } fro
 export type { ArchDependency, ArchEntryPoint, ArchExternal, ArchHotspot, ArchModuleStat, ArchSourceFile, ArchitectureMap, } from "./vascend/architecture-map.js";
 export { doctorExitCode, renderDoctorReport, runDoctor } from "./core/doctor.js";
 export type { DoctorCheck, DoctorReport, DoctorStatus } from "./core/doctor.js";
-export { HORIZON_CAPABILITIES, HorizonContextUnavailableError, HorizonEngine, HorizonMainTeam, needsGuideArbitration, HorizonSessionNotFoundError, HorizonStateError, routeWorkerModels, } from "./horizon/index.js";
-export type { HorizonCapabilityDescriptor, HorizonContextStatus, HorizonEngineOptions, HorizonEngineState, HorizonModelCatalog, HorizonModelDescriptor, HorizonModelInspectionOptions, HorizonProviderDescriptor, HorizonRuntime, HorizonSessionListItem, HorizonSessionSnapshot, HorizonTurn, HorizonTurnInput, HorizonTurnOptions, HorizonTurnResult, HorizonTurnStatus, HorizonVibeStatus, } from "./horizon/index.js";
+export { HORIZON_CAPABILITIES, HorizonContextUnavailableError, HorizonFusionUnavailableError, HorizonEngine, HorizonMainTeam, needsGuideArbitration, HorizonSessionNotFoundError, HorizonStateError, routeWorkerModels, } from "./horizon/index.js";
+export type { HorizonCapabilityDescriptor, HorizonContextStatus, HorizonEngineOptions, HorizonEngineState, HorizonModelCatalog, HorizonModelDescriptor, HorizonModelInspectionOptions, HorizonProviderDescriptor, HorizonRuntime, HorizonSessionListItem, HorizonSessionSnapshot, HorizonTurn, HorizonTurnInput, HorizonTurnOptions, HorizonTurnResult, HorizonTurnStatus, HorizonVibeStatus, HorizonFusionStatus, } from "./horizon/index.js";
 export type { HorizonGuideCooperation, HorizonGuideDecision, HorizonGuideDecisionRecord, HorizonGuideDecisionRequest, HorizonGuidePlan, HorizonGuideTask, HorizonGuideVerdict, HorizonMainExchange, HorizonMainRef, HorizonMainTeamConfig, HorizonMainTeamEvent, HorizonMainTeamResult, HorizonMainTeamTurn, HorizonTeamRef, HorizonAgentPurpose, } from "./horizon/index.js";
 export type { AgentEvent, EventSink, Message, ContentPart, Tool, ToolDef, ToolRegistrationDef, RegisteredTool, ToolHandler, ToolHandlerOutput, ToolContext, ImagePart, Provider, ModelTurn, CompletionRequest, } from "./core/types.js";
 export type { Extension, ExtensionApi, SlashCommand, } from "./extensions/types.js";

package/dist/sdk.js

@@ -2,6 +2,8 @@
 // (es. il processo main di vascend-terminal). Quattro modalita' condividono
 // lo stesso nucleo: TUI, print, RPC e questo SDK.
 export { bootstrap } from "./core/bootstrap.js";
+export { DEFAULT_FUSION, fusionAvailability, isPaidTier, parseFusion } from "./core/fusion.js";
+export { createJevClient, isDevChannel, parseJevResponse, resolveJevTransport } from "./fusion/jev.js";
 export { runTurn } from "./core/agent.js";
 export { FileCoordinationHub, fileActor, formatFileConflicts, withFileActor } from "./core/file-coordination.js";
 // Casella dei messaggi scritti mentre l'agente lavora: un host che usa runTurn
@@ -53,7 +55,7 @@ export { buildArchitectureMap, renderArchitectureMap, scanArchitectureMap, } fro
 // Diagnostica ambiente (stessa del comando `talos --doctor`).
 export { doctorExitCode, renderDoctorReport, runDoctor } from "./core/doctor.js";
 // Horizon: facade headless stabile per l'embedding in Vascend Terminal.
-export { HORIZON_CAPABILITIES, HorizonContextUnavailableError, HorizonEngine, HorizonMainTeam, needsGuideArbitration, HorizonSessionNotFoundError, HorizonStateError, routeWorkerModels, } from "./horizon/index.js";
+export { HORIZON_CAPABILITIES, HorizonContextUnavailableError, HorizonFusionUnavailableError, HorizonEngine, HorizonMainTeam, needsGuideArbitration, HorizonSessionNotFoundError, HorizonStateError, routeWorkerModels, } from "./horizon/index.js";
 // Modulo Cowork: workspace condivisi collaborativi su engine Talos (desktop).
 export { CoworkManager, localIdentity, CoworkStore, CoworkSyncChannel, CoworkEngine, createCoworkIpc, createCoworkClient, } from "./cowork/index.js";
 // Kingdoms Mode osservabile e INTERROGABILE dall'host: scrivere a un singolo

package/dist/tools/builtin.js

@@ -286,8 +286,10 @@ function runBashSpawn(command, ctx, options) {
             mgr.clearForeground(task.id);
             resolvePromise(isError ? toolError(msg) : msg);
         };
-        child.stdout?.on("data", (d) => mgr.appendOutput(task.id, d.toString("utf8")));
-        child.stderr?.on("data", (d) => mgr.appendOutput(task.id, d.toString("utf8")));
+        child.stdout?.setEncoding("utf8");
+        child.stderr?.setEncoding("utf8");
+        child.stdout?.on("data", (text) => mgr.appendOutput(task.id, text));
+        child.stderr?.on("data", (text) => mgr.appendOutput(task.id, text));
         child.on("error", (err) => {
             mgr.finishTask(task.id, "failed");
             finish(`errore esecuzione: ${err.message}`, true);
@@ -308,7 +310,7 @@ function runBashSpawn(command, ctx, options) {
             finish(`comando in background [${task.id}]: ${command.length > 60 ? command.slice(0, 57) + "..." : command}\n` +
                 `Continua a girare. Leggi l'output con bash_output id="${task.id}".`);
         };
-        mgr.setForeground({ taskId: task.id, background: detach });
+        mgr.setForeground({ taskId: task.id, sessionId: ctx.sessionId, background: detach });
         // Un agente non puo' decidere di interrompere un tool mentre ne attende il
         // risultato. Una breve attesa evita un secondo giro per i comandi rapidi;
         // oltre il limite bash_output permette di osservare e terminare il task.
@@ -330,12 +332,18 @@ function runBashSpawn(command, ctx, options) {
 export const bashOutputTool = {
     name: "bash_output",
     description: "Monitora e gestisce un comando shell in background. Passa `id` (es. \"bg1\") per " +
-        "leggerne stato e output; senza id elenca i task. `kill: true` interrompe il processo.",
+        "attendere il risultato finale senza polling del modello; l'attesa e' interrompibile. " +
+        "`wait: false` legge subito stato/output (utile per server persistenti); senza id elenca i task. " +
+        "`timeout_seconds` limita esplicitamente l'attesa; omettilo per attendere il completamento. " +
+        "`kill: true` interrompe subito il processo.",
     schema: {
         type: "object",
         properties: {
             id: { type: "string", description: "id del task (es. bg1)" },
             kill: { type: "boolean", description: "se true termina il task" },
+            wait: { type: "boolean", description: "default true: attende il completamento; false: legge subito, per server persistenti o diagnosi" },
+            timeout_seconds: { type: "number", minimum: 0, maximum: 3600,
+                description: "Limite opzionale dell'attesa in secondi; omesso attende il risultato finale, 0 legge subito" },
         },
     },
     handler: async (input, ctx) => {
@@ -353,6 +361,13 @@ export const bashOutputTool = {
             return toolError(`task non trovato: ${id}`);
         if (input["kill"] === true)
             return mgr.kill(id) ? `terminato ${id}` : `${id} non e' piu' in esecuzione`;
+        if (input["wait"] !== false && t.status === "running") {
+            const timeout = input["timeout_seconds"];
+            const timeoutMs = typeof timeout === "number" && Number.isFinite(timeout)
+                ? Math.min(3600, Math.max(0, timeout)) * 1000 : undefined;
+            await mgr.waitForTask(id, ctx.signal, { timeoutMs, interrupted: ctx.waitInterrupted });
+            ctx.signal.throwIfAborted();
+        }
         const head = `${t.id} [${t.status}${t.exitCode != null ? ` · uscita ${t.exitCode}` : ""}] ${t.command}`;
         const output = `${head}\n${clamp(t.output) || "(nessun output)"}`;
         return t.status === "failed" || t.status === "killed" ? toolError(output) : output;
@@ -367,7 +382,7 @@ const READ_FINESTRA_BYTES = 2_000_000;
 const READ_SCAN_MAX_BYTES = 16_000_000;
 const READ_CHUNK_BYTES = 262_144;
 // Un read senza limit su un file grande ritorna comunque una finestra finita.
-const READ_RIGHE_DEFAULT_GRANDI = 1_000;
+const READ_RIGHE_DEFAULT_GRANDI = 200;
 // Lettura incrementale per righe di un file grande: chunk da 256KB, decoder
 // streaming (i confini multi-byte non si spezzano), respiro periodico per
 // l'event loop, stop appena la finestra richiesta e' completa.
@@ -437,14 +452,14 @@ async function leggiFinestra(abs, rel, taglia, offset, limit, ctx) {
 export const readTool = {
     name: "read_file",
     execution: "parallel",
-    description: "Legge un file di testo (path libero). Per sbirciarne solo una porzione usa " +
+    description: "Legge un file di testo (path libero), default 200 righe. Per scegliere una porzione usa " +
         "`offset` (riga di partenza, 1-based) e `limit` (numero di righe): NON serve bash/head/cat.",
     schema: {
         type: "object",
         properties: {
             path: { type: "string" },
             offset: { type: "number", description: "riga di partenza (1-based), default 1" },
-            limit: { type: "number", description: "numero massimo di righe da leggere" },
+            limit: { type: "number", description: "numero massimo di righe da leggere (default 200)" },
         },
         required: ["path"],
     },
@@ -461,8 +476,10 @@ export const readTool = {
                     mode: "viewing", others: conflicts, at: Date.now(),
                 });
             }
-            const offset = typeof input["offset"] === "number" && input["offset"] > 0 ? Math.floor(input["offset"]) : 1;
-            const limit = typeof input["limit"] === "number" && input["limit"] > 0 ? Math.floor(input["limit"]) : 0;
+            const offset = typeof input["offset"] === "number" && Number.isFinite(input["offset"]) && input["offset"] > 0
+                ? Math.max(1, Math.floor(input["offset"])) : 1;
+            const limit = typeof input["limit"] === "number" && Number.isFinite(input["limit"]) && input["limit"] > 0
+                ? Math.max(1, Math.floor(input["limit"])) : READ_RIGHE_DEFAULT_GRANDI;
             // I file grandi non si leggono mai integrali: finestra incrementale.
             const taglia = (await stat(abs)).size;
             const notaPresenza = conflicts.length
@@ -471,14 +488,13 @@ export const readTool = {
             if (taglia > READ_FINESTRA_BYTES)
                 return await leggiFinestra(abs, rel, taglia, offset, limit, ctx) + notaPresenza;
             const full = await readFile(abs, "utf8");
-            if (offset <= 1 && limit <= 0)
-                return paginate(full, `file ${rel}`, ctx) + notaPresenza;
             // Lettura parziale per righe (stile Claude Code): porzione [offset, offset+limit).
             const lines = full.split("\n");
             const start = Math.min(offset - 1, lines.length);
             const slice = limit > 0 ? lines.slice(start, start + limit) : lines.slice(start);
             const note = start + slice.length < lines.length || start > 0
-                ? `\n[righe ${start + 1}-${start + slice.length} di ${lines.length}]`
+                ? `\n[righe ${start + 1}-${start + slice.length} di ${lines.length}`
+                    + (start + slice.length < lines.length ? `; continua con read_file offset=${start + slice.length + 1} limit=${limit}` : "") + "]"
                 : "";
             return paginate(slice.join("\n"), `file ${rel}`, ctx) + note + notaPresenza;
         }
@@ -487,11 +503,11 @@ export const readTool = {
         }
     },
 };
-function acquireFileWrite(ctx, abs) {
+async function acquireFileWrite(ctx, abs) {
     const coordination = ctx.fileCoordination;
     if (!coordination)
         return "";
-    const outcome = coordination.hub.acquire(abs, coordination.actor);
+    const outcome = await coordination.hub.acquireAsync(abs, coordination.actor, ctx.signal);
     if (!outcome.ok) {
         coordination.emit?.({
             phase: "blocked", path: abs, actor: coordination.actor,
@@ -519,10 +535,10 @@ function validateFileWrite(ctx, lease) {
     return `conflitto file sopraggiunto: ${formatFileConflicts(conflicts)}. `
         + "La scrittura e' stata annullata senza sovrascrivere il lavoro concorrente.";
 }
-function releaseFileWrite(ctx, lease) {
+async function releaseFileWrite(ctx, lease) {
     if (typeof lease === "string" || !ctx.fileCoordination)
         return;
-    ctx.fileCoordination.hub.release(lease);
+    await ctx.fileCoordination.hub.releaseAsync(lease);
     ctx.fileCoordination.emit?.({
         phase: "released", path: lease.path, actor: lease.actor,
         mode: "writing", others: [], at: Date.now(),
@@ -587,7 +603,7 @@ export const writeTool = {
             }
             const abs = await safePath(ctx.cwd, rel, ctx.fsRoots);
             ctx.signal.throwIfAborted();
-            const lease = acquireFileWrite(ctx, abs);
+            const lease = await acquireFileWrite(ctx, abs);
             if (typeof lease === "string" && lease)
                 return { output: lease, isError: true };
             const append = input["append"] === true;
@@ -615,7 +631,7 @@ export const writeTool = {
                 return `${append ? "accodato" : "scritto"}: ${rel}${notaNul}`;
             }
             finally {
-                releaseFileWrite(ctx, lease);
+                await releaseFileWrite(ctx, lease);
             }
         }
         catch (err) {
@@ -755,7 +771,7 @@ export const editTool = {
             }
             const abs = await safePath(ctx.cwd, rel, ctx.fsRoots);
             ctx.signal.throwIfAborted();
-            const lease = acquireFileWrite(ctx, abs);
+            const lease = await acquireFileWrite(ctx, abs);
             if (typeof lease === "string" && lease)
                 return { output: lease, isError: true };
             try {
@@ -793,7 +809,7 @@ export const editTool = {
                 return `modificato: ${rel}${hint}${notaNul}`;
             }
             finally {
-                releaseFileWrite(ctx, lease);
+                await releaseFileWrite(ctx, lease);
             }
         }
         catch (err) {
@@ -862,6 +878,7 @@ export const recallTool = {
         properties: {
             query: { type: "string", description: "Testo da cercare nelle attivita archiviate" },
             rooms: { type: "array", items: { type: "string" }, description: "Id attivita da recuperare integralmente" },
+            attachments: { type: "boolean", description: "Con rooms: recupera le immagini originali del checkpoint come input visivo, on demand. Senza questa opzione restituisce solo l'indice." },
             files: { type: "array", items: { type: "string" }, description: "Path: restituisce le attivita che hanno toccato quei file (traversata del grafo)" },
             expand: { type: "boolean", description: "Se true, apre gruppi e liste fino alle singole attivita" },
             domains: { type: "array", items: { type: "string" }, description: "Domini memoria: rooms, plan, notes, skills, vision, assets, decisions, contracts, sessions (conversazioni passate)" },
@@ -893,6 +910,10 @@ export const recallTool = {
             const found = wantsRooms && mem.count() ? input["expand"] === true ? mem.expandRooms(rooms) : mem.byRooms(rooms) : [];
             if (!found.length)
                 return `nessuna attivita trovata per: ${rooms.join(", ")}`;
+            if (input["attachments"] === true) {
+                const media = mem.attachmentMedia(rooms);
+                return { output: found.map(r => r.body).join('\n\n---\n\n') + `\nAllegati visivi recuperati: ${media.length}.` + (media.length ? '' : ' Originali non disponibili; non dedurre dettagli visivi dal riepilogo.'), media };
+            }
             return paginate(found.map((r) => r.body).join("\n\n---\n\n"), "attivita", ctx);
         }
         // TRAVERSATA DEL GRAFO: "chi ha gia' messo le mani su questo file?".

package/dist/tools/capabilities.d.ts

@@ -1,5 +1,7 @@
 export declare const PROTOCOL_TOOLS: ReadonlySet<string>;
 export declare const NATIVE_CALL_TOOLS: ReadonlySet<string>;
+/** Desktop consent option; hosts and Fusion recognize the consent question by it. */
+export declare const COMPUTER_USE_CONSENT = "Consenti accesso al desktop";
 export declare const BUILTIN_CAPABILITIES: Readonly<Record<string, readonly string[]>>;
 export declare const BUILTIN_CONTINUATIONS: Readonly<Record<string, readonly string[]>>;
-export declare const COMPACT_TOOL_GUIDANCE = "Tool protocol: resolve and execute\nAll operation names mentioned elsewhere (bash, read_file, vascend_plan, ask_user, etc.)\nare internal tools. Use execute to call them; only tools in the native list can be\ncalled at top level. Interpret the user's language yourself and emit stable capability\nIDs; never translate file paths, search patterns or user data to discover a tool.\nresolve({capabilities:[\"process.run\",\"files.edit\"]}) returns exact tools, full input\ncontracts, continuations and a catalog revision. Reuse that revision and the contracts\nuntil stale_contract; do not resolve again for tools you already know.\nFamilies: files, process, output, plan, memory, user, workspace, code, web, image,\nskills, team, branches, market. resolve({namespace:\"files\"}) lists that family's\noperations; resolve({namespace:\"tools\"}) lists all installed tools in pages, including\nextensions. resolve({names:[\"read_file\",\"output_page\"]}) gets known names in one call.\nCommon capabilities: files.read/write/edit/search/find/list, process.run/observe,\nplan.create/update/inspect/note, user.ask, memory.recall, output.read.\nFor one operation: execute({mode:\"call\",revision,tool:\"read_file\",args:{path:\"src/a.ts\"}}).\nPrefer call mode for shell scripts and file edits. Use write_file/edit_file for UTF-8\nsource changes. In Python always specify encoding=\"utf-8\" when reading/writing text.\nFor sequences, pass payloads in data: execute({mode:\"program\",revision,data:{path:\"src/a.ts\"},code:\"return await tools.read_file({path:tools.$data.path});\"}).\nKeep scripts, file content and multiline text in data, never inside JavaScript\nstring literals; tools.$data contains this invocation's data, default {}.\nPrograms have tools, state, console and await; state persists per session, return emits\nthe result. Tools return text; tools.$result(name,args) also returns structuredContent,\ncontent and isError. Keep intermediate data in state and return only useful evidence.\nAwait dependent writes and approvals sequentially; use bounded Promise.allSettled for\nindependent work and inspect every outcome. Do not repeat a completed action on error.\nPrefer process.run with bash for rg, rg --files and git. Follow background processes\nwith bash_output through execute until the final exit status. Unknown or unavailable\ncapabilities require catalog inspection or independent work, never invented tool names.\nThe revision checks catalog freshness, not permission. All existing permission gates\nstill apply. Tools marked native must be called directly, including for images or\nincremental computer control when their contract requires it.";
+export declare const COMPACT_TOOL_GUIDANCE = "Tool protocol: resolve and execute\nAll operation names mentioned elsewhere (bash, read_file, vascend_plan, ask_user, etc.)\nare internal tools. Use execute to call them; only tools in the native list can be\ncalled at top level. Interpret the user's language yourself and emit stable capability\nIDs; never translate file paths, search patterns or user data to discover a tool.\nresolve({capabilities:[\"process.run\",\"files.edit\"]}) returns exact tools, full input\ncontracts, continuations and a catalog revision. Reuse that revision and the contracts\nuntil stale_contract; do not resolve again for tools you already know.\nFamilies: files, process, output, plan, memory, user, workspace, code, web, image,\nskills, team, branches, market. resolve({namespace:\"files\"}) lists that family's\noperations; resolve({namespace:\"tools\"}) lists all installed tools in pages, including\nextensions. resolve({names:[\"read_file\",\"output_page\"]}) gets known names in one call.\nCommon capabilities: files.read/write/edit/search/find/list, process.run/observe,\nplan.create/update/inspect/note, user.ask, memory.recall, output.read.\nFor one operation: execute({mode:\"call\",revision,tool:\"read_file\",args:{path:\"src/a.ts\"}}).\nPrefer call mode for shell scripts and file edits. Use write_file/edit_file for UTF-8\nsource changes. In Python always specify encoding=\"utf-8\" when reading/writing text.\nFor sequences, pass payloads in data: execute({mode:\"program\",revision,data:{path:\"src/a.ts\"},code:\"return await tools.read_file({path:tools.$data.path});\"}).\nKeep scripts, file content and multiline text in data, never inside JavaScript\nstring literals; tools.$data contains this invocation's data, default {}.\nPrograms have tools, state, console and await; state persists per session, return emits\nthe result. Tools return text; tools.$result(name,args) also returns structuredContent,\ncontent and isError. Keep intermediate data in state and return only useful evidence.\nAwait dependent writes and approvals sequentially; use bounded Promise.allSettled for\nindependent work and inspect every outcome. Do not repeat a completed action on error.\nPrefer process.run with bash for rg, rg --files and git. Collect a background result\nwith one bash_output call through execute: it waits locally for the final exit status.\nUse wait=false for persistent server snapshots, not repeated polling. Unknown or unavailable\ncapabilities require catalog inspection or independent work, never invented tool names.\nThe revision checks catalog freshness, not permission. All existing permission gates\nstill apply. Tools marked native must be called directly, including for images or\nincremental computer control when their contract requires it.";

package/dist/tools/capabilities.js

@@ -1,6 +1,8 @@
 // Local operational metadata. These declarations never confer permissions.
 export const PROTOCOL_TOOLS = new Set(["resolve", "execute"]);
 export const NATIVE_CALL_TOOLS = new Set(["computer_control", "computer_batch"]);
+/** Desktop consent option; hosts and Fusion recognize the consent question by it. */
+export const COMPUTER_USE_CONSENT = "Consenti accesso al desktop";
 export const BUILTIN_CAPABILITIES = {
     read_file: ["files.read"], write_file: ["files.write"], edit_file: ["files.edit"],
     grep: ["files.search"], glob: ["files.find"], list_dir: ["files.list"], file_activity: ["files.activity"],
@@ -47,8 +49,9 @@ the result. Tools return text; tools.$result(name,args) also returns structuredC
 content and isError. Keep intermediate data in state and return only useful evidence.
 Await dependent writes and approvals sequentially; use bounded Promise.allSettled for
 independent work and inspect every outcome. Do not repeat a completed action on error.
-Prefer process.run with bash for rg, rg --files and git. Follow background processes
-with bash_output through execute until the final exit status. Unknown or unavailable
+Prefer process.run with bash for rg, rg --files and git. Collect a background result
+with one bash_output call through execute: it waits locally for the final exit status.
+Use wait=false for persistent server snapshots, not repeated polling. Unknown or unavailable
 capabilities require catalog inspection or independent work, never invented tool names.
 The revision checks catalog freshness, not permission. All existing permission gates
 still apply. Tools marked native must be called directly, including for images or

package/dist/tools/computer-use.js

@@ -1,11 +1,12 @@
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { isAbsolute } from "node:path";
+import { COMPUTER_USE_CONSENT } from "./capabilities.js";
 import { captureComputerDesktop } from "./computer-capture.js";
 import { normalizeMcpToolResult } from "../mcp/protocol.js";
 import { posixComputerTools } from "./computer-posix.js";
 const require = createRequire(import.meta.url);
-const CONSENT = "Consenti accesso al desktop";
+const CONSENT = COMPUTER_USE_CONSENT;
 const unavailable = (output) => ({ output, isError: true });
 /** Standalone desktop tools. Loading definitions does not access the desktop. */
 export function registerComputerUse(registry, env, options = {}) {

package/dist/tools/pagination.js

@@ -4,7 +4,7 @@ import { ToolOutputStore } from "../core/tool-result-store.js";
 // mostra la prima pagina e si conserva il resto, recuperabile dal modello con il
 // tool output_page quando lo ritiene utile. Niente perdita di informazione.
 // Store di processo (in-memory), con eviction per non accumulare.
-const PAGE_CHARS = 30_000; // dimensione di una pagina
+const PAGE_CHARS = 8_000; // circa 2k token; dettagli ulteriori solo su richiesta
 const MAX_STORED = 5_000_000; // tetto per entry (5MB): oltre, si tronca a monte
 const MAX_ENTRIES = 24; // quante uscite lunghe tenere
 class PageStore {