@cjhyy/code-shell-core 0.5.0-rc.0

package/dist/tool-system/registry.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Unified tool registry — built-in tools + MCP tools.
+ */
+import type { RegisteredTool, ToolDefinition, ToolResult } from "../types.js";
+import { type BuiltinToolFn } from "./builtin/index.js";
+import type { ToolContext } from "./context.js";
+/**
+ * Default execution timeout for any tool that does not declare its own
+ * timeoutMs at registration time. Tools that need to run longer (Agent,
+ * Arena, Bash, custom long-running tools) should set timeoutMs explicitly.
+ */
+export declare const DEFAULT_TOOL_TIMEOUT_MS = 120000;
+export interface ToolRegistryOptions {
+    builtinTools?: readonly string[];
+}
+export declare class ToolRegistry {
+    private tools;
+    private builtinExecutors;
+    constructor(options?: ToolRegistryOptions);
+    private registerBuiltins;
+    registerTool(tool: RegisteredTool, executor?: BuiltinToolFn): void;
+    getToolDefinitions(): ToolDefinition[];
+    getTool(name: string): RegisteredTool | undefined;
+    hasTool(name: string): boolean;
+    executeTool(name: string, args: Record<string, unknown>, options?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+        ctx?: ToolContext;
+    }): Promise<ToolResult>;
+    listTools(): string[];
+    listToolsDetailed(): RegisteredTool[];
+}

package/dist/tool-system/registry.js

