comisai 1.0.4

package/node_modules/@comis/skills/dist/builtin/sandbox/bwrap-provider.js

@@ -0,0 +1,181 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * BwrapProvider -- Linux sandbox provider using Bubblewrap (bwrap).
+ *
+ * Generates bwrap CLI arguments that wrap child process spawns with
+ * kernel-enforced filesystem isolation using user namespaces.
+ *
+ * @module
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/**
+ * System paths to bind read-only. Filtered by existsSync once at
+ * first buildArgs() call and cached for the provider's lifetime.
+ */
+const SYSTEM_RO_PATHS = [
+    "/usr",
+    "/bin",
+    "/sbin",
+    "/lib",
+    "/lib64",
+    "/lib32",
+    "/etc/resolv.conf",
+    "/etc/hosts",
+    "/etc/hostname",
+    "/etc/ssl",
+    "/etc/ca-certificates",
+    "/etc/pki",
+    "/etc/ld.so.cache",
+    "/etc/ld.so.conf",
+    "/etc/ld.so.conf.d",
+    "/etc/alternatives",
+    "/etc/localtime",
+    "/etc/passwd",
+    "/etc/group",
+    "/etc/nsswitch.conf",
+];
+/**
+ * Per-user config paths to bind read-only. Resolved against the daemon
+ * user's HOME at startup. These contain no secrets -- git config has
+ * author name/email, not credentials (those live in credential helpers
+ * or ~/.ssh which is intentionally NOT mounted).
+ */
+function getUserRoPaths(home) {
+    /* eslint-disable no-restricted-syntax -- Trusted: constant subpaths of homedir, no user input */
+    return [
+        path.join(home, ".gitconfig"),
+        path.join(home, ".config", "git"),
+        // pip/uv: .pth files in system site-packages inject custom paths into
+        // sys.path. pip scans all sys.path via os.scandir(); without read access
+        // it crashes with PermissionError.
+        path.join(home, ".local"),
+        // nvm Node.js — npm/npx need to read their cli.js source files
+        path.join(home, ".nvm"),
+        // claude CLI auth/config at HOME root (not inside ~/.claude/ directory).
+        // Without read access, `claude -p` hangs indefinitely producing zero output.
+        path.join(home, ".claude.json"),
+        /* eslint-enable no-restricted-syntax */
+    ].filter((p) => existsSync(p));
+}
+/**
+ * Per-user claude CLI paths that need read-write access.
+ * ~/.claude/ stores history, cache, settings, hooks, and skills.
+ * ~/.local/share/claude/ stores version data and session state.
+ */
+function getClaudeCodeRwPaths(home) {
+    /* eslint-disable no-restricted-syntax -- Trusted: constant subpaths of homedir */
+    return [
+        path.join(home, ".claude"),
+        path.join(home, ".local", "share", "claude"),
+        /* eslint-enable no-restricted-syntax */
+    ].filter((p) => existsSync(p));
+}
+export class BwrapProvider {
+    name = "bwrap";
+    bwrapPath = null;
+    /** Cached set of system paths that exist (populated on first buildArgs call). */
+    resolvedSysPaths = null;
+    available() {
+        if (this.bwrapPath !== null)
+            return true;
+        try {
+            this.bwrapPath = execFileSync("which", ["bwrap"], { encoding: "utf8" }).trim();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    getSystemPaths() {
+        if (!this.resolvedSysPaths) {
+            this.resolvedSysPaths = SYSTEM_RO_PATHS.filter((p) => existsSync(p));
+        }
+        return this.resolvedSysPaths;
+    }
+    buildArgs(opts) {
+        const args = [this.bwrapPath];
+        // -- System paths (read-only, cached at first call) --
+        for (const sysPath of this.getSystemPaths()) {
+            args.push("--ro-bind", sysPath, sysPath);
+        }
+        // -- Special filesystems --
+        args.push("--proc", "/proc");
+        args.push("--dev", "/dev");
+        args.push("--dev-bind", "/dev/pts", "/dev/pts"); // PTY slave devices (interactive tools)
+        // -- Temp directory (read-write) --
+        args.push("--tmpfs", "/tmp");
+        if (opts.tempDir && opts.tempDir !== "/tmp") {
+            args.push("--bind", opts.tempDir, opts.tempDir);
+        }
+        // -- Workspace (read-write) --
+        args.push("--bind", opts.workspacePath, opts.workspacePath);
+        // -- Shared paths (read-write) --
+        for (const sp of opts.sharedPaths) {
+            args.push("--bind", sp, sp);
+        }
+        // -- User config paths (read-only) --
+        for (const up of getUserRoPaths(os.homedir())) {
+            args.push("--ro-bind", up, up);
+        }
+        // -- claude CLI paths (read-write) --
+        for (const cp of getClaudeCodeRwPaths(os.homedir())) {
+            args.push("--bind", cp, cp);
+        }
+        // -- Read-only paths (discovery paths, custom) --
+        for (const ro of opts.readOnlyPaths) {
+            if (existsSync(ro)) {
+                args.push("--ro-bind", ro, ro);
+            }
+        }
+        // -- Isolation flags --
+        args.push("--unshare-all", "--share-net", "--die-with-parent", "--new-session");
+        // -- Working directory --
+        args.push("--chdir", opts.cwd);
+        return args;
+    }
+    wrapEnv(env, workspacePath) {
+        // eslint-disable-next-line no-restricted-syntax -- Trusted: workspace path is daemon-controlled, constant subpaths
+        const cacheDir = path.join(workspacePath, ".cache");
+        return {
+            ...env,
+            // Temp files: heredocs, wheel builds, etc.
+            // eslint-disable-next-line no-restricted-syntax -- Trusted: workspace path is daemon-controlled, constant subpaths
+            TMPDIR: path.join(workspacePath, ".comis-tmp"),
+            // Package manager caches
+            // eslint-disable-next-line no-restricted-syntax -- Trusted: workspace path is daemon-controlled, constant subpaths
+            NPM_CONFIG_CACHE: path.join(cacheDir, "npm"),
+            // eslint-disable-next-line no-restricted-syntax -- Trusted: workspace path is daemon-controlled, constant subpaths
+            PIP_CACHE_DIR: path.join(cacheDir, "pip"),
+            XDG_CACHE_HOME: cacheDir,
+            // Python: redirect user packages into workspace.
+            // PYTHONNOUSERSITE is NOT set — sandbox read paths cover dirs that
+            // pip needs to scan. Removing it lets Python find packages installed
+            // to PYTHONUSERBASE.
+            // eslint-disable-next-line no-restricted-syntax -- Trusted: workspace path is daemon-controlled, constant subpaths
+            PYTHONUSERBASE: path.join(workspacePath, ".local"),
+            // eslint-disable-next-line no-restricted-syntax -- Trusted: workspace path is daemon-controlled, constant subpaths
+            MPLCONFIGDIR: path.join(cacheDir, "matplotlib"),
+            // Force non-interactive backend — prevents plt.show() from opening GUI and blocking
+            MPLBACKEND: "Agg",
+            // uv: redirect managed Python installs into workspace
+            // eslint-disable-next-line no-restricted-syntax -- Trusted: workspace path is daemon-controlled, constant subpaths
+            UV_PYTHON_INSTALL_DIR: path.join(cacheDir, "uv", "python"),
+            // Rust
+            // eslint-disable-next-line no-restricted-syntax -- Trusted: workspace path is daemon-controlled, constant subpaths
+            CARGO_HOME: path.join(cacheDir, "cargo"),
+            // Go
+            // eslint-disable-next-line no-restricted-syntax -- Trusted: workspace path is daemon-controlled, constant subpaths
+            GOPATH: path.join(cacheDir, "go"),
+            // eslint-disable-next-line no-restricted-syntax -- Trusted: workspace path is daemon-controlled, constant subpaths
+            GOMODCACHE: path.join(cacheDir, "go", "pkg", "mod"),
+            // Ruby
+            // eslint-disable-next-line no-restricted-syntax -- Trusted: workspace path is daemon-controlled, constant subpaths
+            GEM_HOME: path.join(cacheDir, "gems"),
+            // eslint-disable-next-line no-restricted-syntax -- Trusted: workspace path is daemon-controlled, constant subpaths
+            BUNDLE_PATH: path.join(cacheDir, "bundle"),
+        };
+    }
+}

package/node_modules/@comis/skills/dist/builtin/sandbox/detect-provider.d.ts

@@ -0,0 +1,20 @@
+/**
+ * detectSandboxProvider -- Platform sandbox provider detection factory.
+ *
+ * Called once at daemon startup to detect and return the best available
+ * OS-level sandbox provider. Returns undefined if no supported sandbox
+ * runtime is available.
+ *
+ * @module
+ */
+import type { SandboxProvider } from "./types.js";
+/** Minimal logger interface for sandbox detection. */
+export interface DetectLogger {
+    warn(obj: Record<string, unknown>, msg: string): void;
+}
+/**
+ * Detect and return the best available sandbox provider for this platform.
+ * Returns undefined if no sandbox runtime is available -- caller decides
+ * whether to proceed unsandboxed or abort.
+ */
+export declare function detectSandboxProvider(logger?: DetectLogger): SandboxProvider | undefined;

package/node_modules/@comis/skills/dist/builtin/sandbox/detect-provider.js

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * detectSandboxProvider -- Platform sandbox provider detection factory.
+ *
+ * Called once at daemon startup to detect and return the best available
+ * OS-level sandbox provider. Returns undefined if no supported sandbox
+ * runtime is available.
+ *
+ * @module
+ */
+import { BwrapProvider } from "./bwrap-provider.js";
+import { SandboxExecProvider } from "./sandbox-exec-provider.js";
+/**
+ * Detect and return the best available sandbox provider for this platform.
+ * Returns undefined if no sandbox runtime is available -- caller decides
+ * whether to proceed unsandboxed or abort.
+ */
+export function detectSandboxProvider(logger) {
+    if (process.platform === "linux") {
+        const bwrap = new BwrapProvider();
+        if (bwrap.available())
+            return bwrap;
+        logger?.warn({
+            hint: "Install bubblewrap for OS-level exec sandboxing: apt install bubblewrap",
+            errorKind: "config",
+        }, "bwrap not found -- exec tool will run without OS sandbox");
+        return undefined;
+    }
+    if (process.platform === "darwin") {
+        const sbexec = new SandboxExecProvider();
+        if (sbexec.available())
+            return sbexec;
+        logger?.warn({ hint: "sandbox-exec not found -- unexpected on macOS", errorKind: "config" }, "sandbox-exec not found -- exec tool will run without OS sandbox");
+        return undefined;
+    }
+    logger?.warn({
+        hint: `Platform "${process.platform}" has no supported sandbox runtime`,
+        errorKind: "config",
+    }, "Unsupported platform -- exec tool will run without OS sandbox");
+    return undefined;
+}

package/node_modules/@comis/skills/dist/builtin/sandbox/sandbox-exec-provider.d.ts

@@ -0,0 +1,15 @@
+/**
+ * SandboxExecProvider -- macOS sandbox provider using sandbox-exec.
+ *
+ * Generates SBPL (Sandbox Profile Language) profiles that restrict
+ * child process filesystem access via Apple's sandbox-exec utility.
+ *
+ * @module
+ */
+import type { SandboxOptions, SandboxProvider } from "./types.js";
+export declare class SandboxExecProvider implements SandboxProvider {
+    readonly name = "sandbox-exec";
+    available(): boolean;
+    buildArgs(opts: SandboxOptions): string[];
+    wrapEnv(env: Record<string, string>, workspacePath: string): Record<string, string>;
+}

package/node_modules/@comis/skills/dist/builtin/sandbox/sandbox-exec-provider.js

@@ -0,0 +1,201 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * SandboxExecProvider -- macOS sandbox provider using sandbox-exec.
+ *
+ * Generates SBPL (Sandbox Profile Language) profiles that restrict
+ * child process filesystem access via Apple's sandbox-exec utility.
+ *
+ * @module
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+/** Escape a path for SBPL string literal. */
+function sbplQuote(p) {
+    return `"${p.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+/**
+ * Resolve symlinks in a path for SBPL. On macOS, /var → /private/var,
+ * /tmp → /private/tmp, /etc → /private/etc. The kernel uses resolved
+ * paths for sandbox enforcement, so SBPL rules must use resolved paths.
+ */
+function resolvePath(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p; // Path doesn't exist yet — use as-is
+    }
+}
+function buildSbplProfile(opts) {
+    // User home subdirectories needed by pip/uv (read-only).
+    // pip scans all sys.path entries via os.scandir(); .pth files in system
+    // site-packages inject ~/Projects/... and ~/Library/Python/... paths.
+    // Without read access, pip crashes with PermissionError.
+    // eslint-disable-next-line no-restricted-syntax -- Trusted: reading HOME for sandbox profile, no secrets
+    const home = process.env.HOME ?? homedir();
+    /* eslint-disable no-restricted-syntax -- Trusted: constant subpaths of daemon homedir */
+    const homeReadPaths = [
+        path.join(home, "Library"),
+        path.join(home, "Projects"),
+        path.join(home, ".local"),
+        path.join(home, ".nvm"), // nvm Node.js — npm/npx cli.js lives here
+        path.join(home, ".claude"), // claude CLI config, settings, hooks, skills
+        /* eslint-enable no-restricted-syntax */
+    ].filter((p) => existsSync(p)).map(resolvePath);
+    // claude CLI stores auth/config at ~/.claude.json (a file at HOME root,
+    // not inside ~/.claude/ directory). Without read access, `claude -p` hangs
+    // indefinitely producing zero output.
+    /* eslint-disable no-restricted-syntax -- Trusted: constant path of daemon homedir */
+    const claudeJsonPath = path.join(home, ".claude.json");
+    /* eslint-enable no-restricted-syntax */
+    const claudeJsonLiteral = existsSync(claudeJsonPath) ? resolvePath(claudeJsonPath) : null;
+    const readPaths = [
+        "/usr",
+        "/bin",
+        "/sbin",
+        "/Library",
+        "/System",
+        "/private/etc",
+        "/private/var/db/timezone", // /usr/share/zoneinfo symlinks here; kernel resolves before sandbox check
+        "/var/db/timezone", // intermediate symlink target: /usr/share/zoneinfo → /var/db/timezone/zoneinfo
+        "/opt/homebrew",
+        "/usr/local",
+        "/dev",
+        "/private/tmp", // bash heredoc: creates temp files here, needs to read them back
+        ...homeReadPaths,
+        resolvePath(opts.workspacePath),
+        ...opts.sharedPaths.map(resolvePath),
+        ...opts.readOnlyPaths.map(resolvePath),
+    ];
+    // claude CLI directories that need write access:
+    // ~/.claude/ — history, cache, session state, plans
+    // ~/.local/share/claude/ — version data (already under ~/.local read path,
+    //   but needs write for updates; covered by ~/.local in homeReadPaths for reads)
+    /* eslint-disable no-restricted-syntax -- Trusted: constant subpaths of daemon homedir */
+    const claudeWritePaths = [
+        path.join(home, ".claude"),
+        path.join(home, ".local", "share", "claude"),
+        /* eslint-enable no-restricted-syntax */
+    ].filter((p) => existsSync(p)).map(resolvePath);
+    const writePaths = [
+        resolvePath(opts.workspacePath),
+        ...opts.sharedPaths.map(resolvePath),
+        ...claudeWritePaths,
+        "/private/tmp",
+        "/private/var/folders",
+    ];
+    const resolvedTempDir = resolvePath(opts.tempDir);
+    if (resolvedTempDir && resolvedTempDir !== "/tmp" && resolvedTempDir !== "/private/tmp") {
+        writePaths.push(resolvedTempDir);
+    }
+    const lines = [
+        "(version 1)",
+        "(deny default)",
+        "",
+        ";; Process execution",
+        "(allow process-exec)",
+        "(allow process-fork)",
+        "",
+        ";; System operations",
+        "(allow sysctl-read)",
+        "(allow mach-lookup)",
+        "(allow signal (target self))",
+        "",
+        ";; Network (allow all -- network isolation is a separate concern)",
+        "(allow network*)",
+        "",
+        ";; Path traversal: stat() on any path (type/size/perms only, not content)",
+        "(allow file-read-metadata)",
+        "",
+        ";; Root directory read (required for path resolution on macOS)",
+        '(allow file-read-data (literal "/"))',
+        "",
+        ";; Device writes (null, DTrace helper)",
+        '(allow file-write-data (literal "/dev/null"))',
+        '(allow file-write-data (literal "/dev/dtracehelper"))',
+        "",
+        ";; PTY/TTY device access (required for interactive tools: script, unbuffer, claude CLI)",
+        ";; posix_openpt/grantpt need write on /dev/ptmx; slave needs write on /dev/ttysNNN",
+        '(allow file-write* (literal "/dev/ptmx"))',
+        '(allow file-write* (regex #"^/dev/ttys[0-9]+$"))',
+        ";; ioctl on device files: tcgetattr/tcsetattr for terminal configuration",
+        '(allow file-ioctl (subpath "/dev"))',
+        "",
+        ";; Read access",
+        ...readPaths.map((p) => `(allow file-read* (subpath ${sbplQuote(p)}))`),
+        // claude CLI auth file at HOME root (literal, not subpath)
+        ...(claudeJsonLiteral ? [`(allow file-read* (literal ${sbplQuote(claudeJsonLiteral)}))`, `(allow file-write* (literal ${sbplQuote(claudeJsonLiteral)}))`] : []),
+        "",
+        ";; Write access",
+        ...writePaths.map((p) => `(allow file-write* (subpath ${sbplQuote(p)}))`),
+    ];
+    return lines.join("\n");
+}
+export class SandboxExecProvider {
+    name = "sandbox-exec";
+    available() {
+        try {
+            execFileSync("which", ["sandbox-exec"], { encoding: "utf8" });
+            // Runtime smoke test: verify sandbox-exec actually works with custom SBPL profiles.
+            // On macOS Sequoia 15.3+, sandbox-exec with custom profiles silently fails
+            // (exitCode 1, empty stdout/stderr). The minimal profile (allow default)
+            // permits everything -- we only need to confirm sandbox-exec can execute at all.
+            const out = execFileSync("sandbox-exec", ["-p", "(version 1)(allow default)", "/bin/echo", "ok"], { encoding: "utf8", timeout: 3000 });
+            if (!out.includes("ok")) {
+                return false;
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    buildArgs(opts) {
+        const profile = buildSbplProfile(opts);
+        return ["sandbox-exec", "-p", profile];
+    }
+    wrapEnv(env, workspacePath) {
+        // eslint-disable-next-line no-restricted-syntax -- Trusted: workspace path is daemon-controlled, constant subpaths
+        const cacheDir = path.join(workspacePath, ".cache");
+        return {
+            ...env,
+            // Temp files: heredocs, wheel builds, etc.
+            // eslint-disable-next-line no-restricted-syntax -- Trusted: workspace path is daemon-controlled, constant subpaths
+            TMPDIR: path.join(workspacePath, ".comis-tmp"),
+            // Package manager caches
+            // eslint-disable-next-line no-restricted-syntax -- Trusted: workspace path is daemon-controlled, constant subpaths
+            NPM_CONFIG_CACHE: path.join(cacheDir, "npm"),
+            // eslint-disable-next-line no-restricted-syntax -- Trusted: workspace path is daemon-controlled, constant subpaths
+            PIP_CACHE_DIR: path.join(cacheDir, "pip"),
+            XDG_CACHE_HOME: cacheDir,
+            // Python: redirect user packages into workspace.
+            // PYTHONNOUSERSITE is NOT set — sandbox read paths now include ~/Library
+            // and ~/Projects, so pip's sys.path scanning works. Removing it lets
+            // Python find packages installed to PYTHONUSERBASE.
+            // eslint-disable-next-line no-restricted-syntax -- Trusted: workspace path is daemon-controlled, constant subpaths
+            PYTHONUSERBASE: path.join(workspacePath, ".local"),
+            // eslint-disable-next-line no-restricted-syntax -- Trusted: workspace path is daemon-controlled, constant subpaths
+            MPLCONFIGDIR: path.join(cacheDir, "matplotlib"),
+            // Force non-interactive backend — prevents plt.show() from opening GUI and blocking
+            MPLBACKEND: "Agg",
+            // uv: redirect managed Python installs into workspace
+            // eslint-disable-next-line no-restricted-syntax -- Trusted: workspace path is daemon-controlled, constant subpaths
+            UV_PYTHON_INSTALL_DIR: path.join(cacheDir, "uv", "python"),
+            // Rust
+            // eslint-disable-next-line no-restricted-syntax -- Trusted: workspace path is daemon-controlled, constant subpaths
+            CARGO_HOME: path.join(cacheDir, "cargo"),
+            // Go
+            // eslint-disable-next-line no-restricted-syntax -- Trusted: workspace path is daemon-controlled, constant subpaths
+            GOPATH: path.join(cacheDir, "go"),
+            // eslint-disable-next-line no-restricted-syntax -- Trusted: workspace path is daemon-controlled, constant subpaths
+            GOMODCACHE: path.join(cacheDir, "go", "pkg", "mod"),
+            // Ruby
+            // eslint-disable-next-line no-restricted-syntax -- Trusted: workspace path is daemon-controlled, constant subpaths
+            GEM_HOME: path.join(cacheDir, "gems"),
+            // eslint-disable-next-line no-restricted-syntax -- Trusted: workspace path is daemon-controlled, constant subpaths
+            BUNDLE_PATH: path.join(cacheDir, "bundle"),
+        };
+    }
+}

package/node_modules/@comis/skills/dist/builtin/sandbox/types.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Sandbox runtime types for exec tool OS-level isolation.
+ *
+ * These interfaces define the contract between the daemon (which detects
+ * and creates sandbox providers at startup) and the exec tool (which uses
+ * them to wrap child process spawns). The Zod config schema lives in
+ * @comis/core; these are runtime-only types.
+ *
+ * @module
+ */
+import type { LazyPaths } from "../file/safe-path-wrapper.js";
+/** Options passed to SandboxProvider.buildArgs() to generate sandbox CLI arguments. */
+export interface SandboxOptions {
+    /** Agent workspace directory (read-write inside sandbox). */
+    workspacePath: string;
+    /** Additional directories with read-write access (e.g., graph pipeline shared dirs). */
+    sharedPaths: string[];
+    /** Directories with read-only access inside sandbox. */
+    readOnlyPaths: string[];
+    /** Working directory for the sandboxed command. */
+    cwd: string;
+    /** Temp directory inside workspace for spillover files. */
+    tempDir: string;
+}
+/** Platform-specific sandbox provider (bwrap on Linux, sandbox-exec on macOS). */
+export interface SandboxProvider {
+    /** Provider name for logging (e.g., "bwrap", "sandbox-exec"). */
+    readonly name: string;
+    /** Whether the sandbox binary is available on this system. Result may be cached. */
+    available(): boolean;
+    /** Build CLI arguments to wrap a command in the sandbox. */
+    buildArgs(opts: SandboxOptions): string[];
+    /** Optional: modify environment variables for sandboxed process (e.g., redirect cache dirs). */
+    wrapEnv?(env: Record<string, string>, workspacePath: string): Record<string, string>;
+}
+/** Runtime sandbox configuration passed to createExecTool(). */
+export interface ExecSandboxConfig {
+    /** The platform sandbox provider instance. */
+    sandbox: SandboxProvider;
+    /** Read-write shared directories (from graph pipeline or assembleToolsForAgent). Supports lazy resolution. */
+    sharedPaths: LazyPaths;
+    /** Read-only directories (from skill discovery paths). */
+    readOnlyPaths: string[];
+    /** Read-only directories from operator config (execSandbox.readOnlyAllowPaths). */
+    configReadOnlyPaths: string[];
+}

package/node_modules/@comis/skills/dist/builtin/sandbox/types.js

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Sandbox runtime types for exec tool OS-level isolation.
+ *
+ * These interfaces define the contract between the daemon (which detects
+ * and creates sandbox providers at startup) and the exec tool (which uses
+ * them to wrap child process spawns). The Zod config schema lives in
+ * @comis/core; these are runtime-only types.
+ *
+ * @module
+ */
+export {};

package/node_modules/@comis/skills/dist/builtin/search-provider.d.ts

@@ -0,0 +1,81 @@
+/**
+ * SearchProvider interface and registry for the web_search tool.
+ *
+ * Formalizes the implicit contract across 8 search providers into a typed
+ * interface with registry-based dispatch. Each provider exports a
+ * `SearchProvider` descriptor; the web-search-tool orchestrator dispatches
+ * via the registry instead of individual imports.
+ *
+ * Two provider categories exist:
+ * - **Result providers** (Brave, DuckDuckGo, SearXNG, Tavily, Exa, Jina):
+ *   return structured `{ results, count }` with per-result title/url/description.
+ * - **AI providers** (Perplexity, Grok): return synthesized `{ content, citations }`
+ *   with optional inline citations.
+ *
+ * The `execute` function returns a generic `Record<string, unknown>` payload
+ * that the orchestrator passes through unchanged, preserving provider-specific
+ * fields (e.g. Brave's `published`/`siteName`, Grok's `inlineCitations`).
+ *
+ * @module
+ */
+import type { WrapExternalContentOptions } from "@comis/core";
+/**
+ * Common configuration passed to every search provider's execute function.
+ * Provider-specific params (e.g., Brave's `freshness`, Grok's `inlineCitations`)
+ * are passed via the `providerConfig` escape hatch.
+ */
+export interface SearchProviderParams {
+    /** The search query string. */
+    query: string;
+    /** Number of results to return. */
+    count: number;
+    /** API key for the provider (may be "no-key-needed" for keyless providers). */
+    apiKey: string;
+    /** Timeout for the HTTP request in seconds. */
+    timeoutSeconds: number;
+    /** Optional callback for suspicious content detection. */
+    onSuspiciousContent?: WrapExternalContentOptions["onSuspiciousContent"];
+    /**
+     * Provider-specific configuration. Each provider reads only the keys it
+     * needs and ignores the rest. Avoids polluting the common interface with
+     * provider-specific fields.
+     */
+    providerConfig?: Record<string, unknown>;
+}
+/**
+ * Descriptor for a single search provider.
+ *
+ * Each `web-search-xxx.ts` module exports a `SearchProvider` that the
+ * `searchProviders` registry collects. The orchestrator looks up the provider
+ * by name and calls `execute(params)`.
+ */
+export interface SearchProvider {
+    /** Provider name matching the SearchProviderName union in web-search-tool. */
+    readonly name: string;
+    /** Whether this provider requires an API key to function. */
+    readonly requiresApiKey: boolean;
+    /**
+     * Execute a search and return a payload. The shape varies by provider:
+     * - Result providers return `{ results: [...], count: N }`.
+     * - AI providers return `{ content: "...", citations: [...] }`.
+     * The orchestrator passes the payload through unchanged.
+     */
+    execute(params: SearchProviderParams): Promise<Record<string, unknown>>;
+}
+/**
+ * Registry of all search providers, keyed by provider name.
+ * Populated by importing provider modules at the bottom of this file.
+ *
+ * Use `getSearchProvider(name)` for safe lookup.
+ */
+export declare const searchProviders: Map<string, SearchProvider>;
+/**
+ * Register a search provider in the global registry.
+ * Called by each provider module to self-register.
+ */
+export declare function registerSearchProvider(provider: SearchProvider): void;
+/**
+ * Look up a search provider by name.
+ * Returns undefined if the provider is not registered.
+ */
+export declare function getSearchProvider(name: string): SearchProvider | undefined;

package/node_modules/@comis/skills/dist/builtin/search-provider.js

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * SearchProvider interface and registry for the web_search tool.
+ *
+ * Formalizes the implicit contract across 8 search providers into a typed
+ * interface with registry-based dispatch. Each provider exports a
+ * `SearchProvider` descriptor; the web-search-tool orchestrator dispatches
+ * via the registry instead of individual imports.
+ *
+ * Two provider categories exist:
+ * - **Result providers** (Brave, DuckDuckGo, SearXNG, Tavily, Exa, Jina):
+ *   return structured `{ results, count }` with per-result title/url/description.
+ * - **AI providers** (Perplexity, Grok): return synthesized `{ content, citations }`
+ *   with optional inline citations.
+ *
+ * The `execute` function returns a generic `Record<string, unknown>` payload
+ * that the orchestrator passes through unchanged, preserving provider-specific
+ * fields (e.g. Brave's `published`/`siteName`, Grok's `inlineCitations`).
+ *
+ * @module
+ */
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+/**
+ * Registry of all search providers, keyed by provider name.
+ * Populated by importing provider modules at the bottom of this file.
+ *
+ * Use `getSearchProvider(name)` for safe lookup.
+ */
+export const searchProviders = new Map();
+/**
+ * Register a search provider in the global registry.
+ * Called by each provider module to self-register.
+ */
+export function registerSearchProvider(provider) {
+    searchProviders.set(provider.name, provider);
+}
+/**
+ * Look up a search provider by name.
+ * Returns undefined if the provider is not registered.
+ */
+export function getSearchProvider(name) {
+    return searchProviders.get(name);
+}