@vascend/talos 0.1.0

package/dist/tools/capabilities.d.ts

@@ -0,0 +1,5 @@
+export declare const PROTOCOL_TOOLS: ReadonlySet<string>;
+export declare const NATIVE_CALL_TOOLS: ReadonlySet<string>;
+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.";

package/dist/tools/capabilities.js

@@ -0,0 +1,55 @@
+// 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"]);
+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"],
+    bash: ["process.run"], bash_output: ["process.observe"], wait: ["process.wait"],
+    output_page: ["output.read"], recall: ["memory.recall"], user_profile: ["memory.profile"],
+    vascend_plan: ["plan.create"], vascend_mark: ["plan.update"], vascend_status: ["plan.inspect"],
+    vascend_note: ["plan.note"], vascend_addtasks: ["plan.extend"], work_queue: ["plan.queue"],
+    ask_user: ["user.ask"], workspace_sessions: ["workspace.sessions"],
+    architecture_map: ["code.architecture"], web_fetch: ["web.fetch"], image_generate: ["image.generate"],
+    skill_search: ["skills.search"], skill_load: ["skills.load"], vascend_skill: ["skills.create"],
+    team_engage: ["team.engage"], team_say: ["team.send"], team_inbox: ["team.receive"],
+    team_wait: ["team.wait"], team_report: ["team.inspect"], market_compare: ["market.compare"],
+    ram_plan: ["branches.plan"], ram_status: ["branches.inspect"], ram_take: ["branches.take"],
+    ram_submit: ["branches.submit"], ram_ask: ["branches.ask"], ram_judge: ["branches.judge"],
+    ram_propose: ["branches.propose"], ram_decide: ["branches.decide"], ram_tell: ["branches.send"],
+    ram_hear: ["branches.receive"],
+};
+export const BUILTIN_CONTINUATIONS = {
+    bash: ["bash_output"], vascend_plan: ["vascend_mark", "vascend_status"],
+    skill_search: ["skill_load"], team_engage: ["team_say", "team_inbox", "team_report"],
+};
+export const COMPACT_TOOL_GUIDANCE = `Tool protocol: resolve and execute
+All operation names mentioned elsewhere (bash, read_file, vascend_plan, ask_user, etc.)
+are internal tools. Use execute to call them; only tools in the native list can be
+called at top level. Interpret the user's language yourself and emit stable capability
+IDs; never translate file paths, search patterns or user data to discover a tool.
+resolve({capabilities:["process.run","files.edit"]}) returns exact tools, full input
+contracts, continuations and a catalog revision. Reuse that revision and the contracts
+until stale_contract; do not resolve again for tools you already know.
+Families: files, process, output, plan, memory, user, workspace, code, web, image,
+skills, team, branches, market. resolve({namespace:"files"}) lists that family's
+operations; resolve({namespace:"tools"}) lists all installed tools in pages, including
+extensions. resolve({names:["read_file","output_page"]}) gets known names in one call.
+Common capabilities: files.read/write/edit/search/find/list, process.run/observe,
+plan.create/update/inspect/note, user.ask, memory.recall, output.read.
+For one operation: execute({mode:"call",revision,tool:"read_file",args:{path:"src/a.ts"}}).
+Prefer call mode for shell scripts and file edits. Use write_file/edit_file for UTF-8
+source changes. In Python always specify encoding="utf-8" when reading/writing text.
+For sequences, pass payloads in data: execute({mode:"program",revision,data:{path:"src/a.ts"},code:"return await tools.read_file({path:tools.$data.path});"}).
+Keep scripts, file content and multiline text in data, never inside JavaScript
+string literals; tools.$data contains this invocation's data, default {}.
+Programs have tools, state, console and await; state persists per session, return emits
+the result. Tools return text; tools.$result(name,args) also returns structuredContent,
+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
+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
+incremental computer control when their contract requires it.`;

package/dist/tools/computer-capture.d.ts

@@ -0,0 +1,2 @@
+export declare const CAPTURE_SCRIPT: string;
+export declare function captureComputerDesktop(input: Record<string, unknown>, signal?: AbortSignal): Promise<Record<string, unknown>>;

package/dist/tools/computer-capture.js