@@ -0,0 +1,131 @@
+/**
+ * Unified tool registry — built-in tools + MCP tools.
+ */
+import { ConfigError, ToolNotFoundError, ToolExecutionError, ToolTimeoutError } from "../exceptions.js";
+import { BUILTIN_TOOLS } from "./builtin/index.js";
+/**
+ * Default execution timeout for any tool that does not declare its own
+ * timeoutMs at registration time. Tools that need to run longer (Agent,
+ * Arena, Bash, custom long-running tools) should set timeoutMs explicitly.
+ */
+export const DEFAULT_TOOL_TIMEOUT_MS = 120_000;
+export class ToolRegistry {
+    tools = new Map();
+    builtinExecutors = new Map();
+    constructor(options = {}) {
+        this.registerBuiltins(options.builtinTools);
+    }
+    registerBuiltins(selectedBuiltinTools) {
+        const availableNames = new Set(BUILTIN_TOOLS.map((tool) => tool.definition.name));
+        const selectedNames = selectedBuiltinTools ? new Set(selectedBuiltinTools) : null;
+        if (selectedNames) {
+            const unknown = [...selectedNames].filter((name) => !availableNames.has(name));
+            if (unknown.length > 0) {
+                throw new ConfigError(`Unknown built-in tool(s): ${unknown.join(", ")}`, { unknownBuiltinTools: unknown });
+            }
+        }
+        for (const tool of BUILTIN_TOOLS) {
+            if (selectedNames && !selectedNames.has(tool.definition.name)) {
+                continue;
+            }
+            this.tools.set(tool.definition.name, tool.definition);
+            this.builtinExecutors.set(tool.definition.name, tool.execute);
+        }
+    }
+    registerTool(tool, executor) {
+        this.tools.set(tool.name, tool);
+        if (executor) {
+            this.builtinExecutors.set(tool.name, executor);
+        }
+    }
+    getToolDefinitions() {
+        return [...this.tools.values()].map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+        }));
+    }
+    getTool(name) {
+        return this.tools.get(name);
+    }
+    hasTool(name) {
+        return this.tools.has(name);
+    }
+    async executeTool(name, args, options) {
+        const tool = this.tools.get(name);
+        if (!tool) {
+            throw new ToolNotFoundError(name);
+        }
+        const executor = this.builtinExecutors.get(name);
+        if (!executor) {
+            throw new ToolExecutionError(name, "No executor registered for this tool");
+        }
+        // Tool timeout precedence:
+        //   options.timeoutMs (per-call override) > tool.timeoutMs (declared at registration) > default 120s.
+        // To run longer, declare timeoutMs on the tool (e.g. Agent/Arena: 30min, Bash: 1h).
+        const timeout = options?.timeoutMs ?? tool.timeoutMs ?? DEFAULT_TOOL_TIMEOUT_MS;
+        const parentSignal = options?.signal;
+        const id = `tool_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+        // Check if already aborted before starting
+        if (parentSignal?.aborted) {
+            return {
+                id,
+                toolName: name,
+                error: `Tool aborted before execution: ${name}`,
+                isError: true,
+            };
+        }
+        // Create a child AbortController that aborts on timeout OR parent abort
+        const childController = new AbortController();
+        const timerId = timeout > 0
+            ? setTimeout(() => childController.abort(new ToolTimeoutError(name, timeout)), timeout)
+            : undefined;
+        // Cascade parent abort to child
+        const onParentAbort = () => childController.abort(parentSignal?.reason);
+        parentSignal?.addEventListener("abort", onParentAbort, { once: true });
+        // Inject the abort signal into args so tools (like Agent) can use it
+        const argsWithSignal = { ...args, __signal: childController.signal };
+        // Build per-call ctx: caller's ctx (if any) + this call's signal
+        const ctx = options?.ctx
+            ? { ...options.ctx, signal: childController.signal }
+            : undefined;
+        try {
+            const result = await Promise.race([
+                executor(argsWithSignal, ctx),
+                new Promise((_, reject) => {
+                    childController.signal.addEventListener("abort", () => {
+                        const reason = childController.signal.reason;
+                        reject(reason instanceof ToolTimeoutError ? reason : new Error("Tool aborted"));
+                    }, { once: true });
+                }),
+            ]);
+            clearTimeout(timerId);
+            parentSignal?.removeEventListener("abort", onParentAbort);
+            return { id, toolName: name, result };
+        }
+        catch (err) {
+            clearTimeout(timerId);
+            parentSignal?.removeEventListener("abort", onParentAbort);
+            // Always return error as ToolResult, never throw
+            let errorMsg;
+            const isAbort = err?.name === "AbortError" ||
+                parentSignal?.aborted === true;
+            if (err instanceof ToolTimeoutError) {
+                errorMsg = `Tool timed out after ${timeout}ms: ${name}`;
+            }
+            else if (isAbort) {
+                errorMsg = `Tool aborted: ${name}`;
+            }
+            else {
+                errorMsg = err.message;
+            }
+            return { id, toolName: name, error: errorMsg, isError: true };
+        }
+    }
+    listTools() {
+        return [...this.tools.keys()];
+    }
+    listToolsDetailed() {
+        return [...this.tools.values()];
+    }
+}

package/dist/tool-system/sandbox/bwrap.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Linux bubblewrap backend.
+ *
+ * bwrap creates a fresh mount namespace, then bind-mounts only what we tell
+ * it. We bind / read-only and overlay writableRoots as read-write. PID,
+ * IPC, UTS, cgroup namespaces are unshared. Network is shared unless
+ * config.network === "deny".
+ *
+ * Sensitive directories listed in deniedReads are shadowed with a tmpfs so
+ * the inner process literally cannot see them even though `/` is mounted.
+ */
+import type { SandboxBackend, SandboxConfig } from "./index.js";
+export declare function createBwrapBackend(config: SandboxConfig): SandboxBackend;

package/dist/tool-system/sandbox/bwrap.js

@@ -0,0 +1,63 @@
+/**
+ * Linux bubblewrap backend.
+ *
+ * bwrap creates a fresh mount namespace, then bind-mounts only what we tell
+ * it. We bind / read-only and overlay writableRoots as read-write. PID,
+ * IPC, UTS, cgroup namespaces are unshared. Network is shared unless
+ * config.network === "deny".
+ *
+ * Sensitive directories listed in deniedReads are shadowed with a tmpfs so
+ * the inner process literally cannot see them even though `/` is mounted.
+ */
+export function createBwrapBackend(config) {
+    return {
+        name: "bwrap",
+        wrap(command, opts) {
+            const args = [];
+            args.push("--ro-bind", "/", "/");
+            args.push("--dev", "/dev");
+            args.push("--proc", "/proc");
+            args.push("--tmpfs", "/tmp");
+            for (const root of config.writableRoots) {
+                args.push("--bind-try", root, root);
+            }
+            // Shadow each denied path by bind-mounting /dev/null on top. Why this
+            // approach instead of `--tmpfs <denied>`:
+            //   1. `--tmpfs` requires the destination to exist (mount(2) does), so
+            //      a missing ~/.aws meant we had to skip the deny entirely — that's
+            //      a TOCTOU window: if the host creates ~/.aws between wrap-time
+            //      and spawn-time (or while the child is alive, since --ro-bind /
+            //      reflects live host state, not a snapshot), the shadow never
+            //      applies.
+            //   2. `--ro-bind-try /dev/null DEST` is no-op when DEST is missing on
+            //      the host (SRC is always there); when DEST exists, the bind hides
+            //      whatever was there. A read of the path returns EOF; directory
+            //      traversal fails (it's a char device, not a dir).
+            // The leftover case — DEST didn't exist at wrap-time, then appears on
+            // the host mid-run — is mitigated by `--ro-bind / /` making the rest of
+            // the filesystem read-only inside the sandbox, so the child can't
+            // create the path itself. A host-side concurrent write into a denied
+            // path is still visible to the sandbox; document that limitation in
+            // index.ts rather than papering over it here.
+            for (const denied of config.deniedReads) {
+                args.push("--ro-bind-try", "/dev/null", denied);
+            }
+            args.push("--unshare-pid", "--unshare-ipc", "--unshare-uts", "--unshare-cgroup");
+            if (config.network === "deny") {
+                args.push("--unshare-net");
+            }
+            args.push("--die-with-parent");
+            args.push("--chdir", opts.cwd);
+            args.push(opts.shell, "-c", command);
+            return { file: "bwrap", args };
+        },
+        hintForBlockedOutput(stderr) {
+            if (/Permission denied|No such file or directory.*bwrap/i.test(stderr)) {
+                return ("\n[sandbox:bwrap] A path access was blocked by the sandbox. " +
+                    "If this path should be writable, ask the user to update " +
+                    "sandbox.writableRoots in settings.json.");
+            }
+            return undefined;
+        },
+    };
+}

package/dist/tool-system/sandbox/index.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Sandbox backends for shell command execution.
+ *
+ * We wrap Bash-tool commands in an OS-level sandbox so a misbehaving (or
+ * prompt-injected) model can't reach beyond the workspace. The sandbox runs
+ * the user's command inside an isolated process tree with restricted file
+ * and (optionally) network access. The Engine itself is NOT sandboxed; only
+ * the spawned shell is. File-editing tools (Edit/Write) keep going through
+ * the application-layer permission gate.
+ *
+ * Backends are platform-specific:
+ *   - "seatbelt"  macOS sandbox-exec, built into macOS, zero install
+ *   - "bwrap"     Linux bubblewrap, requires `apt install bubblewrap`
+ *   - "off"       passthrough, no sandboxing (current behavior)
+ *
+ * "auto" picks per platform at startup; falls back to "off" with a warning
+ * when no sandbox is available.
+ */
+export type SandboxMode = "off" | "auto" | "seatbelt" | "bwrap";
+export type SandboxNetworkPolicy = "allow" | "deny";
+export interface SandboxConfig {
+    mode: SandboxMode;
+    writableRoots: string[];
+    deniedReads: string[];
+    network: SandboxNetworkPolicy;
+}
+export interface SandboxBackend {
+    /** Resolved backend name — "off" means no sandboxing. */
+    name: "off" | "seatbelt" | "bwrap";
+    /**
+     * Decide the binary + argv that should actually be spawned to run `command`
+     * under this sandbox. The shell still interprets `command`; we only swap
+     * the outer process.
+     */
+    wrap(command: string, opts: {
+        cwd: string;
+        shell: string;
+    }): {
+        file: string;
+        args: string[];
+        /**
+         * Optional callback the Bash tool calls after the child process exits.
+         * Backends that allocate per-command resources (e.g. seatbelt writes a
+         * profile file to a fresh temp dir) hang their cleanup here so a long
+         * session doesn't leak hundreds of temp dirs in /tmp.
+         */
+        cleanup?: () => void;
+    };
+    /**
+     * If `stderr` looks like a sandbox denial, return a short hint string that
+     * the Bash tool will append to its result so the model understands why.
+     */
+    hintForBlockedOutput?(stderr: string): string | undefined;
+}
+/**
+ * Detect which sandbox mechanisms are available on the current host. Used by
+ * "auto" mode and surfaced to the user via /sandbox status if desired.
+ */
+export declare function detectSandboxCapabilities(): {
+    seatbelt: boolean;
+    bwrap: boolean;
+};
+/**
+ * Expand `~` and `${workspace}` placeholders against the live cwd and home.
+ */
+export declare function expandPath(p: string, cwd: string): string;
+export declare function expandConfig(config: SandboxConfig, cwd: string): SandboxConfig;
+export declare function defaultSandboxConfig(mode?: SandboxMode): SandboxConfig;
+/**
+ * Resolve the active backend given user config + the current host.
+ *
+ *   "off"      → off backend
+ *   "seatbelt" → seatbelt if available, else throws (explicit choice)
+ *   "bwrap"    → bwrap if available, else throws
+ *   "auto"     → seatbelt on macOS, bwrap on Linux with bwrap installed,
+ *                else off + console warning
+ */
+export declare function resolveSandboxBackend(config: SandboxConfig, cwd: string): Promise<SandboxBackend>;

package/dist/tool-system/sandbox/index.js

@@ -0,0 +1,222 @@
+/**
+ * Sandbox backends for shell command execution.
+ *
+ * We wrap Bash-tool commands in an OS-level sandbox so a misbehaving (or
+ * prompt-injected) model can't reach beyond the workspace. The sandbox runs
+ * the user's command inside an isolated process tree with restricted file
+ * and (optionally) network access. The Engine itself is NOT sandboxed; only
+ * the spawned shell is. File-editing tools (Edit/Write) keep going through
+ * the application-layer permission gate.
+ *
+ * Backends are platform-specific:
+ *   - "seatbelt"  macOS sandbox-exec, built into macOS, zero install
+ *   - "bwrap"     Linux bubblewrap, requires `apt install bubblewrap`
+ *   - "off"       passthrough, no sandboxing (current behavior)
+ *
+ * "auto" picks per platform at startup; falls back to "off" with a warning
+ * when no sandbox is available.
+ */
+import { accessSync, constants, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { SandboxUnavailableError } from "../../exceptions.js";
+/**
+ * Detect which sandbox mechanisms are available on the current host. Used by
+ * "auto" mode and surfaced to the user via /sandbox status if desired.
+ */
+export function detectSandboxCapabilities() {
+    return {
+        seatbelt: process.platform === "darwin" && binaryExists("/usr/bin/sandbox-exec"),
+        bwrap: process.platform === "linux" && (binaryExists("/usr/bin/bwrap") || binaryExists("/usr/local/bin/bwrap")),
+    };
+}
+function binaryExists(path) {
+    try {
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Expand `~` and `${workspace}` placeholders against the live cwd and home.
+ */
+export function expandPath(p, cwd) {
+    if (p === "${workspace}")
+        return cwd;
+    if (p.startsWith("${workspace}/"))
+        return cwd + p.slice("${workspace}".length);
+    if (p === "~")
+        return homedir();
+    if (p.startsWith("~/"))
+        return homedir() + p.slice(1);
+    return p;
+}
+/**
+ * Resolve a path through any symlinks. On macOS `/var` and `/tmp` are
+ * symlinks to `/private/var` and `/private/tmp`; Seatbelt's `subpath` rules
+ * match by canonical (post-resolution) path, so a profile that lists
+ * `/var/folders/...` silently doesn't match when the syscall actually
+ * hits `/private/var/folders/...`. Resolving up front fixes this.
+ *
+ * Falls back to the original path when realpath fails (e.g. the path
+ * doesn't exist yet — common for deniedReads on hosts without those
+ * credential dirs).
+ */
+function canonicalize(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+export function expandConfig(config, cwd) {
+    return {
+        ...config,
+        writableRoots: config.writableRoots.map((p) => canonicalize(expandPath(p, cwd))),
+        deniedReads: config.deniedReads.map((p) => canonicalize(expandPath(p, cwd))),
+    };
+}
+/**
+ * Default config when the user hasn't supplied anything. Workspace +
+ * /tmp writable; ssh / cloud creds explicitly denied for read; network
+ * left open (sandboxing network breaks `npm install`, `git pull`, etc.,
+ * and most users find that surprising).
+ */
+/**
+ * Emit a one-shot warning when `auto` finds no usable backend. Per-process
+ * latch so a long REPL session doesn't repeat the message every Engine run.
+ * Suppressible with CODE_SHELL_SANDBOX_QUIET=1 for users who know.
+ */
+let autoDowngradeWarned = false;
+function warnAutoDowngrade() {
+    if (autoDowngradeWarned)
+        return;
+    if (process.env.CODE_SHELL_SANDBOX_QUIET === "1")
+        return;
+    autoDowngradeWarned = true;
+    const platform = process.platform;
+    let hint;
+    if (platform === "linux") {
+        hint = "install bubblewrap (apt install bubblewrap / dnf install bubblewrap)";
+    }
+    else if (platform === "win32") {
+        hint = "run code-shell inside WSL or a Docker container";
+    }
+    else {
+        hint = "this platform does not currently have an OS-level sandbox backend";
+    }
+    process.stderr.write(`[code-shell] sandbox=auto found no usable backend; shell commands will run unsandboxed. To fix: ${hint}. ` +
+        `Set sandbox.mode=off in settings.json to silence, or CODE_SHELL_SANDBOX_QUIET=1.\n`);
+}
+export function defaultSandboxConfig(mode = "auto") {
+    return {
+        mode,
+        writableRoots: ["${workspace}", "/tmp", "/private/tmp", "/var/tmp"],
+        deniedReads: [
+            "~/.ssh",
+            "~/.aws",
+            "~/.config/gcloud",
+            "~/.code-shell",
+            "~/.claude",
+        ],
+        network: "allow",
+    };
+}
+/**
+ * Resolve the active backend given user config + the current host.
+ *
+ *   "off"      → off backend
+ *   "seatbelt" → seatbelt if available, else throws (explicit choice)
+ *   "bwrap"    → bwrap if available, else throws
+ *   "auto"     → seatbelt on macOS, bwrap on Linux with bwrap installed,
+ *                else off + console warning
+ */
+export async function resolveSandboxBackend(config, cwd) {
+    const expanded = expandConfig(config, cwd);
+    const caps = detectSandboxCapabilities();
+    let chosen;
+    switch (config.mode) {
+        case "off":
+            chosen = "off";
+            break;
+        case "seatbelt":
+            if (!caps.seatbelt) {
+                throw new SandboxUnavailableError("seatbelt", process.platform, "sandbox.mode=seatbelt requested but sandbox-exec is unavailable (macOS-only). " +
+                    'Set sandbox.mode to "auto" or "off".');
+            }
+            chosen = "seatbelt";
+            break;
+        case "bwrap":
+            if (!caps.bwrap) {
+                throw new SandboxUnavailableError("bwrap", process.platform, "sandbox.mode=bwrap requested but bubblewrap (bwrap) is not installed. " +
+                    "Install with `apt install bubblewrap` (Debian/Ubuntu) or `dnf install bubblewrap` (Fedora).");
+            }
+            chosen = "bwrap";
+            break;
+        case "auto":
+            if (caps.seatbelt)
+                chosen = "seatbelt";
+            else if (caps.bwrap)
+                chosen = "bwrap";
+            else {
+                chosen = "off";
+                warnAutoDowngrade();
+            }
+            break;
+    }
+    switch (chosen) {
+        case "off": {
+            const { createOffBackend } = await import("./off.js");
+            return createOffBackend();
+        }
+        case "seatbelt": {
+            const { createSeatbeltBackend } = await import("./seatbelt.js");
+            // Same footgun as bwrap below: seatbelt's `(subpath "...")` rule for
+            // a non-existent path silently matches nothing, so a typo in
+            // writableRoots presents as "my sandbox blocks all writes" with no
+            // diagnostic. Warn so the user notices the dropped path up front.
+            warnMissingWritableRoots(expanded.writableRoots);
+            return createSeatbeltBackend(expanded);
+        }
+        case "bwrap": {
+            const { createBwrapBackend } = await import("./bwrap.js");
+            // bwrap's --bind-try silently skips paths that don't exist on the
+            // host. That's the right default (e.g. /private/tmp doesn't exist on
+            // Linux) but turns into invisible footguns for typos: a user adds
+            // "/work/important" to writableRoots, mistypes it as "/wrok/...", and
+            // every write looks blocked-by-sandbox with no diagnostic. Warn here
+            // so the user sees the path got dropped before the first command.
+            warnMissingWritableRoots(expanded.writableRoots);
+            return createBwrapBackend(expanded);
+        }
+    }
+}
+/**
+ * Warn once per session for each writableRoot that doesn't exist on the
+ * host. Keyed by absolute path so a long session doesn't repeat the same
+ * warning across many Engine.run() calls.
+ */
+const missingWritableWarned = new Set();
+function warnMissingWritableRoots(roots) {
+    if (process.env.CODE_SHELL_SANDBOX_QUIET === "1")
+        return;
+    for (const root of roots) {
+        if (missingWritableWarned.has(root))
+            continue;
+        let exists = false;
+        try {
+            accessSync(root, constants.F_OK);
+            exists = true;
+        }
+        catch {
+            // doesn't exist
+        }
+        if (!exists) {
+            missingWritableWarned.add(root);
+            process.stderr.write(`[code-shell] sandbox.writableRoots includes "${root}" which doesn't exist on this host — ` +
+                `writes there will be blocked. Check for typos in settings.json (silence with CODE_SHELL_SANDBOX_QUIET=1).\n`);
+        }
+    }
+}

