synorch 0.2.0 → 0.4.0-beta.0

package/dist/harness/tools/process.js

@@ -0,0 +1,263 @@
+import { spawn, spawnSync } from "node:child_process";
+import { performance } from "node:perf_hooks";
+import { planLaunch } from "./windows-launch.js";
+const INTERRUPT_GRACE_MS = 1_500;
+const CLOSE_GRACE_MS = 5_000;
+/**
+ * Runs one argv without a shell (on Windows a `.cmd`/`.bat` shim is launched as `planLaunch`
+ * decides: its node target directly, or cmd.exe with every argument quoted), with piped stdio (no console code-page inheritance), an explicit
+ * environment, a wall-clock timeout and cancellation that terminates the whole process tree:
+ * `taskkill /T /F` on Windows, SIGINT then SIGKILL to the process group elsewhere. Output beyond
+ * the limit is dropped (the pipes keep draining) and reported as truncated.
+ */
+export async function runProcess(argv, options, signal) {
+    const started = performance.now();
+    let launch;
+    try {
+        launch = await planLaunch(argv, { cwd: options.cwd, env: options.env, ...(options.untrustedRoots === undefined ? {} : { untrustedRoots: options.untrustedRoots }) });
+    }
+    catch (error) {
+        return failedSpawn(error, started);
+    }
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn(launch.file, [...launch.args], {
+                cwd: options.cwd,
+                env: { ...launch.env },
+                stdio: ["pipe", "pipe", "pipe"],
+                shell: false,
+                windowsHide: true,
+                windowsVerbatimArguments: launch.verbatim,
+                detached: process.platform !== "win32",
+            });
+        }
+        catch (error) {
+            resolve(failedSpawn(error, started));
+            return;
+        }
+        const stdout = [];
+        const stderr = [];
+        let captured = 0;
+        let truncated = false;
+        let timedOut = false;
+        let cancelled = false;
+        let spawnError;
+        let settled = false;
+        let forceTimer;
+        const collect = (target) => (chunk) => {
+            const room = options.outputLimitBytes - captured;
+            if (room <= 0) {
+                truncated = true;
+                return;
+            }
+            const kept = chunk.length > room ? chunk.subarray(0, room) : chunk;
+            if (kept.length < chunk.length)
+                truncated = true;
+            target.push(kept);
+            captured += kept.length;
+        };
+        child.stdout?.on("data", collect(stdout));
+        child.stderr?.on("data", collect(stderr));
+        child.stdin?.on("error", () => undefined);
+        child.stdin?.end(options.stdin ?? "");
+        const finish = (exitCode, exitSignal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (forceTimer !== undefined)
+                clearTimeout(forceTimer);
+            signal.removeEventListener("abort", onAbort);
+            const neverStarted = spawnError !== undefined && child.pid === undefined;
+            resolve({
+                termination: neverStarted ? "spawn-failed" : cancelled ? "cancelled" : timedOut ? "timeout" : "exited",
+                exitCode,
+                signal: exitSignal,
+                stdout: decode(stdout),
+                stderr: decode(stderr),
+                truncated,
+                spawnError,
+                durationMs: Math.round(performance.now() - started),
+            });
+        };
+        const terminate = () => {
+            void killTree(child).finally(() => {
+                forceTimer = setTimeout(() => {
+                    child.stdout?.destroy();
+                    child.stderr?.destroy();
+                    finish(child.exitCode, child.signalCode);
+                }, CLOSE_GRACE_MS);
+            });
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            terminate();
+        }, options.timeoutMs);
+        const onAbort = () => {
+            cancelled = true;
+            terminate();
+        };
+        child.on("error", (error) => {
+            spawnError = error.message;
+            if (child.pid === undefined)
+                finish(null, null);
+        });
+        child.on("close", (code, closeSignal) => finish(code, closeSignal));
+        if (signal.aborted)
+            onAbort();
+        else
+            signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/**
+ * K4.2: starts one argv like `runProcess` (same launch plan, piped stdio, explicit environment)
+ * but returns at once with streamed output. `timeoutMs` bounds the child's lifetime; the caller
+ * kills the tree when the session ends.
+ */
+export function startProcess(argv, options) {
+    const listeners = [];
+    let child;
+    let timedOut = false;
+    let killed = false;
+    const exited = (async () => {
+        let launch;
+        try {
+            launch = await planLaunch(argv, { cwd: options.cwd, env: options.env, ...(options.untrustedRoots === undefined ? {} : { untrustedRoots: options.untrustedRoots }) });
+        }
+        catch (error) {
+            return { termination: "spawn-failed", exitCode: null, signal: null, spawnError: error instanceof Error ? error.message : String(error) };
+        }
+        if (killed)
+            return { termination: "cancelled", exitCode: null, signal: null, spawnError: undefined };
+        return new Promise((resolve) => {
+            let spawned;
+            try {
+                spawned = spawn(launch.file, [...launch.args], {
+                    cwd: options.cwd,
+                    env: { ...launch.env },
+                    stdio: ["pipe", "pipe", "pipe"],
+                    shell: false,
+                    windowsHide: true,
+                    windowsVerbatimArguments: launch.verbatim,
+                    detached: process.platform !== "win32",
+                });
+            }
+            catch (error) {
+                resolve({ termination: "spawn-failed", exitCode: null, signal: null, spawnError: error instanceof Error ? error.message : String(error) });
+                return;
+            }
+            child = spawned;
+            let spawnError;
+            let settled = false;
+            const emit = (stream) => (chunk) => {
+                const text = chunk.toString("utf8");
+                for (const listener of listeners)
+                    listener(text, stream);
+            };
+            spawned.stdout?.on("data", emit("stdout"));
+            spawned.stderr?.on("data", emit("stderr"));
+            spawned.stdin?.on("error", () => undefined);
+            spawned.stdin?.end(options.stdin ?? "");
+            const timer = setTimeout(() => {
+                timedOut = true;
+                void killTree(spawned);
+            }, options.timeoutMs);
+            timer.unref?.();
+            const finish = (exitCode, exitSignal) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                const neverStarted = spawnError !== undefined && spawned.pid === undefined;
+                resolve({ termination: neverStarted ? "spawn-failed" : killed ? "cancelled" : timedOut ? "timeout" : "exited", exitCode, signal: exitSignal, spawnError });
+            };
+            spawned.on("error", (error) => {
+                spawnError = error.message;
+                if (spawned.pid === undefined)
+                    finish(null, null);
+            });
+            spawned.on("close", (code, closeSignal) => finish(code, closeSignal));
+        });
+    })();
+    return {
+        get pid() {
+            return child?.pid;
+        },
+        onOutput(listener) {
+            listeners.push(listener);
+        },
+        exited,
+        async kill() {
+            killed = true;
+            if (child !== undefined)
+                await killTree(child);
+        },
+        killSync() {
+            killed = true;
+            const pid = child?.pid;
+            if (pid === undefined || child?.exitCode !== null)
+                return;
+            if (process.platform === "win32") {
+                spawnSync("taskkill", ["/PID", String(pid), "/T", "/F"], { windowsHide: true, stdio: "ignore" });
+                return;
+            }
+            signalGroup(pid, "SIGKILL");
+        },
+    };
+}
+/** Terminates a child and every descendant it started. */
+export async function killTree(child) {
+    const pid = child.pid;
+    if (pid === undefined || child.exitCode !== null)
+        return;
+    if (process.platform === "win32") {
+        await new Promise((resolve) => {
+            const killer = spawn("taskkill", ["/PID", String(pid), "/T", "/F"], { windowsHide: true, stdio: "ignore" });
+            killer.on("error", () => resolve());
+            killer.on("close", () => resolve());
+        });
+        return;
+    }
+    signalGroup(pid, "SIGINT");
+    await new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            signalGroup(pid, "SIGKILL");
+            resolve();
+        }, INTERRUPT_GRACE_MS);
+        child.once("close", () => {
+            clearTimeout(timer);
+            signalGroup(pid, "SIGKILL");
+            resolve();
+        });
+    });
+}
+function signalGroup(pid, name) {
+    try {
+        process.kill(-pid, name);
+    }
+    catch {
+        try {
+            process.kill(pid, name);
+        }
+        catch {
+            return;
+        }
+    }
+}
+function decode(chunks) {
+    return Buffer.concat(chunks).toString("utf8").replace(/�$/, "");
+}
+function failedSpawn(error, started) {
+    return {
+        termination: "spawn-failed",
+        exitCode: null,
+        signal: null,
+        stdout: "",
+        stderr: "",
+        truncated: false,
+        spawnError: error instanceof Error ? error.message : String(error),
+        durationMs: Math.round(performance.now() - started),
+    };
+}
+//# sourceMappingURL=process.js.map

