@wardby/cli 0.7.0 → 0.8.0

package/dist/claude-plugin/command.js

@@ -0,0 +1,376 @@
+/**
+ * `wardby claude-plugin install | uninstall | status`: sets up the wardby-runs
+ * Claude Code plugin (plugins/claude-code) on this machine. Install adds the
+ * plugin from a marketplace (wardby/wardby by default, or an operator's own),
+ * can register the wardby MCP server, and offers the allow rules auto mode
+ * needs for the pane's read-only tools. Uninstall removes the plugin and only
+ * the settings install added. Status reports all three.
+ *
+ * Runs without a database or any server configuration. It prints the commands
+ * it runs and their outcome, never a token: the MCP server's sign-in is Claude
+ * Code's own, at first use.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { createInterface } from "node:readline";
+import { parseArgs } from "node:util";
+export const PLUGIN = "wardby-runs";
+export const DEFAULT_MARKETPLACE = "wardby/wardby";
+export const MCP_SERVER = "wardby";
+/** The pane's read-only tools on a server: what auto mode needs allowed. stop_run is never added: it changes a run. */
+export function paneTools(server) {
+    return ["list_runs", "list_agents", "get_run", "get_run_transcript"].map((tool) => `mcp__${server}__${tool}`);
+}
+export const PANE_TOOLS = paneTools(MCP_SERVER);
+/** How long one `claude` call may take: `claude mcp get` can check its server, which shouldn't stall doctor. */
+const CLAUDE_TIMEOUT_MS = 20_000;
+export const CLAUDE_PLUGIN_USAGE = `usage: wardby claude-plugin install [--marketplace <owner/repo|path>] [--server-url <url>]
+                                   [--allow-tools | --no-allow-tools] [--fullscreen] [--yes]
+       wardby claude-plugin uninstall
+       wardby claude-plugin status
+
+Set up the wardby-runs Claude Code plugin: a pane listing your wardby runs.
+
+  --server-name <name> The MCP server the pane uses, as /mcp lists it (default ${MCP_SERVER}); its
+                       allow rules follow the name
+  --marketplace <src>  Where to install it from (default ${DEFAULT_MARKETPLACE}; an operator's own
+                       marketplace repository or a local folder works too)
+  --server-url <url>   Register the wardby MCP server at this URL first (for example
+                       https://wardby.example.com/mcp) when Claude Code has none named ${MCP_SERVER}
+  --allow-tools        Allow the pane's read-only wardby tools for auto mode without asking
+  --no-allow-tools     Leave permission rules alone
+  --fullscreen         Also switch Claude Code's terminal to its fullscreen view, where the pane
+                       is a side bar that takes clicks (applies to every session)
+  --yes, -y            Answer yes to every question`;
+/** The real machine: spawns `claude`, asks on the terminal, uses CLAUDE_CONFIG_DIR or ~/.claude. */
+export function claudePluginDeps() {
+    return {
+        run: (command, args) => {
+            const result = spawnSync(command, args, { encoding: "utf8", timeout: CLAUDE_TIMEOUT_MS });
+            return {
+                status: result.error ? 127 : (result.status ?? 1),
+                stdout: result.stdout ?? "",
+                stderr: result.stderr ?? "",
+            };
+        },
+        confirm: async (question) => {
+            if (!process.stdin.isTTY)
+                return false;
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            try {
+                const answer = await new Promise((resolve) => rl.question(`${question} [y/N] `, resolve));
+                return /^y(es)?$/i.test(answer.trim());
+            }
+            finally {
+                rl.close();
+            }
+        },
+        claudeConfigDir: process.env.CLAUDE_CONFIG_DIR?.trim() || join(homedir(), ".claude"),
+        wardbyDir: join(homedir(), ".wardby"),
+        out: (line) => process.stdout.write(`${line}\n`),
+    };
+}
+const recordPath = (deps) => join(deps.wardbyDir, "claude-plugin.json");
+/** A settings file as an object: {} when absent; refuses a file that isn't a JSON object rather than overwrite it. */
+function readSettings(path) {
+    if (!existsSync(path))
+        return {};
+    const text = readFileSync(path, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`${path} isn't valid JSON; fix it, then run this again. Nothing was changed.`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`${path} isn't a JSON object; nothing was changed.`);
+    }
+    return parsed;
+}
+/** Writes a settings file whole, through a temporary file, so a failure never leaves half a file. */
+function writeSettings(path, settings) {
+    mkdirSync(dirname(path), { recursive: true });
+    const temp = `${path}.wardby-${process.pid}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(settings, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temp, path);
+}
+function allowList(settings) {
+    const permissions = settings.permissions;
+    if (typeof permissions !== "object" || permissions === null)
+        return [];
+    const allow = permissions.allow;
+    return Array.isArray(allow) ? allow.filter((rule) => typeof rule === "string") : [];
+}
+function withAllowList(settings, allow) {
+    const permissions = typeof settings.permissions === "object" && settings.permissions !== null
+        ? settings.permissions
+        : {};
+    return { ...settings, permissions: { ...permissions, allow } };
+}
+function readRecord(deps) {
+    try {
+        const record = JSON.parse(readFileSync(recordPath(deps), "utf8"));
+        return typeof record.settingsPath === "string" && Array.isArray(record.rules) ? record : null;
+    }
+    catch {
+        return null;
+    }
+}
+function claudeAvailable(deps) {
+    return deps.run("claude", ["--version"]).status === 0;
+}
+function hasMcpServer(deps, server = MCP_SERVER) {
+    return deps.run("claude", ["mcp", "get", server]).status === 0;
+}
+function pluginInstalled(deps) {
+    const list = deps.run("claude", ["plugin", "list"]);
+    return list.status === 0 && new RegExp(`\\b${PLUGIN}@`).test(list.stdout);
+}
+/** The first line of a failed command's output, for the message. */
+const firstLine = (result) => (result.stderr || result.stdout).trim().split("\n")[0]?.slice(0, 300) ?? "";
+export async function installPlugin(options, deps) {
+    if (!claudeAvailable(deps)) {
+        deps.out("Claude Code (claude) wasn't found on PATH. Install it, then run this again.");
+        return 1;
+    }
+    const server = options.serverName ?? MCP_SERVER;
+    if (!/^[A-Za-z0-9_-]{1,64}$/.test(server)) {
+        deps.out(`--server-name "${server}" isn't a server name (letters, digits, - and _).`);
+        return 1;
+    }
+    const tools = paneTools(server);
+    // Read the settings file before changing anything, so a broken one stops the install cleanly.
+    const settingsPath = join(deps.claudeConfigDir, "settings.json");
+    let settings;
+    try {
+        settings = readSettings(settingsPath);
+    }
+    catch (error) {
+        deps.out(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+    // 1. The MCP server the pane talks to.
+    if (hasMcpServer(deps, server)) {
+        deps.out(`✓ Claude Code has an MCP server named ${server}.`);
+    }
+    else if (options.serverUrl) {
+        let url;
+        try {
+            url = new URL(options.serverUrl);
+        }
+        catch {
+            deps.out(`--server-url "${options.serverUrl}" isn't a URL.`);
+            return 1;
+        }
+        if (url.protocol !== "https:" &&
+            !(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname))) {
+            deps.out("--server-url must be https (or http on localhost).");
+            return 1;
+        }
+        const added = deps.run("claude", ["mcp", "add", "--transport", "http", "--scope", "user", server, url.href]);
+        if (added.status !== 0) {
+            deps.out(`Adding the ${server} MCP server failed: ${firstLine(added)}`);
+            return 1;
+        }
+        deps.out(`✓ Added the ${server} MCP server (${url.href}). Sign in with /mcp in Claude Code.`);
+    }
+    else {
+        deps.out(`! Claude Code has no MCP server named ${server}. The pane needs one: run this again with ` +
+            "--server-url <your wardby URL>/mcp, or run `wardby quickstart`.");
+    }
+    // 2. The plugin itself.
+    const installed = deps.run("claude", ["plugin", "install", PLUGIN, "--marketplace", options.marketplace]);
+    if (installed.status !== 0) {
+        deps.out(`Installing the ${PLUGIN} plugin from ${options.marketplace} failed: ${firstLine(installed)}`);
+        return 1;
+    }
+    deps.out(`✓ Installed the ${PLUGIN} plugin from ${options.marketplace}.`);
+    // 3. Allow rules for auto mode, and the fullscreen view: each only when asked for or agreed to.
+    const record = readRecord(deps) ?? { settingsPath, rules: [], tui: false };
+    let changed = false;
+    const allowTools = options.allowTools ??
+        (options.yes ||
+            (await deps.confirm(`Allow the pane's read-only wardby tools (${tools.map((t) => t.replace(`mcp__${server}__`, "")).join(", ")}) ` +
+                `in ${settingsPath}? Auto mode refuses the pane's calls without them.`)));
+    if (allowTools) {
+        const current = allowList(settings);
+        const missing = tools.filter((rule) => !current.includes(rule));
+        if (missing.length > 0) {
+            settings = withAllowList(settings, [...current, ...missing]);
+            record.rules = [...new Set([...record.rules, ...missing])];
+            changed = true;
+            deps.out(`✓ Allowed ${missing.join(", ")}.`);
+        }
+        else {
+            deps.out("✓ The pane's tools are already allowed.");
+        }
+    }
+    else {
+        deps.out(`Left permission rules alone. Under auto mode, allow ${tools.join(", ")} in /permissions.`);
+    }
+    if (options.fullscreen && settings.tui !== "fullscreen") {
+        settings = { ...settings, tui: "fullscreen" };
+        record.tui = true;
+        changed = true;
+        deps.out("✓ Switched Claude Code to its fullscreen view (restart Claude Code to see it).");
+    }
+    if (changed) {
+        writeSettings(settingsPath, settings);
+        mkdirSync(deps.wardbyDir, { recursive: true });
+        writeFileSync(recordPath(deps), `${JSON.stringify({ ...record, settingsPath }, null, 2)}\n`, { mode: 0o600 });
+    }
+    deps.out("Open the pane in Claude Code with /wardby-runs (in a new session, or after /reload-plugins).");
+    return 0;
+}
+export async function uninstallPlugin(deps) {
+    if (!claudeAvailable(deps)) {
+        deps.out("Claude Code (claude) wasn't found on PATH.");
+        return 1;
+    }
+    const removed = deps.run("claude", ["plugin", "uninstall", PLUGIN]);
+    if (removed.status === 0)
+        deps.out(`✓ Uninstalled the ${PLUGIN} plugin.`);
+    else
+        deps.out(`The ${PLUGIN} plugin wasn't uninstalled: ${firstLine(removed)}`);
+    // Only what install added: rules it added, and the fullscreen view if it switched it on. The file is
+    // written only when one of those is still there; a broken file is reported, not rewritten.
+    const record = readRecord(deps);
+    if (record && existsSync(record.settingsPath)) {
+        let settings;
+        try {
+            settings = readSettings(record.settingsPath);
+        }
+        catch (error) {
+            deps.out(`${error instanceof Error ? error.message : String(error)} Remove ${record.rules.join(", ")} yourself.`);
+            return 1;
+        }
+        const current = allowList(settings);
+        const kept = current.filter((rule) => !record.rules.includes(rule));
+        let changed = false;
+        if (kept.length !== current.length) {
+            settings = withAllowList(settings, kept);
+            changed = true;
+            deps.out(`✓ Removed the rules install added: ${current.filter((rule) => !kept.includes(rule)).join(", ")}.`);
+        }
+        if (record.tui && settings.tui === "fullscreen") {
+            const { tui: _tui, ...rest } = settings;
+            settings = rest;
+            changed = true;
+            deps.out("✓ Switched the fullscreen view back off.");
+        }
+        if (changed)
+            writeSettings(record.settingsPath, settings);
+    }
+    if (record)
+        writeFileSync(recordPath(deps), "{}\n", { mode: 0o600 });
+    deps.out(`The ${MCP_SERVER} MCP server was left in place (remove it with: claude mcp remove ${MCP_SERVER} -s user).`);
+    return removed.status === 0 ? 0 : 1;
+}
+export function pluginStatus(deps, serverName = MCP_SERVER) {
+    if (!claudeAvailable(deps)) {
+        deps.out("✗ Claude Code (claude) wasn't found on PATH.");
+        return 1;
+    }
+    const plugin = pluginInstalled(deps);
+    const server = hasMcpServer(deps, serverName);
+    const settingsPath = join(deps.claudeConfigDir, "settings.json");
+    let allowed = [];
+    try {
+        allowed = allowList(readSettings(settingsPath));
+    }
+    catch (error) {
+        deps.out(`! ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const missing = paneTools(serverName).filter((rule) => !allowed.includes(rule));
+    deps.out(`${plugin ? "✓" : "✗"} ${PLUGIN} plugin ${plugin ? "installed" : "not installed"}`);
+    deps.out(`${server ? "✓" : "✗"} ${serverName} MCP server ${server ? "configured" : "not configured"}`);
+    deps.out(missing.length === 0
+        ? `✓ the pane's tools are allowed in ${settingsPath}`
+        : `! not allowed in ${settingsPath} (auto mode refuses them): ${missing.join(", ")}`);
+    return plugin && server ? 0 : 1;
+}
+/**
+ * Quickstart's offer of the pane, once it connected Claude Code: asks unless a flag answered it,
+ * never in a non-interactive run, and installs on a yes. A failed install is a warning, not a stop.
+ */
+export async function quickstartPaneStep(options, steps) {
+    if (!options.mcpConfigured || (options.client !== "claude" && options.client !== "both"))
+        return "skipped";
+    const wanted = options.flag ??
+        (!options.nonInteractive && (await steps.ask("Add the wardby runs pane to Claude Code (the wardby-runs plugin)?")));
+    if (!wanted)
+        return "skipped";
+    const status = await steps.install({ marketplace: DEFAULT_MARKETPLACE, fullscreen: false, yes: options.yes });
+    if (status === 0)
+        return "installed";
+    steps.warn("! The runs pane wasn't installed; try again with: npx @wardby/cli@latest claude-plugin install");
+    return "failed";
+}
+/**
+ * `wardby doctor`'s lines for the pane: none without Claude Code. The pane is optional, so nothing
+ * here is a failure (✗): a missing plugin is "○", a missing server or rule a warning ("!").
+ */
+export function claudePluginDoctorLines(deps, serverName = MCP_SERVER) {
+    if (!claudeAvailable(deps))
+        return [];
+    if (!pluginInstalled(deps)) {
+        return [`○ Claude Code runs pane not installed (optional: npx @wardby/cli@latest claude-plugin install)`];
+    }
+    const lines = [`✓ ${PLUGIN} Claude Code plugin installed`];
+    lines.push(hasMcpServer(deps, serverName)
+        ? `✓ ${serverName} MCP server configured in Claude Code`
+        : `! Claude Code has no MCP server named ${serverName}: the pane has nothing to show (claude-plugin install --server-url <url>)`);
+    const settingsPath = join(deps.claudeConfigDir, "settings.json");
+    let missing = paneTools(serverName);
+    try {
+        const allowed = allowList(readSettings(settingsPath));
+        missing = paneTools(serverName).filter((rule) => !allowed.includes(rule));
+    }
+    catch {
+        // An unreadable settings file reads as no rules: the warning below says what to allow.
+    }
+    lines.push(missing.length === 0
+        ? "✓ the pane's tools are allowed for auto mode"
+        : `! not allowed for auto mode in ${settingsPath}: ${missing.join(", ")} (needed only in auto mode)`);
+    return lines;
+}
+export async function claudePluginCommand(args, deps = claudePluginDeps()) {
+    const [sub, ...rest] = args;
+    if (sub === undefined || sub === "--help" || sub === "-h") {
+        deps.out(CLAUDE_PLUGIN_USAGE);
+        return sub === undefined ? 1 : 0;
+    }
+    if (sub === "install") {
+        const { values } = parseArgs({
+            args: rest,
+            allowNegative: true,
+            options: {
+                marketplace: { type: "string" },
+                "server-name": { type: "string" },
+                "server-url": { type: "string" },
+                "allow-tools": { type: "boolean" },
+                fullscreen: { type: "boolean" },
+                yes: { type: "boolean", short: "y" },
+            },
+        });
+        return installPlugin({
+            marketplace: values.marketplace ?? DEFAULT_MARKETPLACE,
+            serverName: values["server-name"],
+            serverUrl: values["server-url"],
+            allowTools: values["allow-tools"],
+            fullscreen: values.fullscreen ?? false,
+            yes: values.yes ?? false,
+        }, deps);
+    }
+    if (sub === "uninstall")
+        return uninstallPlugin(deps);
+    if (sub === "status") {
+        const { values } = parseArgs({ args: rest, options: { "server-name": { type: "string" } } });
+        return pluginStatus(deps, values["server-name"] ?? MCP_SERVER);
+    }
+    deps.out(`Unknown claude-plugin command "${sub}".\n${CLAUDE_PLUGIN_USAGE}`);
+    return 1;
+}

package/dist/cli-help.d.ts

@@ -1 +1 @@
-export declare const CLI_USAGE = "usage:\n  wardby quickstart [--provider openai|anthropic] [--model <m>] [--budget <usd>] [--client none|codex|claude|both] [--skip-demo] [--non-interactive --yes]\n  wardby doctor\n  wardby status\n  wardby logs [--tail N] [--follow]\n  wardby down [--volumes]\n  wardby knowledge check [dir] [--root <dir>] [--strict] [--json]   Validate a knowledge bundle (offline)\n  wardby resume - [--dir <path> | --here] [--force] [--print]   Continue a coding run's Claude Code session locally (paste the get_run_transcript link)\n  wardby help [list]\n  wardby help search <terms>\n  wardby help open <article-id>\n  wardby agent create --name <n> --model <m> --prompt <p> --budget <usd> [--schedule \"<cron>\"] [--timezone <tz>] [--max-turns <n>] [--owner <subject>] [--public] [--native-execution-mode control-plane|sandbox]\n      (owned by --owner or LOCAL_PRINCIPAL; --public shares it with everyone at execute;\n       sandbox needs NATIVE_SANDBOX_LAUNCHER set in this environment)\n  wardby agent list\n  wardby agent mode <name> control-plane|sandbox   (native agents; applies to runs created after the change)\n  wardby agent schedule <name> --cron \"<expr>\" [--timezone <tz>] [--disable]\n  wardby tool create --name <n> --description <d> --params <file> --code <file>\n  wardby tool attach <tool-name|tool-id> <agent-name>   (grants the capabilities in the agent owner's name)\n  wardby tool detach <tool-name|tool-id> <agent-name>\n  wardby tool update <tool-name|tool-id> [--description <d>] [--params <file>] [--code <file>]\n  wardby tool delete <tool-name|tool-id> [--detach]\n  wardby tool list [--agent <name>]\n  wardby run <name>\n  wardby runs [--agent <name>] [--limit N] [--status <s>]\n  wardby coding preflight   (JOB_LAUNCHER=docker or kubernetes)\n  wardby coding cleanup --run-id <id>\n  wardby scheduler [--scope default]\n  wardby native-gateway   (the native sandbox gateway only; NATIVE_GATEWAY_LISTEN, default 0.0.0.0:8790)\n  wardby mcp   (MCP_TRANSPORT=stdio|http selects the transport)\n  wardby serve [--scope default]   (mcp + scheduler + reconciler in one process; http only)\n  wardby grants migration-report [--json]\n  wardby grants adopt-public --owner <subject> [--dry-run] [--keep-everyone-execute]\n  wardby grants prune-bindings [--dry-run]\n  wardby import <bundle-dir> [--owner <subject>] [--public] [--include-secrets --transfer-key <pem>] [--default-budget <usd>] [--dry-run] [--prefix <p>] [--on-conflict fail|skip|rename] [--allow-open-fetch]\n\noptions:\n  -h, --help       Show this help\n  -v, --version    Show the installed Wardby version";
+export declare const CLI_USAGE = "usage:\n  wardby quickstart [--provider openai|anthropic] [--model <m>] [--budget <usd>] [--client none|codex|claude|both] [--claude-plugin | --no-claude-plugin] [--skip-demo] [--non-interactive --yes]\n  wardby doctor\n  wardby status\n  wardby logs [--tail N] [--follow]\n  wardby down [--volumes]\n  wardby knowledge check [dir] [--root <dir>] [--strict] [--json]   Validate a knowledge bundle (offline)\n  wardby resume - [--dir <path> | --here] [--force] [--print]   Continue a coding run's Claude Code session locally (paste the get_run_transcript link)\n  wardby claude-plugin install|uninstall|status [options]   Set up the wardby-runs Claude Code pane (plugin, MCP server, allow rules)\n  wardby help [list]\n  wardby help search <terms>\n  wardby help open <article-id>\n  wardby agent create --name <n> --model <m> --prompt <p> --budget <usd> [--schedule \"<cron>\"] [--timezone <tz>] [--max-turns <n>] [--owner <subject>] [--public] [--native-execution-mode control-plane|sandbox]\n      (owned by --owner or LOCAL_PRINCIPAL; --public shares it with everyone at execute;\n       sandbox needs NATIVE_SANDBOX_LAUNCHER set in this environment)\n  wardby agent list\n  wardby agent mode <name> control-plane|sandbox   (native agents; applies to runs created after the change)\n  wardby agent schedule <name> --cron \"<expr>\" [--timezone <tz>] [--disable]\n  wardby tool create --name <n> --description <d> --params <file> --code <file>\n  wardby tool attach <tool-name|tool-id> <agent-name>   (grants the capabilities in the agent owner's name)\n  wardby tool detach <tool-name|tool-id> <agent-name>\n  wardby tool update <tool-name|tool-id> [--description <d>] [--params <file>] [--code <file>]\n  wardby tool delete <tool-name|tool-id> [--detach]\n  wardby tool list [--agent <name>]\n  wardby run <name>\n  wardby runs [--agent <name>] [--limit N] [--status <s>]\n  wardby coding preflight   (JOB_LAUNCHER=docker or kubernetes)\n  wardby coding cleanup --run-id <id>\n  wardby scheduler [--scope default]\n  wardby native-gateway   (the native sandbox gateway only; NATIVE_GATEWAY_LISTEN, default 0.0.0.0:8790)\n  wardby mcp   (MCP_TRANSPORT=stdio|http selects the transport)\n  wardby serve [--scope default]   (mcp + scheduler + reconciler in one process; http only)\n  wardby grants migration-report [--json]\n  wardby grants adopt-public --owner <subject> [--dry-run] [--keep-everyone-execute]\n  wardby grants prune-bindings [--dry-run]\n  wardby import <bundle-dir> [--owner <subject>] [--public] [--include-secrets --transfer-key <pem>] [--default-budget <usd>] [--dry-run] [--prefix <p>] [--on-conflict fail|skip|rename] [--allow-open-fetch]\n\noptions:\n  -h, --help       Show this help\n  -v, --version    Show the installed Wardby version";

package/dist/cli-help.js

@@ -1,11 +1,12 @@
 export const CLI_USAGE = `usage:
-  wardby quickstart [--provider openai|anthropic] [--model <m>] [--budget <usd>] [--client none|codex|claude|both] [--skip-demo] [--non-interactive --yes]
+  wardby quickstart [--provider openai|anthropic] [--model <m>] [--budget <usd>] [--client none|codex|claude|both] [--claude-plugin | --no-claude-plugin] [--skip-demo] [--non-interactive --yes]
   wardby doctor
   wardby status
   wardby logs [--tail N] [--follow]
   wardby down [--volumes]
   wardby knowledge check [dir] [--root <dir>] [--strict] [--json]   Validate a knowledge bundle (offline)
   wardby resume - [--dir <path> | --here] [--force] [--print]   Continue a coding run's Claude Code session locally (paste the get_run_transcript link)
+  wardby claude-plugin install|uninstall|status [options]   Set up the wardby-runs Claude Code pane (plugin, MCP server, allow rules)
   wardby help [list]
   wardby help search <terms>
   wardby help open <article-id>

package/dist/cli.js

@@ -60,9 +60,13 @@ import { logger } from "./core/logger.js";
 import { buildPower } from "./core/power-composition.js";
 import { deriveJsonSchema } from "./sandbox/zod-params.js";
 import { toolSubject, zod3ToolWarnings } from "./core/zod3-window.js";
-import { findSameNamedAttachedTool, reservedToolNameReason, resolveToolRef } from "./core/tool-names.js";
+import { findSameNamedAttachedTool, findSameNamedMcpTool, reservedToolNameReason, resolveToolRef, sameNamedMcpToolMessage, } from "./core/tool-names.js";
 import { ToolAttachedError, deleteToolGuarded, formatAttachedAgents, formatToolLine, hasToolChanges, prepareToolUpdate, updateToolGuarded, } from "./core/tool-admin.js";
 import { ToolCapabilitiesPatchSchema } from "./sandbox/tool-capabilities.js";
+import { toolTimeoutProblem } from "./sandbox/tool-timeout.js";
+import { loadToolMaxTimeoutMs } from "./config/tool-timeout.js";
+import { loadMcpServersMode } from "./config/mcp-servers.js";
+import { loadMcpMaxCallsPerRun } from "./config/mcp-call-limit.js";
 import { startMcp, warmUpExecutor } from "./mcp/index.js";
 import { startServe } from "./serve.js";
 import { authCommand } from "./mcp/auth/self-hosted/cli.js";
@@ -226,6 +230,21 @@ async function agentCreate(args) {
     });
     console.log(agent.id);
 }
+/**
+ * `--timeout-ms <ms>`: the tool's own time limit, up to WARDBY_TOOL_MAX_TIMEOUT_MS. On update,
+ * `--timeout-ms default` clears it (back to the default limit).
+ */
+function cliToolTimeout(raw, allowClear) {
+    if (raw === undefined)
+        return undefined;
+    if (allowClear && raw === "default")
+        return null;
+    const value = /^\d+$/.test(raw.trim()) ? Number(raw.trim()) : NaN;
+    const problem = toolTimeoutProblem(value, loadToolMaxTimeoutMs());
+    if (problem)
+        fail(`invalid --timeout-ms: ${problem}`);
+    return value;
+}
 async function toolCreate(args) {
     const { values } = parseArgs({
         args,
@@ -234,6 +253,7 @@ async function toolCreate(args) {
             description: { type: "string" },
             params: { type: "string" },
             code: { type: "string" },
+            "timeout-ms": { type: "string" },
         },
     });
     if (!values.name || !values.description || !values.params || !values.code) {
@@ -242,6 +262,7 @@ async function toolCreate(args) {
     const reserved = reservedToolNameReason(values.name);
     if (reserved)
         fail(reserved);
+    const timeoutMs = cliToolTimeout(values["timeout-ms"], false);
     let paramsZod;
     let code;
     try {
@@ -277,6 +298,7 @@ async function toolCreate(args) {
             paramsZod: paramsZod,
             jsonSchema: schemaResult.value,
             code: code,
+            ...(timeoutMs !== undefined ? { timeoutMs } : {}),
         },
     });
     for (const warning of await zod3ToolWarnings(toolSubject(tool.name), paramsZod))
@@ -336,6 +358,9 @@ async function toolAttach(args, detach) {
     if (clash) {
         fail(`agent "${agentName}" already has a different tool named "${tool.name}" attached (${clash.id}); detach it first.`);
     }
+    const mcpClash = await findSameNamedMcpTool(prisma, agent.id, tool.name);
+    if (mcpClash)
+        fail(sameNamedMcpToolMessage(agentName, tool.name, mcpClash.serverName));
     const patch = ToolCapabilitiesPatchSchema.safeParse({
         allowedSecrets: values["allow-secret"],
         allowedDatastorePrefixes: values["allow-datastore-prefix"],
@@ -422,6 +447,7 @@ async function toolUpdate(args) {
             description: { type: "string" },
             params: { type: "string" },
             code: { type: "string" },
+            "timeout-ms": { type: "string" },
         },
     });
     const [ref] = positionals;
@@ -441,9 +467,10 @@ async function toolUpdate(args) {
         description: values.description,
         paramsZod: readFile("--params", values.params),
         code: readFile("--code", values.code),
+        timeoutMs: cliToolTimeout(values["timeout-ms"], true),
     };
     if (!hasToolChanges(changes)) {
-        fail("tool update requires at least one of --description, --params <file>, --code <file>.");
+        fail("tool update requires at least one of --description, --params <file>, --code <file>, --timeout-ms.");
     }
     const resolved = await resolveToolRef(prisma, ref);
     if (!resolved.ok)
@@ -792,6 +819,10 @@ async function scheduler(args) {
                 cliLog.warn(`low_power_scale_forbidden: missing ${missing.join(", ")}`);
         }, (err) => cliLog.warn({ err }, "low_power_access_check_failed"));
     }
+    // Read again at each tool call; checked here so a bad value stops start-up, not every run.
+    loadToolMaxTimeoutMs();
+    loadMcpServersMode();
+    loadMcpMaxCallsPerRun();
     const executor = buildConfiguredExecutor({
         native: nativeExecutor,
         db: prisma,
@@ -858,6 +889,14 @@ async function scheduler(args) {
  */
 async function nativeGateway() {
     const listen = parseGatewayListen(process.env.NATIVE_GATEWAY_LISTEN) ?? { host: "0.0.0.0", port: 8790 };
+    try {
+        loadToolMaxTimeoutMs();
+        loadMcpServersMode();
+        loadMcpMaxCallsPerRun();
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+    }
     let modelCatalog;
     try {
         modelCatalog = await startModelCatalog(prisma);
@@ -878,7 +917,12 @@ async function nativeGateway() {
         repoAccess: createRepoAccessGate({ db: prisma, hosts: reviewHosts }),
         executor: new DeferredExecutor(prisma),
     };
-    const server = await startGatewayServer(listen, { db: prisma, providers });
+    const server = await startGatewayServer(listen, {
+        db: prisma,
+        providers,
+        // Coding runs' MCP calls, forwarded by the coding proxy's /mcp route (its own token auth).
+        codingMcp: { db: prisma, cipher: secrets, log: logger.child({ module: "coding-mcp" }) },
+    });
     // The deny port (NATIVE_GATEWAY_DENY_PORT, default 8791) serves nothing: a worker that can reach the
     // gateway port but not this one proves its NetworkPolicy is programmed and port-scoped.
     const denyPort = Number(process.env.NATIVE_GATEWAY_DENY_PORT ?? NATIVE_GATEWAY_DENY_PORT);

package/dist/coding/code-host.d.ts

@@ -0,0 +1,16 @@
+/** Whether `name` may be registered: it must also be what a `<name>:<workspace>/<repo>` id resolves to. */
+export declare function isValidHostProviderName(name: string): boolean;
+/** The provider that owns an already-normalized repository id. */
+export declare function codeProviderOf(repository: string): string;
+/**
+ * The canonical id of a repository on a host with pull requests: GitHub names,
+ * or `<provider>:<workspace>/<repo>` lower-cased. Throws for anything else,
+ * local repositories included, as normalizeGitHubRepository always has.
+ */
+export declare function normalizeHostedRepository(value: string): string;
+/**
+ * A pull request's web link, known here only for GitHub. A GitHub name never
+ * has a ":": anything that does gets no link, so no other host's id, valid or
+ * not, reaches a github.com URL.
+ */
+export declare function pullRequestWebUrl(provider: string, repository: string, number: number): string | null;

package/dist/coding/code-host.js

@@ -0,0 +1,60 @@
+/**
+ * Which code host owns a repository, from the form of its id: `owner/name` is
+ * GitHub, `local:/abs/path` a local folder, `<provider>:<workspace>/<repo>` a
+ * registered host provider. Control-plane only: coding/protocol.ts ships in the
+ * worker images, so this stays out of it.
+ */
+import { LOCAL_REPO_PREFIX, normalizeGitHubRepository } from "./protocol.js";
+const HOSTED_REPOSITORY = /^([a-z][a-z0-9-]{1,30}):([A-Za-z0-9][A-Za-z0-9._-]{0,99})\/([A-Za-z0-9][A-Za-z0-9._-]{0,99})$/;
+const HOST_PROVIDER_NAME = /^[a-z][a-z0-9-]{1,30}$/;
+/** Never a registered provider: built-ins, URL schemes a repository string could start with, and an Object.prototype key. */
+const RESERVED_PREFIXES = new Set([
+    "github",
+    "local",
+    "http",
+    "https",
+    "ssh",
+    "git",
+    "file",
+    "constructor",
+]);
+/** Whether `name` may be registered: it must also be what a `<name>:<workspace>/<repo>` id resolves to. */
+export function isValidHostProviderName(name) {
+    return HOST_PROVIDER_NAME.test(name) && !RESERVED_PREFIXES.has(name);
+}
+/** `a..b` could walk a path and `web.git` is a second name for `web`, so neither is a repository id. */
+function isCanonicalPart(part) {
+    return !part.endsWith(".") && !part.includes("..") && !part.toLowerCase().endsWith(".git");
+}
+function hostedParts(value) {
+    const match = HOSTED_REPOSITORY.exec(value);
+    if (!match || RESERVED_PREFIXES.has(match[1]))
+        return null;
+    const [, provider, workspace, repository] = match;
+    return isCanonicalPart(workspace) && isCanonicalPart(repository) ? { provider, workspace, repository } : null;
+}
+/** The provider that owns an already-normalized repository id. */
+export function codeProviderOf(repository) {
+    if (repository.startsWith(LOCAL_REPO_PREFIX))
+        return "local";
+    return hostedParts(repository)?.provider ?? "github";
+}
+/**
+ * The canonical id of a repository on a host with pull requests: GitHub names,
+ * or `<provider>:<workspace>/<repo>` lower-cased. Throws for anything else,
+ * local repositories included, as normalizeGitHubRepository always has.
+ */
+export function normalizeHostedRepository(value) {
+    const hosted = hostedParts(value);
+    if (hosted)
+        return `${hosted.provider}:${hosted.workspace.toLowerCase()}/${hosted.repository.toLowerCase()}`;
+    return normalizeGitHubRepository(value);
+}
+/**
+ * A pull request's web link, known here only for GitHub. A GitHub name never
+ * has a ":": anything that does gets no link, so no other host's id, valid or
+ * not, reaches a github.com URL.
+ */
+export function pullRequestWebUrl(provider, repository, number) {
+    return provider === "github" && !repository.includes(":") ? `https://github.com/${repository}/pull/${number}` : null;
+}

