@webpresso/agent-kit 3.3.1 → 3.3.2

package/dist/esm/review/execution/sandbox/policy.js

@@ -0,0 +1,95 @@
+import { readdirSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * srt always unions these host-global persistent paths into any custom policy
+ * and redirects the child `TMPDIR` to `/tmp/claude`. They are shared across
+ * concurrent runs (a corruption surface), so we deny them: `denyWrite` takes
+ * precedence over `allowWrite`, removing them from the child's writable set.
+ * The child's `TMPDIR` is redirected into the per-run dir via
+ * `CLAUDE_CODE_TMPDIR` (see `withSandboxTmpdir`).
+ */
+const SRT_DEFAULT_WRITABLE_DENY = [
+    "/tmp/claude",
+    "/private/tmp/claude",
+    "~/.npm/_logs",
+    "~/.claude/debug",
+];
+/**
+ * Defense-in-depth credential-store read denies (srt expands `~`). Reads
+ * elsewhere stay allowed (default srt semantics); network-deny is the hard
+ * exfiltration barrier. The caller repo root and the pnpm store are
+ * deliberately NOT denied — the reconstruction and the gate toolchain must read
+ * dependencies from them.
+ */
+const CREDENTIAL_DENY_READ = [
+    "~/.ssh",
+    "~/.aws",
+    "~/.netrc",
+    "~/.npmrc",
+    "~/.docker",
+    "~/.kube",
+    "~/.azure",
+    "~/.gnupg",
+    "~/.config/gh",
+    "~/.config/gcloud",
+];
+/**
+ * Common `.env*` names denied under the caller root even if the directory
+ * cannot be enumerated. srt takes no globs, so `callerEnvDenyReads` expands the
+ * real `.env*` set at build time; this is only the fallback floor.
+ */
+const CALLER_ENV_FILES = [
+    ".env",
+    ".env.local",
+    ".env.development",
+    ".env.production",
+    ".env.test",
+];
+// Literally `.env*`: `.env`, `.env.local`, but ALSO `.envrc`, `.environment`,
+// and any other secret-bearing name that begins `.env`.
+const ENV_FILE_PATTERN = /^\.env/u;
+/**
+ * Deny-read every `.env*` file actually present in the caller root — not just a
+ * literal five — because a hostile gate could otherwise read `.env.staging`,
+ * `.env.secret`, `.env.production.local`, etc. Both the lexical path and (for a
+ * symlinked secret) its realpath target are denied. Falls back to the common
+ * literal set if the caller root cannot be listed.
+ */
+function callerEnvDenyReads(projectRoot) {
+    const denied = new Set(CALLER_ENV_FILES.map((file) => join(projectRoot, file)));
+    try {
+        for (const entry of readdirSync(projectRoot, { withFileTypes: true })) {
+            if (!ENV_FILE_PATTERN.test(entry.name))
+                continue;
+            const lexical = join(projectRoot, entry.name);
+            denied.add(lexical);
+            try {
+                denied.add(realpathSync(lexical));
+            }
+            catch {
+                // Broken/unreadable link — the lexical deny still applies.
+            }
+        }
+    }
+    catch {
+        // Caller root not enumerable — the literal fallback floor still applies.
+    }
+    return [...denied];
+}
+/**
+ * Builds the srt filesystem/network policy for one gate: writes confined to the
+ * checkout + per-run tmp + the shared per-process scratch dir; the checkout
+ * `.git` and srt's default-writable set denied; network fully denied.
+ */
+export function buildGateSandboxConfig(policy) {
+    return {
+        network: { allowedDomains: [], deniedDomains: [] },
+        filesystem: {
+            // The per-run sandbox temp dir (CLAUDE_CODE_TMPDIR) lives under runTmpDir,
+            // so allowing the run dir covers it — no process-global shared scratch.
+            allowWrite: [policy.checkoutRoot, policy.runTmpDir],
+            denyWrite: [join(policy.checkoutRoot, ".git"), ...SRT_DEFAULT_WRITABLE_DENY],
+            denyRead: [...CREDENTIAL_DENY_READ, ...callerEnvDenyReads(policy.projectRoot)],
+        },
+    };
+}

package/dist/esm/review/execution/sandbox/probe.d.ts

@@ -0,0 +1,20 @@
+import { spawnSync } from "node:child_process";
+import { type SrtModule } from "#review/execution/sandbox/adapter.js";
+import type { SandboxAvailability } from "#review/execution/sandbox/types.js";
+export type ProbeOptions = {
+    readonly platform?: NodeJS.Platform;
+    readonly loadSrtModule?: () => Promise<SrtModule>;
+    readonly spawn?: typeof spawnSync;
+};
+/**
+ * Probes the host for a usable OS sandbox backend. Fail-closed: any missing
+ * prerequisite yields `{ kind: "none", reason }` with operator remediation —
+ * never a silent unsandboxed pass. Memoized per process unless `options` are
+ * supplied (tests). Order: platform gate → srt resolvable → srt platform
+ * support → dependency check → a real smoke-run of a wrapped `/usr/bin/true`
+ * (catches the Ubuntu 24.04 AppArmor userns restriction that the dependency
+ * check cannot see), with `cleanupAfterCommand` in a `finally`.
+ */
+export declare function resolveSandboxAvailability(options?: ProbeOptions): Promise<SandboxAvailability>;
+/** Test-only: clears the per-process memo. */
+export declare function resetSandboxAvailabilityCache(): void;

package/dist/esm/review/execution/sandbox/probe.js

@@ -0,0 +1,97 @@
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { loadSrt } from "#review/execution/sandbox/adapter.js";
+import { buildGateSandboxConfig } from "#review/execution/sandbox/policy.js";
+import { withSandboxTmpdir } from "#review/execution/sandbox/tmpdir.js";
+const LINUX_REMEDIATION = "install bubblewrap, socat, and ripgrep, and (on Ubuntu 24.04+) allow unprivileged user namespaces: `sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0`";
+const MODULE_REMEDIATION = "run `wp review` from the source or an installed runtime (not the bun-compiled binary), where @anthropic-ai/sandbox-runtime resolves";
+const OVERRIDE_NOTE = "or set WP_REVIEW_UNSANDBOXED_GATES=1 to run gates unsandboxed (recorded as disabled-by-operator)";
+let cached;
+/**
+ * Probes the host for a usable OS sandbox backend. Fail-closed: any missing
+ * prerequisite yields `{ kind: "none", reason }` with operator remediation —
+ * never a silent unsandboxed pass. Memoized per process unless `options` are
+ * supplied (tests). Order: platform gate → srt resolvable → srt platform
+ * support → dependency check → a real smoke-run of a wrapped `/usr/bin/true`
+ * (catches the Ubuntu 24.04 AppArmor userns restriction that the dependency
+ * check cannot see), with `cleanupAfterCommand` in a `finally`.
+ */
+export async function resolveSandboxAvailability(options) {
+    if (options === undefined && cached !== undefined)
+        return cached;
+    const result = await probe(options);
+    if (options === undefined)
+        cached = result;
+    return result;
+}
+/** Test-only: clears the per-process memo. */
+export function resetSandboxAvailabilityCache() {
+    cached = undefined;
+}
+async function probe(options) {
+    const platform = options?.platform ?? process.platform;
+    if (platform !== "darwin" && platform !== "linux") {
+        return none(`OS sandbox is only supported on macOS and Linux (host platform: ${platform}); ${OVERRIDE_NOTE}`);
+    }
+    let srt;
+    try {
+        srt = options?.loadSrtModule ? await options.loadSrtModule() : await loadSrt();
+    }
+    catch (error) {
+        return none(`@anthropic-ai/sandbox-runtime is not loadable (${describe(error)}); ${MODULE_REMEDIATION}, ${OVERRIDE_NOTE}`);
+    }
+    const { SandboxManager } = srt;
+    if (!SandboxManager.isSupportedPlatform()) {
+        return none(`the sandbox runtime reports this platform unsupported; ${OVERRIDE_NOTE}`);
+    }
+    const deps = SandboxManager.checkDependencies();
+    if (deps.errors.length > 0) {
+        return none(`sandbox dependencies missing (${deps.errors.join("; ")}); ${LINUX_REMEDIATION}, ${OVERRIDE_NOTE}`);
+    }
+    return smokeTest(SandboxManager, options?.spawn ?? spawnSync);
+}
+async function smokeTest(manager, spawn) {
+    const dir = realpathSync(mkdtempSync(join(tmpdir(), "wp-sandbox-probe-")));
+    const outcome = await runSmoke(manager, spawn, dir);
+    // Cleanup is part of the backend's health: if it cannot balance its own
+    // active-sandbox counter / mounts, the backend is NOT usable. Fail the probe
+    // (kind: none) rather than caching a leaky backend that silently litters.
+    let result = outcome;
+    try {
+        await manager.cleanupAfterCommand();
+    }
+    catch (error) {
+        result = none(`the sandbox backend cleanup did not complete (${describe(error)}); ${OVERRIDE_NOTE}`);
+    }
+    rmSync(dir, { recursive: true, force: true });
+    return result;
+}
+async function runSmoke(manager, spawn, dir) {
+    try {
+        const config = buildGateSandboxConfig({
+            checkoutRoot: dir,
+            runTmpDir: dir,
+            projectRoot: dir,
+        });
+        const wrapped = await withSandboxTmpdir(dir, () => manager.wrapWithSandboxArgv("/usr/bin/true", undefined, config));
+        const [command, ...args] = wrapped.argv;
+        if (command === undefined)
+            return none("sandbox wrap returned an empty argv during the probe");
+        const result = spawn(command, args, { timeout: 10_000, stdio: "ignore" });
+        if (result.error || result.status !== 0) {
+            return none(`the sandbox smoke-run failed (exit ${result.status ?? "null"}${result.error ? `, ${result.error.message}` : ""}); ${LINUX_REMEDIATION}, ${OVERRIDE_NOTE}`);
+        }
+        return { kind: "srt" };
+    }
+    catch (error) {
+        return none(`the sandbox smoke-run threw (${describe(error)}); ${OVERRIDE_NOTE}`);
+    }
+}
+function none(reason) {
+    return { kind: "none", reason };
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/esm/review/execution/sandbox/shell-quote.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Lossless POSIX shell serialization of a structured argv.
+ *
+ * `SandboxManager.wrapWithSandboxArgv` accepts a command *string* and returns a
+ * `shell -c <string>` wrapper, but the verifier owns a structured argv. Naively
+ * joining with spaces would let a shell-significant character in an argument
+ * (space, quote, glob, `#`, `$`, backtick, newline) change the command's
+ * meaning after wrapping. Single-quote wrapping makes every byte literal — the
+ * only escape needed is the single quote itself, closed and reopened around an
+ * escaped literal quote (`'\''`). This round-trips byte-identically even
+ * through srt's nested `bash -c "... sh -c '<here>'"` wrapping.
+ */
+export declare function shellQuoteArg(arg: string): string;
+export declare function shellQuoteArgv(argv: readonly string[]): string;

package/dist/esm/review/execution/sandbox/shell-quote.js

@@ -0,0 +1,18 @@
+/**
+ * Lossless POSIX shell serialization of a structured argv.
+ *
+ * `SandboxManager.wrapWithSandboxArgv` accepts a command *string* and returns a
+ * `shell -c <string>` wrapper, but the verifier owns a structured argv. Naively
+ * joining with spaces would let a shell-significant character in an argument
+ * (space, quote, glob, `#`, `$`, backtick, newline) change the command's
+ * meaning after wrapping. Single-quote wrapping makes every byte literal — the
+ * only escape needed is the single quote itself, closed and reopened around an
+ * escaped literal quote (`'\''`). This round-trips byte-identically even
+ * through srt's nested `bash -c "... sh -c '<here>'"` wrapping.
+ */
+export function shellQuoteArg(arg) {
+    return `'${arg.replace(/'/gu, "'\\''")}'`;
+}
+export function shellQuoteArgv(argv) {
+    return argv.map(shellQuoteArg).join(" ");
+}

package/dist/esm/review/execution/sandbox/tmpdir.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Runs `fn` (a wrap call) with `process.env.CLAUDE_CODE_TMPDIR` pointed at a
+ * PER-RUN sandbox temp dir under the verification's disposable `runTmpDir`,
+ * serialized against other callers and restored afterward. srt redirects the
+ * sandboxed child's TMPDIR here, so temp writes land in the caller's own
+ * disposable tree — never a process-global shared dir another review in the same
+ * process could read, modify, or recover.
+ */
+export declare function withSandboxTmpdir<T>(runTmpDir: string, fn: () => Promise<T>): Promise<T>;

package/dist/esm/review/execution/sandbox/tmpdir.js

@@ -0,0 +1,36 @@
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+// Serializes the brief window in which CLAUDE_CODE_TMPDIR is set process-wide.
+// srt reads that variable from the environment when it bakes the sandboxed
+// child's TMPDIR into the wrapped argv, so two concurrent wraps must not clobber
+// each other's value. Only the (fast, synchronous-ish) wrap call is serialized;
+// the actual gate execution runs outside this mutex with the value already baked
+// into its argv.
+let sandboxTmpdirChain = Promise.resolve();
+/**
+ * Runs `fn` (a wrap call) with `process.env.CLAUDE_CODE_TMPDIR` pointed at a
+ * PER-RUN sandbox temp dir under the verification's disposable `runTmpDir`,
+ * serialized against other callers and restored afterward. srt redirects the
+ * sandboxed child's TMPDIR here, so temp writes land in the caller's own
+ * disposable tree — never a process-global shared dir another review in the same
+ * process could read, modify, or recover.
+ */
+export function withSandboxTmpdir(runTmpDir, fn) {
+    const dir = join(runTmpDir, "sandbox-tmp");
+    mkdirSync(dir, { recursive: true });
+    const run = sandboxTmpdirChain.then(async () => {
+        const previous = process.env["CLAUDE_CODE_TMPDIR"];
+        process.env["CLAUDE_CODE_TMPDIR"] = dir;
+        try {
+            return await fn();
+        }
+        finally {
+            if (previous === undefined)
+                delete process.env["CLAUDE_CODE_TMPDIR"];
+            else
+                process.env["CLAUDE_CODE_TMPDIR"] = previous;
+        }
+    });
+    sandboxTmpdirChain = run.then(() => undefined, () => undefined);
+    return run;
+}

package/dist/esm/review/execution/sandbox/types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * OS-sandbox contract for the delivery-review verifier's untrusted gate
+ * execution. Backed by @anthropic-ai/sandbox-runtime (Seatbelt on macOS,
+ * bubblewrap on Linux) via the no-initialize wrap pattern.
+ */
+/** Result of probing the host for a usable OS sandbox backend. */
+export type SandboxAvailability = {
+    readonly kind: "srt";
+} | {
+    readonly kind: "none";
+    readonly reason: string;
+};
+/**
+ * Per-verification inputs the sandbox policy is built from. All paths are
+ * realpath-resolved by the caller so srt does not silently drop
+ * boundary-crossing symlink entries on Linux.
+ */
+export type GateSandboxPolicy = {
+    /** The disposable review checkout root (realpath'd). Writable. */
+    readonly checkoutRoot: string;
+    /** A per-run scratch dir outside the checkout (realpath'd). Writable. */
+    readonly runTmpDir: string;
+    /** The caller repository root, used to derive `.env*` read-denies. */
+    readonly projectRoot: string;
+};
+/** A concrete spawnable invocation (post-sandbox-wrap). */
+export type SandboxedInvocation = {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly env: NodeJS.ProcessEnv;
+};

package/dist/esm/review/execution/sandbox/types.js

@@ -0,0 +1,6 @@
+/**
+ * OS-sandbox contract for the delivery-review verifier's untrusted gate
+ * execution. Backed by @anthropic-ai/sandbox-runtime (Seatbelt on macOS,
+ * bubblewrap on Linux) via the no-initialize wrap pattern.
+ */
+export {};

package/dist/esm/review/execution/supervisor.js

@@ -126,11 +126,23 @@ export async function superviseReviewExecution(input, adapter, deps = {}) {
     const droppedEventWarnings = [];
     const recordDroppedProviderEvent = (reason) => {
         droppedEventWarnings.push(reason);
+        if (reason.startsWith("provider-event-too-large")) {
+            oversizedEventsSkipped += 1;
+        }
     };
     const decoder = new StringDecoder("utf8");
     const diagnosticDecoder = new StringDecoder("utf8");
     let buffered = "";
     let diagnosticBuffered = "";
+    // When a single NDJSON event exceeds MAX_PROVIDER_EVENT_BYTES we DROP that one
+    // event (bounding memory) and keep processing toward the terminal verdict,
+    // rather than discarding an otherwise-complete review. A reviewer that reads a
+    // large file (e.g. a big lockfile) legitimately emits one oversized tool event;
+    // that must not sink the whole review. These flags skip the remainder of an
+    // oversized line up to its next newline.
+    let skippingOversizedEvent = false;
+    let skippingOversizedDiagnostic = false;
+    let oversizedEventsSkipped = 0;
     let finalized = false;
     let terminationPromise;
     let resolveSummary;
@@ -332,20 +344,34 @@ export async function superviseReviewExecution(input, adapter, deps = {}) {
         }
     };
     const consume = (chunk) => {
-        buffered += decoder.write(chunk);
+        if (status !== null)
+            return;
+        let text = decoder.write(chunk);
+        if (skippingOversizedEvent) {
+            const newline = text.indexOf("\n");
+            if (newline === -1)
+                return; // still inside the oversized event; drop this chunk
+            skippingOversizedEvent = false;
+            text = text.slice(newline + 1); // resume after the oversized event's newline
+        }
+        buffered += text;
         const lines = buffered.split("\n");
         buffered = lines.pop() ?? "";
         for (const line of lines)
             processLine(line);
         if (status === null && Buffer.byteLength(buffered, "utf8") > MAX_PROVIDER_EVENT_BYTES) {
-            fail("protocol-unsupported", "provider-event-too-large");
+            // An in-progress event already exceeds the bound: drop the rest of it (skip
+            // to its next newline) instead of discarding the whole review.
+            buffered = "";
+            skippingOversizedEvent = true;
+            oversizedEventsSkipped += 1;
         }
     };
     const processDiagnosticLine = (line) => {
         if (line.trim().length === 0 || status !== null || !adapter.parseDiagnostic)
             return;
         if (Buffer.byteLength(line, "utf8") > MAX_PROVIDER_EVENT_BYTES) {
-            fail("protocol-unsupported", "provider-diagnostic-too-large");
+            oversizedEventsSkipped += 1;
             return;
         }
         const event = adapter.parseDiagnostic(line);
@@ -358,14 +384,26 @@ export async function superviseReviewExecution(input, adapter, deps = {}) {
         }
     };
     const consumeDiagnostic = (chunk) => {
-        diagnosticBuffered += diagnosticDecoder.write(chunk);
+        if (status !== null)
+            return;
+        let text = diagnosticDecoder.write(chunk);
+        if (skippingOversizedDiagnostic) {
+            const newline = text.indexOf("\n");
+            if (newline === -1)
+                return;
+            skippingOversizedDiagnostic = false;
+            text = text.slice(newline + 1);
+        }
+        diagnosticBuffered += text;
         const lines = diagnosticBuffered.split("\n");
         diagnosticBuffered = lines.pop() ?? "";
         for (const line of lines)
             processDiagnosticLine(line);
         if (status === null &&
             Buffer.byteLength(diagnosticBuffered, "utf8") > MAX_PROVIDER_EVENT_BYTES) {
-            fail("protocol-unsupported", "provider-diagnostic-too-large");
+            diagnosticBuffered = "";
+            skippingOversizedDiagnostic = true;
+            oversizedEventsSkipped += 1;
         }
     };
     const summaryPromise = new Promise((resolve) => {
@@ -451,6 +489,7 @@ export async function superviseReviewExecution(input, adapter, deps = {}) {
             finishedAt: now().toISOString(),
             lastProgressAt: lastProgressAt.toISOString(),
             semanticProgressCount,
+            ...(oversizedEventsSkipped > 0 ? { oversizedEventsSkipped } : {}),
             exitCode,
             markerMatched,
             ...(result === undefined ? {} : { result }),

package/dist/esm/review/execution/types.d.ts

@@ -73,6 +73,8 @@ export interface ReviewRunSummary {
     readonly finishedAt: string;
     readonly lastProgressAt: string;
     readonly semanticProgressCount: number;
+    /** Count of single provider/diagnostic events dropped for exceeding the byte bound. */
+    readonly oversizedEventsSkipped?: number;
     readonly exitCode: number | null;
     readonly markerMatched: boolean | null;
     readonly result?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpresso/agent-kit",
-  "version": "3.3.1",
+  "version": "3.3.2",
   "private": false,
   "description": "TypeScript-first agent harness for guarded develop/deploy workflows: wp CLI gates, MCP tools, hooks, memory, worktrees, secrets, audits, and evidence checks.",
   "keywords": [
@@ -430,6 +430,7 @@
     "desktop:build": "pnpm --filter @webpresso/desktop exec tsc --noEmit && pnpm --filter @webpresso/desktop exec vite build"
   },
   "dependencies": {
+    "@anthropic-ai/sandbox-runtime": "0.0.67",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@secretlint/secretlint-rule-preset-recommend": "^13.0.2",
     "@typescript/typescript6": "^6.0.2",
@@ -507,16 +508,16 @@
     "setupWpActionRef": "c2c71a7a4be446fc6858e6b57bf55a11ccfa2d88"
   },
   "optionalDependencies": {
-    "@webpresso/agent-kit-runtime-darwin-arm64": "3.3.1",
-    "@webpresso/agent-kit-runtime-darwin-x64": "3.3.1",
-    "@webpresso/agent-kit-runtime-linux-x64": "3.3.1",
-    "@webpresso/agent-kit-runtime-linux-arm64": "3.3.1",
-    "@webpresso/agent-kit-runtime-windows-x64": "3.3.1",
-    "@webpresso/agent-kit-session-memory-darwin-x64": "3.3.1",
-    "@webpresso/agent-kit-session-memory-darwin-arm64": "3.3.1",
-    "@webpresso/agent-kit-session-memory-linux-x64": "3.3.1",
-    "@webpresso/agent-kit-session-memory-linux-arm64": "3.3.1",
-    "@webpresso/agent-kit-session-memory-win32-x64": "3.3.1",
-    "@webpresso/agent-kit-session-memory-win32-arm64": "3.3.1"
+    "@webpresso/agent-kit-runtime-darwin-arm64": "3.3.2",
+    "@webpresso/agent-kit-runtime-darwin-x64": "3.3.2",
+    "@webpresso/agent-kit-runtime-linux-x64": "3.3.2",
+    "@webpresso/agent-kit-runtime-linux-arm64": "3.3.2",
+    "@webpresso/agent-kit-runtime-windows-x64": "3.3.2",
+    "@webpresso/agent-kit-session-memory-darwin-x64": "3.3.2",
+    "@webpresso/agent-kit-session-memory-darwin-arm64": "3.3.2",
+    "@webpresso/agent-kit-session-memory-linux-x64": "3.3.2",
+    "@webpresso/agent-kit-session-memory-linux-arm64": "3.3.2",
+    "@webpresso/agent-kit-session-memory-win32-x64": "3.3.2",
+    "@webpresso/agent-kit-session-memory-win32-arm64": "3.3.2"
   }
 }