package/dist/harness/tools/process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.js","sourceRoot":"","sources":["../../../src/harness/tools/process.ts"],"names":[],"mappings":"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"}

package/dist/harness/tools/redaction.d.ts

@@ -0,0 +1,26 @@
+import type { BlobRef, BlobStore } from "../contracts/index.ts";
+/**
+ * Output hygiene applied by the gateway before anything reaches the model, the event log or a
+ * blob: exact credential values reported by the auth layer (`ResolvedCredential.redactionValues`)
+ * and well-known secret shapes are replaced, then output above the inline cap moves to a blob.
+ */
+export declare const REDACTED = "[redacted]";
+export declare const INLINE_OUTPUT_LIMIT_BYTES: number;
+export interface RedactionResult {
+    readonly text: string;
+    readonly count: number;
+}
+export type Redactor = (text: string) => RedactionResult;
+export declare function createRedactor(values: () => readonly string[]): Redactor;
+/** True when any exact credential value occurs in the text (hard rail `secret-egress` on arguments). */
+export declare function containsCredentialValue(text: string, values: readonly string[]): boolean;
+export interface BoundedText {
+    readonly text: string;
+    readonly blob: BlobRef | undefined;
+}
+/**
+ * Keeps text inline up to 16 KiB; larger text is stored whole as a blob and previewed head + tail.
+ * `hint` tells the model how to see the omitted part with the same tool (audit F18).
+ */
+export declare function boundText(text: string, blobs: BlobStore, hint?: string): Promise<BoundedText>;
+//# sourceMappingURL=redaction.d.ts.map

