castle-web-cli 0.4.78 → 0.4.79

package/dist/native/tools.js

@@ -0,0 +1,630 @@
+// Tool schemas + executors for the native agent loop (native/loop.ts). Role
+// scoping mirrors today's CLI trust levels (agent.ts's buildAgentInvocation):
+// the router is read-only (read_file/list_files/grep/view_image), task agents
+// get everything including bash at full-shell trust (matches the existing
+// `--force` level -- ratified, not revisited here; sandboxing is a later,
+// separate concern for end users).
+//
+// Every call goes through `executeTool`, which is the ratified
+// policy-checkable seam: role scoping is enforced there (not just by
+// omitting a tool's schema from what the model is offered -- a model can
+// still hallucinate a call to a tool it wasn't given), and an optional
+// `checkPolicy` hook on ToolExecContext lets a future caller reject
+// individual calls (e.g. "don't write to a sibling-claimed drawing file")
+// without touching the executors themselves. No policy exists yet --
+// `checkPolicy` defaults to allow-everything.
+import { spawn } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import picomatch from "picomatch";
+import { PLAYTEST_TOOL_DESCRIPTION, PLAYTEST_TOOL_PARAMETERS, runPlaytest, } from "./playtest.js";
+function err(message) {
+    return { ok: false, output: `Error: ${message}` };
+}
+// Mirrors PROGRESS_FILE_RE / the .castle/ exclusion in agent.ts's
+// normalizeTouchedPath, so a native task's filesTouched reads the same as a
+// CLI task's once wired together.
+const PROGRESS_FILE_RE = /\.castle\/agent\/tasks\/[^/]+\/progress$/;
+function isTrackedTouch(rel) {
+    if (rel.startsWith(".castle/"))
+        return false;
+    if (PROGRESS_FILE_RE.test(rel))
+        return false;
+    return true;
+}
+// Mirrors DECK_TREE_EXCLUDE in agent.ts.
+const IGNORED_DIRS = new Set(["node_modules", ".castle", ".git", "dist", ".DS_Store"]);
+const MAX_WALK_FILES = 20_000;
+function baseName(p) {
+    const parts = p.split(/[\\/]/).filter(Boolean);
+    return parts[parts.length - 1] || p;
+}
+// Resolves a tool-supplied path against the deck dir and rejects any escape
+// (absolute paths outside it, `..` traversal). Returns both the absolute path
+// and a deck-root-relative path (forward-slashed, for display and for
+// filesTouched entries).
+function resolveInDeck(deckDir, rawPath) {
+    if (typeof rawPath !== "string" || rawPath.trim() === "")
+        return null;
+    const abs = path.resolve(deckDir, rawPath);
+    const rel = path.relative(deckDir, abs);
+    if (rel.startsWith("..") || path.isAbsolute(rel))
+        return null;
+    return { abs, rel: rel.split(path.sep).join("/") };
+}
+// Sorted recursive file walk (deterministic order matters for grep/list_files
+// results and for tests), skipping IGNORED_DIRS at any depth. Capped as a
+// safety valve against pathological trees, not as a normal limit -- decks are
+// modest-sized web projects.
+function walkFiles(root) {
+    const out = [];
+    const walk = (dir) => {
+        if (out.length >= MAX_WALK_FILES)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of entries) {
+            if (IGNORED_DIRS.has(entry.name))
+                continue;
+            const abs = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(abs);
+            }
+            else if (entry.isFile()) {
+                out.push(abs);
+                if (out.length >= MAX_WALK_FILES)
+                    return;
+            }
+        }
+    };
+    walk(root);
+    return out;
+}
+// -- read_file ----------------------------------------------------------------
+const READ_RAW_SIZE_CAP = 2 * 1024 * 1024; // 2MB
+const READ_DEFAULT_LINE_LIMIT = 2000;
+// Extensions read_file refuses outright as binary: dumping decoded-as-utf8
+// garbage into the context helps nobody and burns tokens. Ratified decision
+// (2026-07): images reach the model as image content parts -- user
+// attachments ride the initial message, and any deck image is viewable via
+// the view_image tool -- so the error redirects there instead of returning
+// raw bytes. Grep's \0 sniff below catches binaries this extension list
+// misses.
+const BINARY_READ_EXTS = new Set([
+    ".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".ico",
+    ".mp3", ".wav", ".ogg", ".mp4", ".webm", ".mov",
+    ".woff", ".woff2", ".ttf", ".otf", ".zip", ".tgz", ".gz", ".wasm",
+]);
+function readFileRun(args, ctx) {
+    const resolved = resolveInDeck(ctx.deckDir, args.path);
+    if (!resolved)
+        return err(`path escapes the deck directory: ${String(args.path)}`);
+    let stat;
+    try {
+        stat = fs.statSync(resolved.abs);
+    }
+    catch {
+        return err(`no such file: ${resolved.rel}`);
+    }
+    if (!stat.isFile())
+        return err(`not a file: ${resolved.rel}`);
+    const ext = path.extname(resolved.rel).toLowerCase();
+    if (BINARY_READ_EXTS.has(ext)) {
+        return err(`${resolved.rel} is a binary/image file -- it cannot be read as text. Use the view_image tool to look at image files.`);
+    }
+    const offset = Number.isInteger(args.offset) && args.offset > 0 ? args.offset : 1;
+    const limit = Number.isInteger(args.limit) && args.limit > 0 ? args.limit : undefined;
+    if (stat.size > READ_RAW_SIZE_CAP && offset === 1 && limit === undefined) {
+        return err(`${resolved.rel} is too large to read in full (> ${READ_RAW_SIZE_CAP} bytes) -- pass offset/limit to read a slice.`);
+    }
+    let content;
+    try {
+        content = fs.readFileSync(resolved.abs, "utf8");
+    }
+    catch (e) {
+        return err(`could not read ${resolved.rel}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (content.includes("\u0000")) {
+        return err(`${resolved.rel} looks binary (contains NUL bytes) -- it cannot be read as text.`);
+    }
+    const lines = content.split("\n");
+    const effectiveLimit = limit ?? READ_DEFAULT_LINE_LIMIT;
+    const slice = lines.slice(offset - 1, offset - 1 + effectiveLimit);
+    const numbered = slice.map((l, i) => `${offset + i}\t${l}`).join("\n");
+    const truncated = offset - 1 + effectiveLimit < lines.length;
+    return {
+        ok: true,
+        output: numbered + (truncated ? `\n... (${lines.length - (offset - 1 + effectiveLimit)} more lines -- use offset/limit to continue)` : ""),
+    };
+}
+// -- view_image -----------------------------------------------------------------
+// Raster formats vision models accept as data URIs. SVG is deliberately
+// absent: it's a text format the model can read (and reason about) via
+// read_file, and providers don't rasterize it.
+const VIEW_IMAGE_MIME = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+};
+// Pre-base64 cap. Matches the serve's own attachment ingest ceiling closely
+// enough that anything a user could paste is viewable; deck art beyond this
+// is almost certainly not something a model needs at full resolution.
+const VIEW_IMAGE_SIZE_CAP = 4 * 1024 * 1024;
+// Delivery note (the wrinkle this tool is built around): in the OpenAI
+// chat-completions shape, role:"tool" messages accept only TEXT content
+// reliably -- image blocks inside tool results are not consistently
+// supported across the providers OpenRouter fronts. The robust pattern
+// (used by every major harness) is: the tool result SAYS the image follows,
+// and the loop appends a synthetic role:"user" message carrying the actual
+// image_url block immediately after the batch's tool results. That is what
+// `imageDataUrl` implements -- see runToolCalls in loop.ts.
+//
+// Path confinement is the same resolveInDeck as every file tool; note that
+// user attachments live at .castle/agent/attachments/ INSIDE the deck, so
+// they are reachable here (the .castle/ exclusions elsewhere apply to
+// filesTouched tracking and tree walks, never to reads).
+function viewImageRun(args, ctx) {
+    const resolved = resolveInDeck(ctx.deckDir, args.path);
+    if (!resolved)
+        return err(`path escapes the deck directory: ${String(args.path)}`);
+    const mime = VIEW_IMAGE_MIME[path.extname(resolved.rel).toLowerCase()];
+    if (!mime) {
+        return err(`${resolved.rel} is not a viewable image -- view_image supports png/jpg/jpeg/gif/webp. SVG and other text formats can be read with read_file.`);
+    }
+    let stat;
+    try {
+        stat = fs.statSync(resolved.abs);
+    }
+    catch {
+        return err(`no such file: ${resolved.rel}`);
+    }
+    if (!stat.isFile())
+        return err(`not a file: ${resolved.rel}`);
+    if (stat.size > VIEW_IMAGE_SIZE_CAP) {
+        return err(`${resolved.rel} is too large to view (${(stat.size / (1024 * 1024)).toFixed(1)}MB > ${VIEW_IMAGE_SIZE_CAP / (1024 * 1024)}MB).`);
+    }
+    let data;
+    try {
+        data = fs.readFileSync(resolved.abs);
+    }
+    catch (e) {
+        return err(`could not read ${resolved.rel}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    return {
+        ok: true,
+        output: `Viewing ${resolved.rel} (${mime}, ${(stat.size / 1024).toFixed(1)}KB) -- the image follows in the next message.`,
+        images: [{ label: `view_image ${resolved.rel}`, dataUrl: `data:${mime};base64,${data.toString("base64")}` }],
+    };
+}
+// -- write_file -----------------------------------------------------------------
+function writeFileRun(args, ctx) {
+    const resolved = resolveInDeck(ctx.deckDir, args.path);
+    if (!resolved)
+        return err(`path escapes the deck directory: ${String(args.path)}`);
+    if (typeof args.content !== "string")
+        return err("write_file requires a `content` string.");
+    try {
+        fs.mkdirSync(path.dirname(resolved.abs), { recursive: true });
+        fs.writeFileSync(resolved.abs, args.content, "utf8");
+    }
+    catch (e) {
+        return err(`could not write ${resolved.rel}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const filesTouched = isTrackedTouch(resolved.rel) ? [resolved.rel] : [];
+    return {
+        ok: true,
+        output: `Wrote ${resolved.rel} (${Buffer.byteLength(args.content, "utf8")} bytes).`,
+        filesTouched,
+    };
+}
+// -- edit_file ------------------------------------------------------------------
+function countOccurrences(haystack, needle) {
+    return needle === "" ? 0 : haystack.split(needle).length - 1;
+}
+function editFileRun(args, ctx) {
+    const resolved = resolveInDeck(ctx.deckDir, args.path);
+    if (!resolved)
+        return err(`path escapes the deck directory: ${String(args.path)}`);
+    if (typeof args.old_string !== "string" || typeof args.new_string !== "string") {
+        return err("edit_file requires `old_string` and `new_string` strings.");
+    }
+    if (args.old_string === "")
+        return err("old_string must not be empty.");
+    if (args.old_string === args.new_string) {
+        return err("old_string and new_string are identical -- nothing to change.");
+    }
+    let content;
+    try {
+        content = fs.readFileSync(resolved.abs, "utf8");
+    }
+    catch {
+        return err(`no such file: ${resolved.rel}`);
+    }
+    const count = countOccurrences(content, args.old_string);
+    if (count === 0)
+        return err(`old_string not found in ${resolved.rel}.`);
+    const replaceAll = args.replace_all === true;
+    if (count > 1 && !replaceAll) {
+        return err(`old_string appears ${count} times in ${resolved.rel} -- it must uniquely identify one location. Include more surrounding context, or pass replace_all: true to replace every occurrence.`);
+    }
+    const next = replaceAll
+        ? content.split(args.old_string).join(args.new_string)
+        : content.replace(args.old_string, args.new_string);
+    try {
+        fs.writeFileSync(resolved.abs, next, "utf8");
+    }
+    catch (e) {
+        return err(`could not write ${resolved.rel}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const filesTouched = isTrackedTouch(resolved.rel) ? [resolved.rel] : [];
+    return {
+        ok: true,
+        output: `Edited ${resolved.rel}${replaceAll ? ` (${count} replacements)` : ""}.`,
+        filesTouched,
+    };
+}
+// -- list_files -----------------------------------------------------------------
+const LIST_FILES_MAX_RESULTS = 500;
+function listFilesRun(args, ctx) {
+    const startPath = typeof args.path === "string" && args.path ? args.path : ".";
+    const resolved = resolveInDeck(ctx.deckDir, startPath);
+    if (!resolved)
+        return err(`path escapes the deck directory: ${startPath}`);
+    if (!fs.existsSync(resolved.abs))
+        return err(`no such directory: ${resolved.rel || "."}`);
+    const pattern = typeof args.pattern === "string" && args.pattern ? args.pattern : "**/*";
+    let isMatch;
+    try {
+        isMatch = picomatch(pattern, { dot: false });
+    }
+    catch (e) {
+        return err(`invalid glob pattern: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const files = walkFiles(resolved.abs);
+    const matches = [];
+    for (const abs of files) {
+        const relFromStart = path.relative(resolved.abs, abs).split(path.sep).join("/");
+        if (!isMatch(relFromStart))
+            continue;
+        matches.push(path.relative(ctx.deckDir, abs).split(path.sep).join("/"));
+        if (matches.length >= LIST_FILES_MAX_RESULTS)
+            break;
+    }
+    if (matches.length === 0)
+        return { ok: true, output: "(no files matched)" };
+    const truncated = matches.length >= LIST_FILES_MAX_RESULTS;
+    return {
+        ok: true,
+        output: matches.join("\n") + (truncated ? `\n... (capped at ${LIST_FILES_MAX_RESULTS} results)` : ""),
+    };
+}
+// -- grep -------------------------------------------------------------------
+const GREP_MAX_RESULTS = 200;
+function grepRun(args, ctx) {
+    if (typeof args.pattern !== "string" || args.pattern === "") {
+        return err("grep requires a non-empty `pattern` string.");
+    }
+    let re;
+    try {
+        re = new RegExp(args.pattern, args.case_insensitive === true ? "i" : "");
+    }
+    catch (e) {
+        return err(`invalid regular expression: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const startPath = typeof args.path === "string" && args.path ? args.path : ".";
+    const resolved = resolveInDeck(ctx.deckDir, startPath);
+    if (!resolved)
+        return err(`path escapes the deck directory: ${startPath}`);
+    if (!fs.existsSync(resolved.abs))
+        return err(`no such directory: ${resolved.rel || "."}`);
+    let globMatch = null;
+    if (typeof args.glob === "string" && args.glob) {
+        try {
+            globMatch = picomatch(args.glob, { dot: false });
+        }
+        catch (e) {
+            return err(`invalid glob pattern: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    const files = walkFiles(resolved.abs);
+    const results = [];
+    outer: for (const abs of files) {
+        const relFromDeck = path.relative(ctx.deckDir, abs).split(path.sep).join("/");
+        if (globMatch && !globMatch(relFromDeck))
+            continue;
+        let content;
+        try {
+            content = fs.readFileSync(abs, "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (content.includes("\u0000"))
+            continue; // looks binary -- skip
+        const lines = content.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            if (re.test(lines[i])) {
+                results.push(`${relFromDeck}:${i + 1}:${lines[i]}`);
+                if (results.length >= GREP_MAX_RESULTS)
+                    break outer;
+            }
+        }
+    }
+    if (results.length === 0)
+        return { ok: true, output: "(no matches)" };
+    const truncated = results.length >= GREP_MAX_RESULTS;
+    return {
+        ok: true,
+        output: results.join("\n") + (truncated ? `\n... (capped at ${GREP_MAX_RESULTS} matches)` : ""),
+    };
+}
+// -- bash -------------------------------------------------------------------
+// Full shell, trusted -- matches today's --force trust level for task agents
+// (ratified; not revisited here). cwd is always the deck dir; per-call
+// timeout defaults to 2 minutes and can be raised up to 10 minutes by the
+// model for known-slow commands (npm install, etc.), never higher.
+const BASH_DEFAULT_TIMEOUT_MS = 2 * 60_000;
+const BASH_MAX_TIMEOUT_MS = 10 * 60_000;
+// Success and failure get different caps: every tool result stays in context
+// and gets re-read on every later iteration, so a clean exit only needs
+// enough output to confirm it worked (npm install's dependency tree, a build's
+// asset list) -- 4KB is generous for that. A NONZERO exit is a different
+// case entirely: stderr/stdout there is how the model debugs, so it keeps the
+// old, much larger cap rather than risk truncating away the actual error.
+const BASH_OUTPUT_CAP_OK = 4_000;
+const BASH_OUTPUT_CAP_ERROR = 20_000;
+function bashRun(args, ctx) {
+    if (typeof args.command !== "string" || args.command.trim() === "") {
+        return Promise.resolve(err("bash requires a non-empty `command` string."));
+    }
+    const command = args.command;
+    const requested = Number.isInteger(args.timeout_ms) ? args.timeout_ms : undefined;
+    const timeoutMs = requested && requested > 0 ? Math.min(requested, BASH_MAX_TIMEOUT_MS) : BASH_DEFAULT_TIMEOUT_MS;
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn(command, {
+                shell: true,
+                cwd: ctx.deckDir,
+                timeout: timeoutMs,
+                killSignal: "SIGKILL",
+                signal: ctx.signal,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+        }
+        catch (e) {
+            resolve(err(`could not run command: ${e instanceof Error ? e.message : String(e)}`));
+            return;
+        }
+        let out = "";
+        child.stdout?.on("data", (d) => {
+            out += d.toString("utf8");
+        });
+        child.stderr?.on("data", (d) => {
+            out += d.toString("utf8");
+        });
+        child.on("error", (e) => {
+            resolve(err(`could not run command: ${e.message}`));
+        });
+        child.on("close", (code, signal) => {
+            const ok = code === 0;
+            const cap = ok ? BASH_OUTPUT_CAP_OK : BASH_OUTPUT_CAP_ERROR;
+            const capped = out.length > cap
+                ? `${out.slice(0, cap)}\n... (output truncated at ${cap} chars)`
+                : out;
+            const timedOutNote = code === null && signal ? `\n[terminated by signal ${signal} -- likely the ${timeoutMs}ms per-command timeout]` : "";
+            // The command itself is NOT echoed back here -- it's already sitting in
+            // the assistant's own tool_call (which, unlike this result, is never
+            // evicted from context -- see evictOldToolResults in loop.ts), so
+            // repeating it would just be the same bytes twice on every later turn.
+            resolve({
+                ok,
+                output: `(exit ${code ?? "null"})\n${capped}${timedOutNote}`,
+            });
+        });
+    });
+}
+// -- restart ------------------------------------------------------------------
+// In-process replacement for the bash pattern `npm run restart`: that command
+// spawns node + the castle-web CLI + a WebSocket client just to send the
+// serve ONE `{type:'restart'}` message -- wasted process-spawn latency when
+// the smith loop and the serve already share a process (unlike cursor/claude,
+// which really do need a subprocess to reach the serve). ctx.restart (wired
+// from createAgentServer -> serve.ts) does the exact same invalidate-then-
+// reload-every-tab work directly.
+function restartRun(ctx) {
+    if (!ctx.restart) {
+        return err("restart has no in-process hook wired up in this context (this deck isn't being run through a serve that supports it) -- fall back to `bash: npm run restart`.");
+    }
+    ctx.restart();
+    return { ok: true, output: "Reloaded the deck in every connected browser tab." };
+}
+const READ_ONLY_ROLES = ["router", "task"];
+const TASK_ONLY_ROLES = ["task"];
+const TOOLS = [
+    {
+        name: "read_file",
+        description: "Read a text file from the deck, optionally a line slice. Text only -- image/binary files are rejected (use view_image for images).",
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "File path relative to the deck directory." },
+                offset: { type: "integer", description: "1-indexed line number to start reading from." },
+                limit: { type: "integer", description: "Maximum number of lines to read." },
+            },
+            required: ["path"],
+        },
+        roles: READ_ONLY_ROLES,
+        run: readFileRun,
+    },
+    {
+        name: "list_files",
+        description: "List files in the deck matching a glob pattern.",
+        parameters: {
+            type: "object",
+            properties: {
+                pattern: { type: "string", description: "Glob pattern, e.g. '**/*.js'. Defaults to '**/*'." },
+                path: { type: "string", description: "Directory to search from, relative to the deck root. Defaults to '.'." },
+            },
+        },
+        roles: READ_ONLY_ROLES,
+        run: listFilesRun,
+    },
+    {
+        name: "grep",
+        description: "Search file contents in the deck for a regular expression.",
+        parameters: {
+            type: "object",
+            properties: {
+                pattern: { type: "string", description: "Regular expression to search for." },
+                path: { type: "string", description: "Directory to search from. Defaults to the deck root." },
+                glob: { type: "string", description: "Only search files matching this glob." },
+                case_insensitive: { type: "boolean" },
+            },
+            required: ["pattern"],
+        },
+        roles: READ_ONLY_ROLES,
+        run: grepRun,
+    },
+    {
+        name: "view_image",
+        description: "Look at an image file in the deck (png/jpg/jpeg/gif/webp) -- the image is delivered to you in a follow-up message. Use this for user-attached image paths and deck art; read_file rejects binaries.",
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Image path relative to the deck directory." },
+            },
+            required: ["path"],
+        },
+        // Read-only, so both roles get it: the router may want to look at deck
+        // images or user attachments referenced by path just as much as a task.
+        roles: READ_ONLY_ROLES,
+        run: viewImageRun,
+    },
+    {
+        name: "write_file",
+        description: "Create or overwrite a file in the deck, creating parent directories as needed.",
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "File path relative to the deck directory." },
+                content: { type: "string", description: "Full file contents to write." },
+            },
+            required: ["path", "content"],
+        },
+        roles: TASK_ONLY_ROLES,
+        run: writeFileRun,
+    },
+    {
+        name: "edit_file",
+        description: "Replace an exact substring in an existing file. old_string must uniquely identify one location unless replace_all is set.",
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "File path relative to the deck directory." },
+                old_string: { type: "string", description: "Exact text to find." },
+                new_string: { type: "string", description: "Text to replace it with." },
+                replace_all: { type: "boolean", description: "Replace every occurrence instead of requiring uniqueness." },
+            },
+            required: ["path", "old_string", "new_string"],
+        },
+        roles: TASK_ONLY_ROLES,
+        run: editFileRun,
+    },
+    {
+        name: "bash",
+        description: "Run a shell command in the deck directory.",
+        parameters: {
+            type: "object",
+            properties: {
+                command: { type: "string", description: "Shell command to run." },
+                timeout_ms: { type: "integer", description: "Optional per-command timeout override, in milliseconds (max 600000)." },
+            },
+            required: ["command"],
+        },
+        roles: TASK_ONLY_ROLES,
+        run: bashRun,
+    },
+    {
+        name: "playtest",
+        description: PLAYTEST_TOOL_DESCRIPTION,
+        parameters: PLAYTEST_TOOL_PARAMETERS,
+        // Task-only: the router never builds anything, so it has nothing to
+        // playtest, and (unlike the read-only tools) playtest ties up the
+        // serve's one shared browser -- a resource task agents own.
+        roles: TASK_ONLY_ROLES,
+        run: (args, ctx) => runPlaytest(args, ctx.deckDir, ctx.playtest, ctx.signal),
+    },
+    {
+        name: "restart",
+        description: "Reload the deck in every connected browser tab, dropping Vite's stale module cache first (same effect as `npm run restart`, applied in-process). Call this after file changes instead of running `npm run restart` via bash.",
+        parameters: { type: "object", properties: {} },
+        // Task-only: the router never edits the deck, so it never has a reason
+        // to reload it.
+        roles: TASK_ONLY_ROLES,
+        run: (_args, ctx) => restartRun(ctx),
+    },
+];
+export function toolSchemasForRole(role) {
+    return TOOLS.filter((t) => t.roles.includes(role)).map((t) => ({
+        type: "function",
+        function: { name: t.name, description: t.description, parameters: t.parameters },
+    }));
+}
+export async function executeTool(name, args, role, ctx) {
+    const spec = TOOLS.find((t) => t.name === name);
+    if (!spec)
+        return err(`unknown tool "${name}".`);
+    if (!spec.roles.includes(role)) {
+        return err(`the "${name}" tool is not available to ${role} agents${role === "router" ? " (the router is read-only)" : ""}.`);
+    }
+    const decision = ctx.checkPolicy?.({ tool: name, args }) ?? { allow: true };
+    if (!decision.allow) {
+        return err(`blocked by policy${decision.reason ? `: ${decision.reason}` : ""}.`);
+    }
+    try {
+        return await spec.run(args, ctx);
+    }
+    catch (e) {
+        return err(`${name} failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+// Activity label vocabulary mirroring claudeToolFeedLabel / genericClaudeToolLabel
+// in agent.ts (concrete for file edits/reads, coarse for search/commands) --
+// see native/loop.ts, which calls this for every tool call regardless of
+// role (unlike the CLI backends, every native tool is known up front, so
+// there is no "unknown tool" case to hide behind labelUnknownTools).
+export function activityLabelForCall(name, args) {
+    const p = typeof args.path === "string" ? args.path : "";
+    switch (name) {
+        case "read_file":
+            return p ? `Reading ${baseName(p)}` : "Reading the deck";
+        case "view_image":
+            return p ? `Viewing ${baseName(p)}` : "Viewing an image";
+        case "write_file":
+        case "edit_file":
+            return p ? `Editing ${baseName(p)}` : "Editing files";
+        case "list_files":
+        case "grep":
+            return "Searching the deck";
+        case "playtest":
+            return "Playtesting";
+        case "restart":
+            return "Restarting the deck";
+        case "bash": {
+            const command = typeof args.command === "string" ? args.command.trim() : "";
+            const words = command.split(/\s+/).filter(Boolean).slice(0, 3).join(" ");
+            return words ? `Running ${words}` : "Running a command";
+        }
+        default:
+            return "Working";
+    }
+}

package/dist/native/types.d.ts

@@ -0,0 +1,40 @@
+import type { PlaytestExecutor } from "./playtest.js";
+export type NativeRole = "router" | "task";
+export interface NativePlaytestOpts {
+    executor: PlaytestExecutor;
+    serveUrl: string;
+    framesDir: string;
+}
+export interface NativeUsage {
+    input_tokens?: number;
+    output_tokens?: number;
+    cache_creation_input_tokens?: number;
+    cache_read_input_tokens?: number;
+}
+export interface NativeRunOpts {
+    cwd: string;
+    role: NativeRole;
+    model: string;
+    apiKey: string;
+    prompt: string;
+    systemReminder?: string;
+    attachments?: string[];
+    playtest?: NativePlaytestOpts;
+    restart?: () => void;
+    logPath?: string;
+    timeoutMs: number;
+    signal?: AbortSignal;
+    onDelta?: (delta: string) => void;
+    onActivity?: (activity: string | null) => void;
+    onThinking?: (delta: string) => void;
+    onSpawn?: (pid: number | undefined) => void;
+    labelUnknownTools?: boolean;
+}
+export interface NativeRunResult {
+    text: string;
+    error?: string;
+    usage?: NativeUsage;
+    filesTouched?: string[];
+    playtestFrames?: string[];
+    crashed?: boolean;
+}