@@ -0,0 +1,91 @@
+import { spawn } from "node:child_process";
+// Fixed program; untrusted coordinates travel as JSON on stdin, never as code.
+export const CAPTURE_SCRIPT = String.raw `
+$ErrorActionPreference = 'Stop'
+Add-Type -AssemblyName System.Drawing
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type @'
+using System;
+using System.Runtime.InteropServices;
+public static class TalosCapture {
+  [StructLayout(LayoutKind.Sequential)] public struct Rect { public int Left, Top, Right, Bottom; }
+  [DllImport("user32.dll")] public static extern bool SetProcessDPIAware();
+  [DllImport("user32.dll")] public static extern IntPtr GetForegroundWindow();
+  [DllImport("user32.dll")] public static extern bool IsIconic(IntPtr window);
+  [DllImport("user32.dll")] public static extern bool GetWindowRect(IntPtr window, out Rect rect);
+}
+'@
+[void][TalosCapture]::SetProcessDPIAware()
+$p = [Console]::In.ReadToEnd() | ConvertFrom-Json
+$b = [System.Windows.Forms.Screen]::PrimaryScreen.Bounds
+if ($p.display) {
+  $screens = [System.Windows.Forms.Screen]::AllScreens
+  $selected = $null
+  for ($i = 0; $i -lt $screens.Length; $i++) {
+    if ([string]$i -eq [string]$p.display -or $screens[$i].DeviceName -eq [string]$p.display) { $selected = $screens[$i]; break }
+  }
+  if ($null -eq $selected) { throw 'Unknown display: use zero-based index or device name' }
+  $b = $selected.Bounds
+}
+if ($p.windowId) {
+  $window = [IntPtr]::new([long]$p.windowId)
+  if ([TalosCapture]::GetForegroundWindow() -ne $window -or [TalosCapture]::IsIconic($window)) { throw 'Attached window must be visible and in foreground' }
+  $r = New-Object TalosCapture+Rect
+  if (-not [TalosCapture]::GetWindowRect($window,[ref]$r)) { throw 'Window is no longer available' }
+  $b = New-Object System.Drawing.Rectangle($r.Left,$r.Top,($r.Right-$r.Left),($r.Bottom-$r.Top))
+}
+if ($b.Width -lt 1 -or $b.Height -lt 1 -or ([long]$b.Width*$b.Height) -gt 32000000) { throw 'Invalid capture bounds' }
+$bitmap = New-Object System.Drawing.Bitmap($b.Width,$b.Height)
+$graphics = [System.Drawing.Graphics]::FromImage($bitmap)
+$stream = New-Object System.IO.MemoryStream
+$scaled = $null
+try {
+  $graphics.CopyFromScreen($b.Location,[System.Drawing.Point]::Empty,$b.Size)
+  $scale = [Math]::Min(1,[Math]::Min(1600.0/$b.Width,1000.0/$b.Height))
+  $w = [Math]::Max(1,[int]($b.Width*$scale)); $h = [Math]::Max(1,[int]($b.Height*$scale))
+  $scaled = New-Object System.Drawing.Bitmap($bitmap,$w,$h)
+  $scaled.Save($stream,[System.Drawing.Imaging.ImageFormat]::Png)
+  @{data=[Convert]::ToBase64String($stream.ToArray());width=$w;height=$h;bounds=@{x=$b.X;y=$b.Y;width=$b.Width;height=$b.Height}} | ConvertTo-Json -Compress
+} finally {
+  if ($null -ne $scaled) { $scaled.Dispose() }
+  $stream.Dispose(); $graphics.Dispose(); $bitmap.Dispose()
+}
+`;
+export function captureComputerDesktop(input, signal) {
+    if (process.platform !== "win32")
+        return Promise.reject(new Error("Computer Use autonomo richiede Windows."));
+    return new Promise((resolve, reject) => {
+        const child = spawn("powershell.exe", ["-NoProfile", "-NonInteractive", "-EncodedCommand",
+            Buffer.from(CAPTURE_SCRIPT, "utf16le").toString("base64")], { windowsHide: true, signal });
+        const chunks = [];
+        let bytes = 0;
+        let error = "";
+        const timer = setTimeout(() => { child.kill(); reject(new Error("Timeout cattura desktop")); }, 20000);
+        child.stdout.on("data", (chunk) => {
+            bytes += chunk.length;
+            if (bytes > 12 * 1024 * 1024) {
+                child.kill();
+                reject(new Error("Screenshot troppo grande"));
+            }
+            else
+                chunks.push(chunk);
+        });
+        child.stderr.on("data", (chunk) => { error = (error + chunk.toString()).slice(-2000); });
+        child.on("error", (err) => { clearTimeout(timer); reject(err); });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            if (code !== 0) {
+                reject(new Error(error || `Cattura terminata: ${code}`));
+                return;
+            }
+            try {
+                resolve(JSON.parse(Buffer.concat(chunks).toString("utf8").trim()));
+            }
+            catch {
+                reject(new Error("Risposta cattura non valida"));
+            }
+        });
+        child.stdin.on("error", () => { });
+        child.stdin.end(JSON.stringify(input));
+    });
+}