package/dist/coding/mcp-token.d.ts

@@ -0,0 +1,12 @@
+export declare const MCP_TOKEN_ENV = "WARDBY_MCP_TOKEN";
+/** The worker's MCP server key; Claude Code names its tools `mcp__<key>__<exposed name>`. */
+export declare const WORKER_MCP_SERVER_KEY = "wardby_mcp";
+export declare const CLAUDE_MCP_TOOL_PREFIX = "mcp__wardby_mcp__";
+/** The 401 text of both /mcp (coding proxy) and /coding-mcp (native gateway). */
+export declare const MCP_TOKEN_REQUIRED_MESSAGE = "A valid MCP token for an active run is required.";
+/** Exactly what mintMcpToken makes; launchers refuse to deliver anything else. */
+export declare function isMcpToken(value: string | undefined): value is string;
+/** `rmt_` followed by 32 random bytes in base64url. */
+export declare function mintMcpToken(): string;
+/** The token's stored form: the same SHA-256 (base64url) the run capability uses. */
+export declare function mcpTokenHash(token: string): string;

package/dist/coding/mcp-token.js

@@ -0,0 +1,26 @@
+/**
+ * A coding run's MCP token (remote MCP servers, phase 2): the worker's bearer for the proxy's /mcp
+ * route only. The control plane mints one per run whose agent has MCP tools, stores only its hash
+ * on the proxy session, keeps the value in the run capability vault for the launch, and delivers it
+ * as WARDBY_MCP_TOKEN (never in a job spec, command line, or log).
+ */
+import { randomBytes } from "node:crypto";
+import { capabilityHash } from "../providers/coding-proxy/capability-hash.js";
+export const MCP_TOKEN_ENV = "WARDBY_MCP_TOKEN";
+/** The worker's MCP server key; Claude Code names its tools `mcp__<key>__<exposed name>`. */
+export const WORKER_MCP_SERVER_KEY = "wardby_mcp";
+export const CLAUDE_MCP_TOOL_PREFIX = `mcp__${WORKER_MCP_SERVER_KEY}__`;
+/** The 401 text of both /mcp (coding proxy) and /coding-mcp (native gateway). */
+export const MCP_TOKEN_REQUIRED_MESSAGE = "A valid MCP token for an active run is required.";
+/** Exactly what mintMcpToken makes; launchers refuse to deliver anything else. */
+export function isMcpToken(value) {
+    return value !== undefined && /^rmt_[A-Za-z0-9_-]{43}$/.test(value);
+}
+/** `rmt_` followed by 32 random bytes in base64url. */
+export function mintMcpToken() {
+    return `rmt_${randomBytes(32).toString("base64url")}`;
+}
+/** The token's stored form: the same SHA-256 (base64url) the run capability uses. */
+export function mcpTokenHash(token) {
+    return capabilityHash(token);
+}

package/dist/coding/protocol.js

@@ -795,6 +795,8 @@ const TOKEN_PATTERNS = [
     /AKIA[0-9A-Z]{16}/g,
     /(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{16,}/gi,
     /rrp_[A-Za-z0-9_-]{32,}/g,
+    // A coding run's MCP token (src/coding/mcp-token.ts).
+    /rmt_[A-Za-z0-9_-]{20,}/g,
     /rv[a-z]_[0-9a-f-]{36}\.[A-Za-z0-9_-]{20,}/gi,
     // A JWT — an IdP access/ID token in delegating auth mode, and what a JWKS or
     // token-exchange failure is most likely to quote back. The HEADER segment is