package/dist/harness/tools/redaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redaction.d.ts","sourceRoot":"","sources":["../../../src/harness/tools/redaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEhE;;;;GAIG;AAEH,eAAO,MAAM,QAAQ,eAAe,CAAC;AACrC,eAAO,MAAM,yBAAyB,QAAY,CAAC;AA8BnD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,QAAQ,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,eAAe,CAAC;AAEzD,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,SAAS,MAAM,EAAE,GAAG,QAAQ,CAsBxE;AAED,wGAAwG;AACxG,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAExF;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,CAAC;CACpC;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAQnG"}

package/dist/harness/tools/redaction.js

@@ -0,0 +1,77 @@
+/**
+ * Output hygiene applied by the gateway before anything reaches the model, the event log or a
+ * blob: exact credential values reported by the auth layer (`ResolvedCredential.redactionValues`)
+ * and well-known secret shapes are replaced, then output above the inline cap moves to a blob.
+ */
+export const REDACTED = "[redacted]";
+export const INLINE_OUTPUT_LIMIT_BYTES = 16 * 1024;
+const PREVIEW_HEAD_BYTES = 12 * 1024;
+const PREVIEW_TAIL_BYTES = 3 * 1024;
+const MIN_EXACT_VALUE_LENGTH = 6;
+const whole = () => REDACTED;
+const SECRET_SHAPES = [
+    { pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, replace: whole },
+    { pattern: /sk-(?:ant-|proj-)?[A-Za-z0-9_-]{20,}/g, replace: whole },
+    { pattern: /gh[pousr]_[A-Za-z0-9]{30,}/g, replace: whole },
+    { pattern: /github_pat_[A-Za-z0-9_]{40,}/g, replace: whole },
+    { pattern: /glpat-[A-Za-z0-9_-]{20,}/g, replace: whole },
+    { pattern: /npm_[A-Za-z0-9]{36}/g, replace: whole },
+    { pattern: /AKIA[0-9A-Z]{16}/g, replace: whole },
+    { pattern: /xox[abprs]-[A-Za-z0-9-]{10,}/g, replace: whole },
+    { pattern: /eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g, replace: whole },
+    { pattern: /(authorization:\s*(?:bearer|basic|token)\s+)[A-Za-z0-9._~+/=-]{8,}/gi, replace: (_match, prefix = "") => `${prefix}${REDACTED}` },
+    { pattern: /(:\/\/[^/\s:@]+:)[^/\s@[]{6,}(@)/g, replace: (_match, prefix = "", suffix = "") => `${prefix}${REDACTED}${suffix}` },
+    {
+        pattern: /\b([A-Za-z0-9_]*(?:API_KEY|APIKEY|SECRET|TOKEN|PASSWORD|PASSWD)[A-Za-z0-9_]*)(\s*[=:]\s*)(["']?)([^\s"'[]{6,})\3/gi,
+        replace: (_match, name = "", separator = "", quote = "") => `${name}${separator}${quote}${REDACTED}${quote}`,
+    },
+];
+export function createRedactor(values) {
+    return (text) => {
+        let count = 0;
+        let output = text;
+        const exact = [...new Set(values())].filter((value) => value.length >= MIN_EXACT_VALUE_LENGTH).sort((left, right) => right.length - left.length);
+        for (const value of exact) {
+            const parts = output.split(value);
+            if (parts.length > 1) {
+                count += parts.length - 1;
+                output = parts.join(REDACTED);
+            }
+        }
+        for (const shape of SECRET_SHAPES) {
+            output = output.replace(shape.pattern, (...args) => {
+                const match = String(args[0]);
+                count += 1;
+                const groups = args.slice(1).filter((value) => typeof value === "string");
+                return shape.replace(match, ...groups);
+            });
+        }
+        return { text: output, count };
+    };
+}
+/** True when any exact credential value occurs in the text (hard rail `secret-egress` on arguments). */
+export function containsCredentialValue(text, values) {
+    return values.some((value) => value.length >= MIN_EXACT_VALUE_LENGTH && text.includes(value));
+}
+/**
+ * Keeps text inline up to 16 KiB; larger text is stored whole as a blob and previewed head + tail.
+ * `hint` tells the model how to see the omitted part with the same tool (audit F18).
+ */
+export async function boundText(text, blobs, hint) {
+    const bytes = Buffer.from(text, "utf8");
+    if (bytes.length <= INLINE_OUTPUT_LIMIT_BYTES)
+        return { text, blob: undefined };
+    const blob = await blobs.put(new Uint8Array(bytes), "text/plain; charset=utf-8");
+    const head = sliceUtf8(bytes, 0, PREVIEW_HEAD_BYTES);
+    const tail = sliceUtf8(bytes, bytes.length - PREVIEW_TAIL_BYTES, bytes.length);
+    const marker = `\n… [${bytes.length - Buffer.byteLength(head) - Buffer.byteLength(tail)} bytes omitted; ${hint ?? "truncated"}; full output in blob ${blob.digest}] …\n`;
+    return { text: head + marker + tail, blob };
+}
+function sliceUtf8(bytes, start, end) {
+    return bytes
+        .subarray(Math.max(0, start), end)
+        .toString("utf8")
+        .replace(/^�+/, "")
+        .replace(/�+$/, "");
+}
+//# sourceMappingURL=redaction.js.map

package/dist/harness/tools/redaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redaction.js","sourceRoot":"","sources":["../../../src/harness/tools/redaction.ts"],"names":[],"mappings":"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"}

package/dist/harness/tools/registry.d.ts

@@ -0,0 +1,26 @@
+import { type ToolRegistry } from "../contracts/index.ts";
+import { type ControlCallbacks } from "./builtin/control-tools.ts";
+import { type CommandClassifierHint } from "./builtin/process-tools.ts";
+import { BackgroundProcessManager } from "./builtin/process-bg.ts";
+import type { SafeFetchOptions } from "./builtin/web-net.ts";
+import { type WebSearchRunner } from "./builtin/web-search.ts";
+import type { WebSession } from "./builtin/web-state.ts";
+export interface ToolRegistryOptions {
+    /** Register the v1 built-in tools (default true). */
+    readonly builtins?: boolean;
+    /** Parent environment that child-process allowlists read from (default `process.env`). */
+    readonly environment?: Readonly<Record<string, string | undefined>>;
+    readonly classifyCommand?: CommandClassifierHint;
+    readonly control?: ControlCallbacks;
+    /** K4.1: registers `web_search` (over the injected backends) and `web_fetch`. */
+    readonly web?: {
+        readonly session: WebSession;
+        readonly search: WebSearchRunner;
+        readonly transport?: SafeFetchOptions;
+    };
+    /** K4.2: the session's background processes (a private manager when absent). */
+    readonly processes?: BackgroundProcessManager;
+}
+/** The v1 registry: built-in tools plus anything registered later; every tool's metadata is validated. */
+export declare function createToolRegistry(options?: ToolRegistryOptions): ToolRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/harness/tools/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/harness/tools/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,YAAY,EAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAsB,KAAK,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACvF,OAAO,EAA0D,KAAK,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEhI,OAAO,EAAE,wBAAwB,EAAsB,MAAM,yBAAyB,CAAC;AAKvF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,yBAAyB,CAAC;AACpF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD,MAAM,WAAW,mBAAmB;IAClC,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,0FAA0F;IAC1F,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IACpE,QAAQ,CAAC,eAAe,CAAC,EAAE,qBAAqB,CAAC;IACjD,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;IACpC,iFAAiF;IACjF,QAAQ,CAAC,GAAG,CAAC,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;QAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAA;KAAE,CAAC;IACzH,gFAAgF;IAChF,QAAQ,CAAC,SAAS,CAAC,EAAE,wBAAwB,CAAC;CAC/C;AAED,0GAA0G;AAC1G,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,YAAY,CA0ClF"}

package/dist/harness/tools/registry.js

@@ -0,0 +1,57 @@
+import { toolMetadataSchema, } from "../contracts/index.js";
+import { createControlTools } from "./builtin/control-tools.js";
+import { createExecTool, createGitDiffTool, createGitStatusTool } from "./builtin/process-tools.js";
+import { createGlobTool } from "./builtin/glob.js";
+import { BackgroundProcessManager, createProcessTools } from "./builtin/process-bg.js";
+import { createTodoTool } from "./builtin/todo.js";
+import { createListDirTool, createReadFileTool, createSearchTool } from "./builtin/read-tools.js";
+import { createApplyPatchTool, createWriteFileTool } from "./builtin/write-tools.js";
+import { createWebFetchTool } from "./builtin/web-fetch.js";
+import { createWebSearchTool } from "./builtin/web-search.js";
+/** The v1 registry: built-in tools plus anything registered later; every tool's metadata is validated. */
+export function createToolRegistry(options = {}) {
+    const tools = new Map();
+    const registry = {
+        register(tool) {
+            toolMetadataSchema.parse(tool.metadata);
+            if (tools.has(tool.metadata.name))
+                throw new Error(`tool ${tool.metadata.name} is already registered`);
+            tools.set(tool.metadata.name, tool);
+        },
+        unregister: (name) => tools.delete(name),
+        get: (name) => tools.get(name),
+        visibleTo(role, policy) {
+            return [...tools.values()]
+                .filter((tool) => tool.metadata.visible_to.includes(role) && policy.effects[tool.metadata.effect] !== "deny")
+                .map((tool) => tool.descriptor());
+        },
+    };
+    if (options.builtins ?? true) {
+        const background = options.processes ?? new BackgroundProcessManager();
+        const environment = options.environment ?? process.env;
+        const processOptions = { environment, classifyCommand: options.classifyCommand, background };
+        const builtins = [
+            createReadFileTool(),
+            createSearchTool(),
+            createListDirTool(),
+            createGitStatusTool(processOptions),
+            createGitDiffTool(processOptions),
+            createApplyPatchTool(),
+            createWriteFileTool(),
+            createExecTool(processOptions),
+            ...createProcessTools(background),
+            createGlobTool({ environment }),
+            createTodoTool(),
+            ...createControlTools(options.control ?? {}),
+        ];
+        const web = options.web;
+        if (web !== undefined) {
+            builtins.push(createWebSearchTool({ session: web.session, environment, search: web.search }));
+            builtins.push(createWebFetchTool({ session: web.session, environment, ...(web.transport === undefined ? {} : { transport: web.transport }) }));
+        }
+        for (const tool of builtins)
+            registry.register(tool);
+    }
+    return registry;
+}
+//# sourceMappingURL=registry.js.map

package/dist/harness/tools/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/harness/tools/registry.ts"],"names":[],"mappings":"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"}

package/dist/harness/tools/sandbox.d.ts

@@ -0,0 +1,23 @@
+import { type ProcessSpec, type SandboxReport, type SandboxRunner } from "../contracts/index.ts";
+/**
+ * OS sandbox backends (ADR-06). The runner applies and reports limits; it never decides
+ * permission. Linux uses bubblewrap and macOS sandbox-exec when present; Windows v1 is
+ * `policy-only` (partial): writes are checked by the gateway at action time and the child runs
+ * with an explicit environment, piped stdio, timeout and tree kill. A failing probe is
+ * `unavailable` (fail closed).
+ */
+export interface SandboxProbeOptions {
+    readonly platform?: NodeJS.Platform;
+    /** Resolves true when the argv runs and exits 0; injectable so probes are testable without the tools. */
+    readonly succeeds?: (argv: readonly [string, ...string[]]) => Promise<boolean>;
+    readonly fileExists?: (path: string) => Promise<boolean>;
+}
+export declare function probeSandbox(options?: SandboxProbeOptions): Promise<SandboxReport>;
+export interface SandboxRunnerOptions {
+    /** Roots whose PATH entries never resolve a program (the session workspace, the Synorch home); each spec may add more. */
+    readonly untrustedRoots?: readonly string[];
+}
+export declare function createSandboxRunner(report: SandboxReport, options?: SandboxRunnerOptions): SandboxRunner;
+/** The argv actually spawned: the command itself, wrapped by the backend when one enforces limits. */
+export declare function sandboxedArgv(report: SandboxReport, spec: ProcessSpec): readonly [string, ...string[]];
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/harness/tools/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../../src/harness/tools/sandbox.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,aAAa,EACnB,MAAM,uBAAuB,CAAC;AAG/B;;;;;;GAMG;AAEH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IACpC,yGAAyG;IACzG,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/E,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1D;AAID,wBAAsB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,aAAa,CAAC,CAuB5F;AAED,MAAM,WAAW,oBAAoB;IACnC,0HAA0H;IAC1H,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,GAAE,oBAAyB,GAAG,aAAa,CAmB5G;AAED,sGAAsG;AACtG,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,WAAW,GAAG,SAAS,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,CA4BtG"}

package/dist/harness/tools/sandbox.js

@@ -0,0 +1,117 @@
+import { spawn } from "node:child_process";
+import { access } from "node:fs/promises";
+import { sandboxReportSchema, } from "../contracts/index.js";
+import { runProcess, startProcess } from "./process.js";
+const SANDBOX_EXEC = "/usr/bin/sandbox-exec";
+export async function probeSandbox(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const reported = reportPlatform(platform);
+    const succeeds = options.succeeds ?? commandSucceeds;
+    const fileExists = options.fileExists ?? pathExists;
+    try {
+        if (platform === "linux") {
+            if (await succeeds(["bwrap", "--ro-bind", "/", "/", "--unshare-all", "--", "true"]))
+                return fullReport("bubblewrap", reported);
+            return policyOnlyReport(reported, "bubblewrap is not installed or cannot create namespaces; writes are checked by the gateway only");
+        }
+        if (platform === "darwin") {
+            if ((await fileExists(SANDBOX_EXEC)) && (await succeeds([SANDBOX_EXEC, "-p", "(version 1)(allow default)", "/usr/bin/true"]))) {
+                return fullReport("sandbox-exec", reported);
+            }
+            return policyOnlyReport(reported, "sandbox-exec is unavailable; writes are checked by the gateway only");
+        }
+        if (platform === "win32") {
+            return policyOnlyReport(reported, "no OS filesystem sandbox on Windows in v1; writes are checked by the gateway at action time");
+        }
+        return unavailableReport(reported, `no sandbox backend for platform ${platform}`);
+    }
+    catch (error) {
+        return unavailableReport(reported, `sandbox probe failed: ${error instanceof Error ? error.message : String(error)}`.slice(0, 500));
+    }
+}
+export function createSandboxRunner(report, options = {}) {
+    const checked = sandboxReportSchema.parse(report);
+    return {
+        probe: async () => checked,
+        run: async (spec, signal) => {
+            const untrustedRoots = [...(options.untrustedRoots ?? []), ...(spec.untrustedRoots ?? [])];
+            const result = await runProcess(sandboxedArgv(checked, spec), { cwd: spec.cwd, env: spec.env, stdin: spec.stdin, timeoutMs: spec.timeoutMs, outputLimitBytes: spec.outputLimitBytes, untrustedRoots }, signal);
+            const stderr = result.termination === "spawn-failed" && result.stderr.length === 0 ? `failed to start ${spec.argv[0]}: ${result.spawnError ?? "unknown error"}` : result.stderr;
+            return { ...result, stderr };
+        },
+        start: (spec) => {
+            const untrustedRoots = [...(options.untrustedRoots ?? []), ...(spec.untrustedRoots ?? [])];
+            return startProcess(sandboxedArgv(checked, spec), { cwd: spec.cwd, env: spec.env, stdin: spec.stdin, timeoutMs: spec.timeoutMs, outputLimitBytes: spec.outputLimitBytes, untrustedRoots });
+        },
+    };
+}
+/** The argv actually spawned: the command itself, wrapped by the backend when one enforces limits. */
+export function sandboxedArgv(report, spec) {
+    if (report.enforcement === "full" && report.backend === "bubblewrap") {
+        return [
+            "bwrap",
+            "--ro-bind",
+            "/",
+            "/",
+            "--dev",
+            "/dev",
+            "--proc",
+            "/proc",
+            "--tmpfs",
+            "/tmp",
+            ...spec.writeRoots.flatMap((root) => ["--bind", root, root]),
+            "--unshare-all",
+            ...(spec.network === "allow" ? ["--share-net"] : []),
+            "--die-with-parent",
+            "--new-session",
+            "--chdir",
+            spec.cwd,
+            "--",
+            ...spec.argv,
+        ];
+    }
+    if (report.enforcement === "full" && report.backend === "sandbox-exec") {
+        return [SANDBOX_EXEC, "-p", sandboxExecProfile(spec), ...spec.argv];
+    }
+    return spec.argv;
+}
+function sandboxExecProfile(spec) {
+    const quote = (value) => `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+    const writable = [
+        ...spec.writeRoots.map((root) => `(subpath ${quote(root)})`),
+        '(subpath "/private/tmp")',
+        '(subpath "/private/var/folders")',
+        '(literal "/dev/null")',
+        '(literal "/dev/tty")',
+    ].join(" ");
+    return `(version 1)(allow default)(deny file-write*)(allow file-write* ${writable})${spec.network === "deny" ? "(deny network*)" : ""}`;
+}
+function fullReport(backend, platform) {
+    return { backend, platform, enforcement: "full", filesystem: "full", network: "full", process: "full", notes: [] };
+}
+function policyOnlyReport(platform, note) {
+    return { backend: "policy-only", platform, enforcement: "partial", filesystem: "partial", network: "unavailable", process: "partial", notes: [note] };
+}
+function unavailableReport(platform, note) {
+    return { backend: "none", platform, enforcement: "unavailable", filesystem: "unavailable", network: "unavailable", process: "unavailable", notes: [note] };
+}
+function reportPlatform(platform) {
+    return platform === "win32" || platform === "darwin" || platform === "linux" ? platform : "other";
+}
+function commandSucceeds(argv) {
+    return new Promise((resolve) => {
+        const child = spawn(argv[0], argv.slice(1), { stdio: "ignore", windowsHide: true, timeout: 5_000 });
+        child.on("error", () => resolve(false));
+        child.on("close", (code) => resolve(code === 0));
+    });
+}
+async function pathExists(target) {
+    try {
+        await access(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=sandbox.js.map