package/dist/tools/computer-posix.d.ts

@@ -0,0 +1,5 @@
+import type { Tool } from "../core/types.js";
+export type DesktopRunner = (file: string, args: readonly string[], signal: AbortSignal) => Promise<string>;
+export declare const runDesktopCommand: DesktopRunner;
+/** Discrete desktop operations; factory is inert until the shared consent gate runs. */
+export declare function posixComputerTools(platform: "darwin" | "linux", env: NodeJS.ProcessEnv, run?: DesktopRunner): readonly Tool[];

package/dist/tools/computer-posix.js

@@ -0,0 +1,136 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+export const runDesktopCommand = (file, args, signal) => new Promise((resolve, reject) => {
+    execFile(file, [...args], { signal, timeout: 15_000, maxBuffer: 4_000_000, encoding: "utf8" }, (error, out, stderr) => {
+        if (error)
+            reject(new Error(`${file}: ${stderr.trim() || error.message}. Verifica installazione, sessione grafica e permessi desktop.`));
+        else
+            resolve(out.trim());
+    });
+});
+const string = (value, label) => {
+    if (typeof value !== "string" || !value.trim() || value.length > 4000 || value.includes("\0"))
+        throw new Error(`${label} non valido.`);
+    return value;
+};
+const integer = (value, label, min = 0, max = 100_000) => {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < min || value > max)
+        throw new Error(`${label} non valido.`);
+    return value;
+};
+const schemaString = { type: "string" };
+const schemaNumber = { type: "integer" };
+/** Discrete desktop operations; factory is inert until the shared consent gate runs. */
+export function posixComputerTools(platform, env, run = runDesktopCommand) {
+    const mac = platform === "darwin";
+    let target;
+    const check = () => {
+        if (!mac && (env["XDG_SESSION_TYPE"] === "wayland" || env["WAYLAND_DISPLAY"])) {
+            throw new Error("Wayland: controllo globale non disponibile. Usa una sessione X11; nessun bypass del consenso del compositor o fallback XWayland parziale.");
+        }
+        if (!mac && !env["DISPLAY"])
+            throw new Error("Nessun DISPLAY X11. Serve una sessione desktop locale, non headless/SSH.");
+    };
+    const command = (ctx, file, args) => {
+        if (ctx.signal.aborted)
+            throw new Error("Computer Use interrotto.");
+        return run(file, args, ctx.signal);
+    };
+    const apple = (ctx, source, args = []) => command(ctx, "/usr/bin/osascript", ["-e", `on run argv\n${source}\nend run`, "--", ...args]);
+    const focus = async (ctx) => {
+        if (!target)
+            throw new Error("Esegui computer_attach prima di inviare input.");
+        if (mac)
+            await apple(ctx, 'tell application "System Events" to set frontmost of first application process whose unix id is (item 1 of argv as integer) to true', [target]);
+        else
+            await command(ctx, "xdotool", ["windowactivate", "--sync", target]);
+    };
+    const tool = (name, description, properties, required, action) => ({
+        name, description, schema: { type: "object", properties, required, additionalProperties: false },
+        handler: async (input, ctx) => {
+            try {
+                if (ctx.signal.aborted)
+                    throw new Error("Computer Use interrotto.");
+                check();
+                return await action(input, ctx);
+            }
+            catch (error) {
+                return { output: error instanceof Error ? error.message : String(error), isError: true };
+            }
+        },
+    });
+    return [
+        { name: "computer_status", description: "Diagnostica backend desktop e prerequisiti senza leggere lo schermo.", schema: { type: "object", properties: {} }, handler: async () => ({ output: JSON.stringify({ platform, backend: mac ? "macOS Accessibility + cliclick" : "X11 + xdotool", availableSession: mac || Boolean(env["DISPLAY"]) && !env["WAYLAND_DISPLAY"] && env["XDG_SESSION_TYPE"] !== "wayland", prerequisites: mac ? ["Registrazione schermo e Accessibilità per terminale/runtime", "cliclick installato (brew install cliclick)"] : ["Sessione X11 locale", "xdotool", "ImageMagick: import"], limitations: "Nessuna UI Automation Windows/RAC; coordinate desktop native, non coordinate PNG ridimensionato." }) }) },
+        tool("computer_processes", "Elenca applicazioni visibili (macOS: PID) o finestre X11 (ID), da usare con computer_attach.", {}, [], async (_, ctx) => ({ output: mac
+                ? await apple(ctx, 'tell application "System Events"\nset rows to ""\nrepeat with p in (application processes whose background only is false)\nset rows to rows & (unix id of p as text) & tab & (name of p) & linefeed\nend repeat\nreturn rows\nend tell')
+                : await command(ctx, "xdotool", ["search", "--onlyvisible", "--name", "."]) })),
+        tool("computer_attach", "Collega e porta in primo piano un PID macOS o window ID X11 restituito da computer_processes.", { target: schemaString }, ["target"], async (input, ctx) => {
+            const next = string(input["target"], "target");
+            if (!/^\d{1,12}$/.test(next))
+                throw new Error("target deve essere un identificatore numerico.");
+            const previous = target;
+            target = next;
+            try {
+                await focus(ctx);
+            }
+            catch (error) {
+                target = previous;
+                throw error;
+            }
+            return { output: `Target collegato: ${target}. Usa computer_snapshot per osservare prima di agire.` };
+        }),
+        tool("computer_snapshot", "Cattura desktop intero in PNG come immagine. Può includere altre app e dati sensibili; non è una cattura isolata del target.", {}, [], async (_, ctx) => {
+            const dir = await mkdtemp(join(tmpdir(), "talos-desktop-"));
+            try {
+                const path = join(dir, "screen.png");
+                if (mac)
+                    await command(ctx, "/usr/sbin/screencapture", ["-x", "-t", "png", path]);
+                else
+                    await command(ctx, "import", ["-window", "root", path]);
+                const bytes = await readFile(path);
+                if (bytes.length > 12_000_000 || bytes.length < 24 || bytes.subarray(0, 8).toString("hex") !== "89504e470d0a1a0a")
+                    throw new Error("Screenshot PNG non valido o oltre 12 MB.");
+                return { content: [{ type: "text", text: JSON.stringify({ width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20), coordinates: "desktop native; su Retina i pixel PNG possono differire dai punti mouse", target: target ?? null }) }, { type: "image", mimeType: "image/png", data: bytes.toString("base64") }] };
+            }
+            finally {
+                await rm(dir, { recursive: true, force: true });
+            }
+        }),
+        tool("computer_click", "Click su coordinate native del desktop dopo attach. Osserva lo screenshot e verifica l'esito; su Retina usa punti desktop.", { x: schemaNumber, y: schemaNumber, button: { type: "string", enum: ["left", "right"] } }, ["x", "y"], async (input, ctx) => {
+            const x = integer(input["x"], "x"), y = integer(input["y"], "y");
+            if (input["button"] !== undefined && !["left", "right"].includes(String(input["button"])))
+                throw new Error("button non valido.");
+            await focus(ctx);
+            await command(ctx, mac ? "cliclick" : "xdotool", mac ? [`${input["button"] === "right" ? "rc" : "c"}:${x},${y}`] : ["mousemove", "--sync", String(x), String(y), "click", input["button"] === "right" ? "3" : "1"]);
+            return { output: "Click inviato. Verifica con computer_snapshot; invio non equivale a successo dell'azione." };
+        }),
+        tool("computer_scroll", "Scorre il target focalizzato. Linux: rotella X11; macOS: tasti pagina, non movimento pixel preciso.", { direction: { type: "string", enum: ["up", "down"] }, amount: schemaNumber }, ["direction"], async (input, ctx) => {
+            if (input["direction"] !== "up" && input["direction"] !== "down")
+                throw new Error("direction non valida.");
+            const amount = integer(input["amount"] ?? 1, "amount", 1, 20);
+            await focus(ctx);
+            await command(ctx, mac ? "cliclick" : "xdotool", mac
+                ? Array.from({ length: amount }, () => `kp:${input["direction"] === "up" ? "page-up" : "page-down"}`)
+                : ["click", "--repeat", String(amount), "--delay", "50", input["direction"] === "up" ? "4" : "5"]);
+            return { output: "Scorrimento inviato. Verifica la posizione con computer_snapshot." };
+        }),
+        tool("computer_type", "Digita testo nel controllo già focalizzato del target. Non cambia clipboard e non preme Invio.", { text: schemaString }, ["text"], async (input, ctx) => {
+            const text = string(input["text"], "text");
+            await focus(ctx);
+            await command(ctx, mac ? "cliclick" : "xdotool", mac ? [`t:${text}`] : ["type", "--clearmodifiers", "--", text]);
+            return { output: "Testo inviato; verifica il controllo prima di proseguire." };
+        }),
+        tool("computer_key", "Invia un tasto discreto: enter, tab, escape, backspace, up, down, left, right. Non accetta codice o combinazioni arbitrarie.", { key: { type: "string", enum: ["enter", "tab", "escape", "backspace", "up", "down", "left", "right"] } }, ["key"], async (input, ctx) => {
+            const keys = { enter: ["return", "Return"], tab: ["tab", "Tab"], escape: ["esc", "Escape"], backspace: ["delete", "BackSpace"], up: ["arrow-up", "Up"], down: ["arrow-down", "Down"], left: ["arrow-left", "Left"], right: ["arrow-right", "Right"] };
+            const keyName = String(input["key"]);
+            const key = Object.hasOwn(keys, keyName) ? keys[keyName] : undefined;
+            if (!key)
+                throw new Error("key non valido.");
+            await focus(ctx);
+            await command(ctx, mac ? "cliclick" : "xdotool", mac ? [`kp:${key[0]}`] : ["key", "--clearmodifiers", key[1]]);
+            return { output: "Tasto inviato; verifica l'esito." };
+        }),
+    ];
+}