package/dist/tool-system/sandbox/off.d.ts

@@ -0,0 +1,2 @@
+import type { SandboxBackend } from "./index.js";
+export declare function createOffBackend(): SandboxBackend;

package/dist/tool-system/sandbox/off.js

@@ -0,0 +1,8 @@
+export function createOffBackend() {
+    return {
+        name: "off",
+        wrap(command, opts) {
+            return { file: opts.shell, args: ["-c", command] };
+        },
+    };
+}

package/dist/tool-system/sandbox/seatbelt.d.ts

@@ -0,0 +1,18 @@
+/**
+ * macOS Seatbelt backend.
+ *
+ * Builds a sandbox-exec profile that:
+ *   - Allows reading most of the filesystem (denying everything breaks tooling)
+ *   - Denies reads of sensitive credential directories
+ *   - Restricts writes to the workspace + writableRoots
+ *   - Optionally denies outbound network
+ *
+ * The profile is written to a fresh temp file per command (cheap; users can
+ * have arbitrary writableRoots so we can't cache). The spawned process and
+ * its entire subprocess tree inherit the profile via XNU's sandbox framework.
+ *
+ * sandbox-exec is technically deprecated by Apple but remains the only
+ * working OS-level sandbox on macOS and is what Codex CLI / Cursor use today.
+ */
+import type { SandboxBackend, SandboxConfig } from "./index.js";
+export declare function createSeatbeltBackend(config: SandboxConfig): SandboxBackend;