package/dist/tools/computer-use.d.ts

@@ -0,0 +1,14 @@
+import type { Tool } from "../core/types.js";
+import type { ToolRegistry } from "./registry.js";
+import { captureComputerDesktop } from "./computer-capture.js";
+import { type DesktopRunner } from "./computer-posix.js";
+export interface ComputerUseModule {
+    computerUseTools(options: Record<string, unknown>): readonly Tool[];
+}
+/** Standalone desktop tools. Loading definitions does not access the desktop. */
+export declare function registerComputerUse(registry: ToolRegistry, env: NodeJS.ProcessEnv, options?: {
+    platform?: string;
+    load?: (path: string) => ComputerUseModule;
+    capture?: typeof captureComputerDesktop;
+    runDesktop?: DesktopRunner;
+}): readonly string[];

package/dist/tools/computer-use.js

@@ -0,0 +1,108 @@
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { isAbsolute } from "node:path";
+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 unavailable = (output) => ({ output, isError: true });
+/** Standalone desktop tools. Loading definitions does not access the desktop. */
+export function registerComputerUse(registry, env, options = {}) {
+    if (env["TALOS_COMPUTER_USE"] === "0" || env["TALOS_HOST_PROFILE"]?.trim().toLowerCase() === "horizon")
+        return [];
+    const override = env["TALOS_COMPUTER_USE_MODULE"]?.trim();
+    const platform = options.platform ?? process.platform;
+    if (!["win32", "darwin", "linux"].includes(platform))
+        return [];
+    if (override && platform !== "win32")
+        throw new Error("Override Horizon disponibile solo su Windows; macOS/Linux usano il backend POSIX incorporato.");
+    const path = override ?? fileURLToPath(new URL("../vendor/computer-use/computer-tools.js", import.meta.url));
+    if (!isAbsolute(path))
+        throw new Error("TALOS_COMPUTER_USE_MODULE deve essere un percorso assoluto a computer-tools.js di Horizon.");
+    const module = platform === "win32"
+        ? (options.load ?? ((file) => require(file)))(path)
+        : { computerUseTools: () => posixComputerTools(platform, env, options.runDesktop) };
+    if (typeof module.computerUseTools !== "function")
+        throw new Error("Modulo Computer Use incompatibile: manca computerUseTools.");
+    const capture = options.capture ?? captureComputerDesktop;
+    const excluded = new Set((env["TALOS_EXCLUDE_TOOLS"] ?? "").split(",").map((name) => name.trim()));
+    // Each session owns its target, snapshots and permission. A global queue
+    // prevents competing sessions/tools from driving the same physical desktop.
+    const sessions = new Map();
+    let tail = Promise.resolve();
+    const createSession = () => {
+        const state = { tools: [], approved: false };
+        state.tools = module.computerUseTools({
+            captureDesktop: (input) => capture(input, state.signal),
+            // CLI uses native UI Automation and discrete controls, not Electron RAC.
+            racStrictMode: false,
+        });
+        return state;
+    };
+    const definitions = createSession().tools;
+    if (!definitions.length)
+        throw new Error("Modulo Computer Use senza strumenti.");
+    const names = [];
+    for (const tool of definitions) {
+        if (!/^computer_[a-z_]+$/.test(tool.name) || typeof tool.handler !== "function") {
+            throw new Error("Definizione Computer Use incompatibile.");
+        }
+        if (/^computer_(control|control_reset|reactive_goal|reactive_status)$/.test(tool.name))
+            continue;
+        if (excluded.has(tool.name) || registry.get(tool.name))
+            continue;
+        registry.register({ ...tool, execution: "serial", handler: async (input, ctx) => {
+                const run = async () => {
+                    if (ctx.signal.aborted)
+                        return unavailable("Computer Use interrotto.");
+                    if (ctx.executionTarget && ctx.executionTarget.kind !== "local") {
+                        return unavailable("Computer Use non controlla il desktop locale da un target remoto.");
+                    }
+                    const key = ctx.sessionId ?? "standalone";
+                    const state = sessions.get(key) ?? createSession();
+                    sessions.delete(key);
+                    sessions.set(key, state);
+                    // Retain only a small LRU of inactive session targets/screenshots.
+                    if (sessions.size > 8)
+                        sessions.delete(sessions.keys().next().value);
+                    // Deliberately do not use the generic auto-approval gate: --yolo is
+                    // not device consent. Noninteractive callers need explicit env opt-in.
+                    if (!state.approved) {
+                        state.approved = env["TALOS_COMPUTER_USE_CONSENT"] === "session"
+                            || await ctx.ask?.("Computer Use può leggere lo schermo e controllare mouse/tastiera per questa sessione. Autorizzi?", [CONSENT, "Nega"]) === CONSENT;
+                    }
+                    if (ctx.signal.aborted)
+                        return unavailable("Computer Use interrotto.");
+                    if (!state.approved)
+                        return unavailable("Consenso desktop negato o assente. In modalità non interattiva serve TALOS_COMPUTER_USE_CONSENT=session; --yolo non basta.");
+                    state.signal = ctx.signal;
+                    const actual = state.tools.find((item) => item.name === tool.name);
+                    if (!actual)
+                        return unavailable(`Tool Computer Use non disponibile: ${tool.name}`);
+                    const context = { ...ctx, confirm: async (action, detail) => !ctx.signal.aborted && (action === "computer_use" ? state.approved : ctx.confirm(action, detail)) };
+                    try {
+                        const result = normalizeMcpToolResult(await actual.handler(input, context));
+                        // Horizon envelopes sometimes encode failures in text/structuredContent.
+                        const text = result.content.find((part) => part.type === "text");
+                        let payload = result.structuredContent;
+                        if (!payload && text?.type === "text") {
+                            try {
+                                payload = JSON.parse(text.text);
+                            }
+                            catch { /* plain text */ }
+                        }
+                        return payload?.["ok"] === false ? { ...result, isError: true } : result;
+                    }
+                    finally {
+                        state.signal = undefined;
+                    }
+                };
+                const pending = tail.then(run, run);
+                tail = pending.catch(() => { });
+                return pending;
+            } }, true);
+        names.push(tool.name);
+    }
+    return names;
+}

package/dist/tools/discovery.d.ts

@@ -0,0 +1,12 @@
+import type { Tool } from "../core/types.js";
+export declare const DISCOVERY_TOOL_NAMES: ReadonlySet<string>;
+export declare const LEGACY_DISCOVERY_TOOL_NAMES: ReadonlySet<string>;
+export declare const ESSENTIAL_TOOL_NAMES: ReadonlySet<string>;
+export declare const CLI_DIRECT_TOOL_NAMES: ReadonlySet<string>;
+export declare const FILE_DISCOVERY_TOOL_NAMES: readonly ["list_dir", "glob", "grep", "file_activity"];
+export declare const HORIZON_DIRECT_TOOL_NAMES: ReadonlySet<string>;
+type DiscoveryRegistry = NonNullable<Parameters<Tool["handler"]>[1]["tools"]>;
+export declare function toolInventory(tools: DiscoveryRegistry): readonly ReturnType<DiscoveryRegistry["catalog"]>[number][];
+export declare const toolListTool: Tool;
+export declare const toolDescribeTool: Tool;
+export {};