jeo-code 0.12.13 → 0.12.16

package/src/agent/sandbox/hands-worker.ts

@@ -0,0 +1,168 @@
+import type { Subprocess } from "bun";
+import * as path from "node:path";
+import { DEFAULT_TOOLS } from "../engine";
+import type { ToolHandler } from "../engine";
+import { executeComputerAction } from "../../commands/computer";
+import { computerSupervisor } from "../computer-supervisor";
+import { assertBashAllowed } from "../tools";
+import { JobRegistry } from "../job-registry";
+import { MonitorRegistry } from "../monitor-registry";
+import { createJobTool } from "../job-tool";
+import { createMonitorTool } from "../monitor-tool";
+import { createGoalTool } from "../goal-tool";
+import { createApproveTool } from "../approve-tool";
+import { createWorkflowStateTool } from "../state";
+import type { ToolResult } from "../tools";
+import { encodeHandsFrame, MAX_FRAME_BYTES, parseHandsRequest, parseHandsResponse, readHandsFrames } from "./rpc";
+import type { SandboxExecResult } from "./types";
+
+// This kernel is not a sandbox. Its process and every descendant live INSIDE the OS container.
+const EVAL_BOOTSTRAP = `
+import {createInterface} from "node:readline";
+const AsyncFunction = Object.getPrototypeOf(async function(){}).constructor;
+const format = value => typeof value === "string" ? value : (() => { try { return JSON.stringify(value) ?? String(value); } catch { return String(value); } })();
+for await (const line of createInterface({input:process.stdin,crlfDelay:Infinity})) {
+  const {id,code,cwd,limit} = JSON.parse(line);
+  const logs=[];
+  let bytes=0;
+  const log=(...values)=>{const text=values.map(format).join(" ");bytes+=Buffer.byteLength(text,"utf8")+1;if(bytes>limit)throw new Error("eval output size limit exceeded");logs.push(text);};
+  let result;
+  try {
+    process.chdir(cwd);
+    const value=await new AsyncFunction("log","print","display","console",code)(log,log,log,{log,info:log,warn:log,error:log,debug:log});
+    if(value!==undefined)log(value);
+    result={success:true,output:logs.join("\\n")||"(eval completed with no output)"};
+  } catch(error) {result={success:false,output:"",error:"eval failed: "+String(error?.message??error)};}
+  process.stdout.write(JSON.stringify({id,type:"result",result})+"\\n");
+}
+`;
+
+export interface HandsWorkerOptions {
+  input: ReadableStream<Uint8Array>;
+  output: (line: string) => void | Promise<void>;
+  cwd: string;
+}
+
+export async function runHandsWorker(options: HandsWorkerOptions): Promise<void> {
+  const jobs = new JobRegistry();
+  const monitors = new MonitorRegistry();
+  let kernel: { process: Subprocess<"pipe", "pipe", "pipe">; frames: AsyncGenerator<unknown> } | undefined;
+  const evaluate: ToolHandler = async (args, cwd): Promise<ToolResult> => {
+    if (typeof args.code !== "string" || !args.code.trim()) return { success: false, output: "", error: "eval requires a code body" };
+    try { await assertBashAllowed(cwd); }
+    catch (error) { return { success: false, output: "", error: String(error) }; }
+    if (!kernel || kernel.process.exitCode !== null) {
+      const child = Bun.spawn([process.execPath, "-e", EVAL_BOOTSTRAP], { cwd, env: { ...process.env }, stdin: "pipe", stdout: "pipe", stderr: "pipe" });
+      kernel = { process: child, frames: readHandsFrames(child.stdout) };
+      void (async () => {
+        const reader = child.stderr.getReader();
+        try { while (!(await reader.read()).done) { /* User stderr cannot create an unbounded parent buffer. */ } }
+        finally { reader.releaseLock(); }
+      })().catch(() => {});
+    }
+    const current = kernel;
+    const id = crypto.randomUUID();
+    const timeoutMs = typeof args.timeoutMs === "number" && Number.isFinite(args.timeoutMs) && args.timeoutMs > 0
+      ? Math.min(args.timeoutMs, 1_800_000) : 300_000;
+    const timeout = Promise.withResolvers<ToolResult>();
+    const timer = setTimeout(() => {
+      current.process.kill("SIGKILL");
+      if (kernel === current) kernel = undefined;
+      timeout.resolve({ success: false, output: "", error: "eval execution timed out" });
+    }, timeoutMs);
+    try {
+      // The outer request is byte-bounded already; this private child envelope adds trusted cwd metadata.
+      await current.process.stdin.write(`${JSON.stringify({ id, code: args.code, cwd, limit: Math.floor(MAX_FRAME_BYTES / 2) })}\n`);
+      await current.process.stdin.flush();
+      const response = (async (): Promise<ToolResult> => {
+        const frame = await current.frames.next();
+        if (frame.done) throw new Error("eval child closed without a result");
+        const parsed = parseHandsResponse(frame.value);
+        if (parsed.id !== id || parsed.type !== "result") throw new Error("eval child returned an invalid result identity");
+        return parsed.result;
+      })();
+      return await Promise.race([response, timeout.promise]);
+    } catch (error) {
+      current.process.kill("SIGKILL");
+      if (kernel === current) kernel = undefined;
+      return { success: false, output: "", error: `eval child failed: ${String(error)}` };
+    } finally { clearTimeout(timer); }
+  };
+  const tools: Record<string, ToolHandler> = {
+    ...DEFAULT_TOOLS,
+    eval: evaluate,
+    job: createJobTool(jobs),
+    monitor: createMonitorTool(monitors),
+    goal: createGoalTool(),
+    // Private (not a model tool): consent comes only from the trusted parent wrapper.
+    __computer: async (args): Promise<ToolResult> => {
+      if (typeof args.enabled !== "boolean") return { success: false, output: "", error: "__computer requires boolean enabled" };
+      if (!args.action || typeof args.action !== "object" || Array.isArray(args.action)) return { success: false, output: "", error: "Expected a computer action object." };
+      computerSupervisor.setKillSwitchLive(true);
+      computerSupervisor.heartbeat();
+      return executeComputerAction(args.action as any, { enabledOverride: args.enabled });
+    },
+    __plan_approve: createApproveTool(),
+    __workflow: createWorkflowStateTool(),
+  };
+  const output = async (id: string, result: SandboxExecResult): Promise<void> => {
+    let frame: string;
+    try { frame = encodeHandsFrame({ id, type: "result", result }); }
+    catch { frame = encodeHandsFrame({ id, type: "result", result: { success: false, output: "", error: "SANDBOX_PROTOCOL: tool output size limit exceeded", mutationMayHaveOccurred: true } }); }
+    await options.output(frame);
+  };
+
+  const exec = async (argv: string[], cwd: string, env?: Record<string, string>, stdin?: string): Promise<SandboxExecResult> => {
+    await assertBashAllowed(cwd);
+    const child = Bun.spawn(argv, { cwd, env: { ...process.env, ...env }, stdin: "pipe", stdout: "pipe", stderr: "pipe" });
+    const capture = async (stream: ReadableStream<Uint8Array>): Promise<string> => {
+      const reader = stream.getReader();
+      const chunks: Uint8Array[] = [];
+      let size = 0;
+      try {
+        for (;;) {
+          const chunk = await reader.read();
+          if (chunk.done) break;
+          size += chunk.value.byteLength;
+          if (size > Math.floor((MAX_FRAME_BYTES - 4096) / 4)) { child.kill(); throw new Error("sandbox exec output limit exceeded"); }
+          chunks.push(chunk.value);
+        }
+      } finally { reader.releaseLock(); }
+      return Buffer.concat(chunks).toString("utf8");
+    };
+    const reads = Promise.all([capture(child.stdout), capture(child.stderr), child.exited]);
+    if (stdin !== undefined) await child.stdin.write(stdin);
+    await child.stdin.end();
+    const [stdout, stderr, exitCode] = await reads;
+    return { success: exitCode === 0, output: `${stdout}${stderr}`, stdout, stderr, exitCode, timedOut: false, aborted: false, ...(exitCode !== 0 ? { error: `Command exited ${exitCode}`, mutationMayHaveOccurred: true } : {}) };
+  };
+
+  try {
+    for await (const frame of readHandsFrames(options.input)) {
+      const request = parseHandsRequest(frame);
+      let result: SandboxExecResult;
+      try {
+        if (request.type === "exec") {
+          result = await exec(request.argv, request.cwd ? path.resolve(options.cwd, request.cwd) : options.cwd, request.env, request.stdin);
+        } else if (!Object.hasOwn(tools, request.tool)) {
+          result = { success: false, output: "", error: `Unknown or unavailable hands tool: ${request.tool}` };
+        } else {
+          result = await tools[request.tool]!(request.args, request.cwd ? path.resolve(options.cwd, request.cwd) : options.cwd, partial => {
+            try { void options.output(encodeHandsFrame({ id: request.id, type: "progress", text: partial })); }
+            catch { /* The bounded final result reports oversized output; progress is cosmetic. */ }
+          });
+        }
+      } catch (error) { result = { success: false, output: "", error: String(error), mutationMayHaveOccurred: true }; }
+      await output(request.id, result);
+    }
+  } finally {
+    if (kernel) { kernel.process.kill("SIGKILL"); await kernel.process.exited; }
+    jobs.cancelAll();
+    monitors.cancelAll();
+  }
+}
+
+if (import.meta.main) {
+  if (process.env.JEO_SANDBOX_HANDS !== "1") throw new Error("Hands runtime requires its isolated backend");
+  await runHandsWorker({ input: Bun.stdin.stream(), output: line => { process.stdout.write(line); }, cwd: process.cwd() });
+}

package/src/agent/sandbox/policy.ts

@@ -0,0 +1,172 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { SandboxConfig, SandboxMount, SandboxPolicy } from "./types";
+
+export interface SandboxPolicyOptions {
+  sessionKey: string;
+  revision: number;
+  cwd: string;
+  config: SandboxConfig;
+  grants?: readonly { host: string; mode: "ro" | "rw" }[];
+  privatePaths?: readonly string[];
+}
+
+export function validateSandboxConfig(value: SandboxConfig): void {
+  if (!value || typeof value.image !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.:/@-]*$/.test(value.image)) {
+    throw new Error("SANDBOX_CONFIG: an existing local image reference is required");
+  }
+  const limits = value.limits;
+  if (!limits || !Number.isSafeInteger(limits.memoryBytes) || limits.memoryBytes <= 0 ||
+      !Number.isSafeInteger(limits.pids) || limits.pids <= 0 ||
+      !Number.isFinite(limits.cpus) || limits.cpus <= 0) {
+    throw new Error("SANDBOX_CONFIG: positive finite memory, PID and CPU limits are required");
+  }
+}
+
+export function sandboxPathContains(parent: string, child: string): boolean {
+  const relative = path.relative(parent, child);
+  return relative === "" || (!path.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path.sep}`));
+}
+
+export function windowsSystemRoot(): string {
+  const configured = process.env.SystemRoot ?? process.env.SYSTEMROOT ?? process.env.windir;
+  if (configured && path.isAbsolute(configured)) return configured;
+  for (const candidate of ["powershell.exe", "cmd.exe"]) {
+    const resolved = Bun.which(candidate);
+    const match = resolved ? /^(.*)[\\/]System32(?:[\\/]|$)/i.exec(resolved) : null;
+    if (match?.[1] && path.isAbsolute(match[1])) return match[1];
+  }
+  throw new Error("SANDBOX_STATE: Windows system directory is unavailable");
+}
+
+let nativeHome: Promise<string> | undefined;
+
+/** Bun userInfo() can inherit startup HOME; query the native account database instead. */
+export function nativeSandboxHome(): Promise<string> {
+  nativeHome ??= (async () => {
+    let home: string | undefined;
+    let argv: string[] | undefined;
+    let systemRoot = "";
+    if (process.platform === "win32") {
+      systemRoot = windowsSystemRoot();
+      const script = "$ErrorActionPreference='Stop';[Console]::Out.Write([Environment]::GetFolderPath([Environment+SpecialFolder]::UserProfile))";
+      argv = [path.join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe"), "-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")];
+    } else {
+      const uid = process.getuid?.();
+      if (uid === undefined) throw new Error("SANDBOX_STATE: native user identity unavailable");
+      if (process.platform === "darwin") argv = ["/usr/bin/dscacheutil", "-q", "user", "-a", "uid", String(uid)];
+      else {
+        const entry = (await fs.readFile("/etc/passwd", "utf8")).split("\n").find(line => line.split(":")[2] === String(uid));
+        home = entry?.split(":")[5];
+        if (!home) argv = ["/usr/bin/getent", "passwd", String(uid)];
+      }
+    }
+    if (argv) {
+      const child = Bun.spawn(argv, { env: { SystemRoot: systemRoot }, stdin: "ignore", stdout: "pipe", stderr: "ignore" });
+      const timer = setTimeout(() => child.kill(), 30_000);
+      try {
+        const [code, output] = await Promise.all([child.exited, new Response(child.stdout).text()]);
+        if (code !== 0) throw new Error("SANDBOX_STATE: native account home lookup failed");
+        home = process.platform === "darwin" ? /^dir: (.+)$/m.exec(output)?.[1] : process.platform === "win32" ? output.trim() : output.trim().split(":")[5];
+      } finally { clearTimeout(timer); }
+    }
+    if (!home || !path.isAbsolute(home)) throw new Error("SANDBOX_STATE: native account home unavailable");
+    return canonicalSandboxPath(home);
+  })();
+  return nativeHome;
+}
+
+/** Canonicalize even a not-yet-created private state path without trusting symlinked ancestors. */
+export async function canonicalSandboxPath(value: string, mustExist = true, cwd?: string): Promise<string> {
+  if (typeof value !== "string" || !value.trim() || /[\0\r\n]/.test(value)) throw new Error("SANDBOX_PATH: invalid host path");
+  // Reject namespaces before normalization or metadata can contact SMB servers or devices.
+  if (process.platform === "win32" && /^(?:[\\/]{2}|[\\/]\?\?[\\/])/.test(value)) throw new Error("SANDBOX_PATH: Windows network and device paths are forbidden");
+  const absolute = cwd === undefined ? path.resolve(value) : path.resolve(cwd, value);
+  if (process.platform === "win32" && /^[\\/]{2}/.test(absolute)) throw new Error("SANDBOX_PATH: Windows network and device paths are forbidden");
+  try {
+    const resolved = await fs.realpath(absolute);
+    return process.platform === "win32" && /^[A-Za-z]:$/.test(resolved) ? `${resolved}\\` : resolved;
+  }
+  catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    // macOS realpath can reject launchd sockets even though their parent is resolvable.
+    const socket = code === "EOPNOTSUPP" && (await fs.lstat(absolute)).isSocket();
+    if (!socket && (mustExist || code !== "ENOENT")) throw error;
+    const parent = path.dirname(absolute);
+    if (parent === absolute) throw error;
+    const resolvedParent = await canonicalSandboxPath(parent, false);
+    const result = path.join(resolvedParent, path.basename(absolute));
+    return process.platform === "win32" && /^[A-Za-z]:$/.test(result) ? `${result}\\` : result;
+  }
+}
+
+/** Deny endpoint ancestors even when their socket has not been created yet. */
+export async function validateSandboxMountSource(host: string, privatePaths: readonly string[], controlPaths: readonly string[] = []): Promise<void> {
+  const home = await canonicalSandboxPath(os.homedir());
+  const isRoot = host === path.parse(host).root || (process.platform === "win32" && /^[A-Za-z]:[\\/]?$/.test(host));
+  if (isRoot || host === home) throw new Error("SANDBOX_POLICY: host root and whole-home mounts are forbidden");
+  if (privatePaths.some(privatePath => sandboxPathContains(host, privatePath) || sandboxPathContains(privatePath, host))) {
+    throw new Error("SANDBOX_POLICY: mount overlaps private control state");
+  }
+  const endpoints = [process.env.SSH_AUTH_SOCK, process.env.DOCKER_HOST?.startsWith("unix://") ? process.env.DOCKER_HOST.slice(7) : undefined, ...controlPaths].filter((value): value is string => Boolean(value));
+  for (const endpoint of endpoints) {
+    if (sandboxPathContains(host, await canonicalSandboxPath(endpoint, false))) throw new Error("SANDBOX_POLICY: mount exposes a control socket endpoint");
+  }
+  const pending = [host];
+  while (pending.length) {
+    const current = pending.pop()!;
+    const stat = await fs.lstat(current);
+    // Symlinks inside a bind resolve in the guest namespace, not the host namespace.
+    if (stat.isSymbolicLink()) continue;
+    if (stat.isSocket() || path.basename(current).toLowerCase() === "docker.sock") throw new Error("SANDBOX_POLICY: control sockets cannot be mounted");
+    if (stat.isDirectory()) {
+      for (const entry of await fs.readdir(current)) pending.push(path.join(current, entry));
+    } else if (!stat.isFile()) throw new Error("SANDBOX_POLICY: non-file resources cannot be mounted");
+  }
+}
+
+export async function createSandboxPolicy(options: SandboxPolicyOptions): Promise<SandboxPolicy> {
+  validateSandboxConfig(options.config);
+  if (!/^[A-Za-z0-9_-]{1,64}$/.test(options.sessionKey) || !Number.isSafeInteger(options.revision) || options.revision < 0) {
+    throw new Error("SANDBOX_POLICY: invalid session or revision");
+  }
+  const home = await canonicalSandboxPath(os.homedir());
+  const nativeHome = await nativeSandboxHome();
+  const privatePaths = await Promise.all([
+    ...[...new Set([home, nativeHome])].flatMap(root => [".jeo", ".jeopi", ".docker", ".gemini", ".ssh", ".claude", ".codex", ".agents", ".aws", ".azure", ".gnupg", ".config"].map(name => path.join(root, name))),
+    ...["JEO_CONFIG_DIR", "DOCKER_CONFIG", "XDG_CONFIG_HOME", "JEO_GEMINI_CREDS_PATH", "CODEX_HOME", "CLAUDE_CONFIG_DIR", "AWS_CONFIG_FILE", "AWS_SHARED_CREDENTIALS_FILE", "AZURE_CONFIG_DIR", "GNUPGHOME"].map(key => process.env[key]).filter((value): value is string => Boolean(value)),
+    ...(options.privatePaths ?? []),
+  ].map(value => canonicalSandboxPath(value, false)));
+  const mounts = new Map<string, SandboxMount>();
+  const workspace = await canonicalSandboxPath(options.cwd);
+  const resources = [{ host: workspace, mode: "rw" as const }, ...(options.grants ?? [])];
+  for (const resource of resources) {
+    if (resource.mode !== "ro" && resource.mode !== "rw") throw new Error("SANDBOX_POLICY: invalid access mode");
+    const host = await canonicalSandboxPath(resource.host);
+    await validateSandboxMountSource(host, privatePaths);
+    for (const existing of mounts.values()) {
+      if (existing.host !== host && (sandboxPathContains(existing.host, host) || sandboxPathContains(host, existing.host))) {
+        throw new Error("SANDBOX_MOUNT_OVERLAP: non-identical ancestor and descendant mount roots are forbidden");
+      }
+    }
+    const existing = mounts.get(host);
+    const mode = existing?.mode === "rw" ? "rw" : resource.mode;
+    const guest = host === workspace ? "/workspace" : `/grants/${new Bun.CryptoHasher("sha256").update(host).digest("hex")}`;
+    mounts.set(host, Object.freeze({ host, guest, mode }));
+  }
+  const ordered = [...mounts.values()].sort((a, b) => a.guest.localeCompare(b.guest));
+  const config = Object.freeze({ image: options.config.image, limits: Object.freeze({ ...options.config.limits }) });
+  const content = { sessionKey: options.sessionKey, revision: options.revision, mounts: ordered, config, privatePaths: Object.freeze(privatePaths) };
+  const digest = new Bun.CryptoHasher("sha256").update(JSON.stringify(content)).digest("hex");
+  return Object.freeze({ ...content, mounts: Object.freeze(ordered), digest });
+}
+
+export function sandboxGuestPath(policy: SandboxPolicy, hostPath: string): string {
+  const absolute = path.resolve(hostPath);
+  const mount = [...policy.mounts].sort((a, b) => b.host.length - a.host.length)
+    .find(candidate => sandboxPathContains(candidate.host, absolute));
+  if (!mount) throw new Error("SANDBOX_PATH: path has no approved mount");
+  const relative = path.relative(mount.host, absolute).split(path.sep).join("/");
+  return relative ? `${mount.guest}/${relative}` : mount.guest;
+}

package/src/agent/sandbox/rpc.ts

@@ -0,0 +1,90 @@
+import type { SandboxExecResult } from "./types";
+
+// Match the existing messenger worker transport bound, measured before UTF-8 decoding.
+export const MAX_FRAME_BYTES = 1_000_000;
+
+export type HandsRequest =
+  | { id: string; type: "tool"; tool: string; args: Record<string, unknown>; cwd?: string }
+  | { id: string; type: "exec"; argv: string[]; cwd?: string; env?: Record<string, string>; stdin?: string };
+export type HandsResponse =
+  | { id: string; type: "progress"; text: string }
+  | { id: string; type: "result"; result: SandboxExecResult };
+
+function record(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function encodeHandsFrame(value: unknown): string {
+  const text = JSON.stringify(value);
+  if (typeof text !== "string" || Buffer.byteLength(text, "utf8") > MAX_FRAME_BYTES) throw new Error("SANDBOX_PROTOCOL: frame size limit exceeded");
+  return `${text}\n`;
+}
+
+export async function* readHandsFrames(input: ReadableStream<Uint8Array>): AsyncGenerator<unknown> {
+  const reader = input.getReader();
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  let pieces: Uint8Array[] = [];
+  let size = 0;
+  try {
+    for (;;) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      let start = 0;
+      for (let index = 0; index <= chunk.value.byteLength; index++) {
+        const complete = index < chunk.value.byteLength && chunk.value[index] === 10;
+        if (!complete && index !== chunk.value.byteLength) continue;
+        const part = chunk.value.subarray(start, index);
+        size += part.byteLength;
+        if (size > MAX_FRAME_BYTES) throw new Error("SANDBOX_PROTOCOL: frame size limit exceeded");
+        if (part.byteLength) pieces.push(part);
+        if (complete) {
+          try { yield JSON.parse(decoder.decode(Buffer.concat(pieces, size))); }
+          catch (error) { throw new Error("SANDBOX_PROTOCOL: malformed JSON frame", { cause: error }); }
+          pieces = [];
+          size = 0;
+          start = index + 1;
+        }
+      }
+    }
+    if (size) throw new Error("SANDBOX_PROTOCOL: incomplete frame at EOF");
+  } finally { reader.releaseLock(); }
+}
+
+export function parseHandsRequest(value: unknown): HandsRequest {
+  if (!record(value) || typeof value.id !== "string" || !/^[A-Za-z0-9_-]{1,256}$/.test(value.id)) {
+    throw new Error("SANDBOX_PROTOCOL: invalid request identity");
+  }
+  if (value.type === "tool" && typeof value.tool === "string" && record(value.args) &&
+      (value.cwd === undefined || (typeof value.cwd === "string" && !value.cwd.includes("\0"))) &&
+      Object.keys(value).every(key => ["id", "type", "tool", "args", "cwd"].includes(key))) {
+    return { id: value.id, type: "tool", tool: value.tool, args: value.args, ...(value.cwd !== undefined ? { cwd: value.cwd } : {}) };
+  }
+  if (value.type === "exec" && Array.isArray(value.argv) && value.argv.length > 0 &&
+      value.argv.every(arg => typeof arg === "string" && !arg.includes("\0")) &&
+      (value.cwd === undefined || typeof value.cwd === "string") &&
+      (value.stdin === undefined || typeof value.stdin === "string") &&
+      (value.env === undefined || (record(value.env) && Object.values(value.env).every(item => typeof item === "string" && !item.includes("\0")))) &&
+      Object.keys(value).every(key => ["id", "type", "argv", "cwd", "env", "stdin"].includes(key))) {
+    return { id: value.id, type: "exec", argv: value.argv, ...(value.cwd !== undefined ? { cwd: value.cwd } : {}), ...(value.stdin !== undefined ? { stdin: value.stdin } : {}), ...(value.env !== undefined ? { env: value.env as Record<string, string> } : {}) };
+  }
+  throw new Error("SANDBOX_PROTOCOL: invalid request frame");
+}
+
+export function parseHandsResponse(value: unknown): HandsResponse {
+  if (!record(value) || typeof value.id !== "string" || !/^[A-Za-z0-9_-]{1,256}$/.test(value.id)) throw new Error("SANDBOX_PROTOCOL: invalid response identity");
+  if (value.type === "progress" && typeof value.text === "string" && Object.keys(value).every(key => ["id", "type", "text"].includes(key))) {
+    return { id: value.id, type: "progress", text: value.text };
+  }
+  const result = value.result;
+  if (value.type === "result" && record(result) && typeof result.success === "boolean" && typeof result.output === "string" &&
+      (result.error === undefined || typeof result.error === "string") &&
+      (result.mutationMayHaveOccurred === undefined || typeof result.mutationMayHaveOccurred === "boolean") &&
+      (result.images === undefined || (Array.isArray(result.images) && result.images.every(image => record(image) && typeof image.mediaType === "string" && /^image\/[a-zA-Z0-9.+-]+$/.test(image.mediaType) && typeof image.data === "string" && /^[A-Za-z0-9+/]*={0,2}$/.test(image.data)))) &&
+      ["stdout", "stderr"].every(key => result[key] === undefined || typeof result[key] === "string") &&
+      (result.exitCode === undefined || result.exitCode === null || Number.isInteger(result.exitCode)) &&
+      ["timedOut", "aborted"].every(key => result[key] === undefined || typeof result[key] === "boolean") &&
+      Object.keys(value).every(key => ["id", "type", "result"].includes(key))) {
+    return { id: value.id, type: "result", result: result as unknown as SandboxExecResult };
+  }
+  throw new Error("SANDBOX_PROTOCOL: invalid response frame");
+}

package/src/agent/sandbox/supervisor.ts

@@ -0,0 +1,210 @@
+import * as path from "node:path";
+import { createDockerBackend, SandboxLaunchError } from "./docker";
+import { prepareHandsBundle } from "./bundle";
+import { sandboxPathContains } from "./policy";
+import { encodeHandsFrame, parseHandsResponse, readHandsFrames } from "./rpc";
+import type { HandsRequest } from "./rpc";
+import type { ToolHandler } from "../engine";
+import type { ToolResult } from "../tools";
+import type { SandboxBackend, SandboxCallOptions, SandboxExecOptions, SandboxExecResult, SandboxPolicy, SandboxProcess, SandboxSupervisor, SandboxTermination } from "./types";
+
+interface PendingEffect {
+  request: HandsRequest;
+  frame: string;
+  settled: boolean;
+  result: PromiseWithResolvers<SandboxExecResult>;
+  progress?: (text: string) => void;
+  signal?: AbortSignal;
+  abort?: () => void;
+}
+
+export function createSandboxSupervisor(options: { policy: SandboxPolicy; backend?: SandboxBackend; bundlePath?: string }): SandboxSupervisor {
+  const backend = options.backend ?? createDockerBackend();
+  let policy = options.policy;
+  let state: "ready" | "changing" | "revoked" | "closed" | "failed" = "ready";
+  let reason = "";
+  let generation = 0;
+  let worker: SandboxProcess | undefined;
+  let launching: Promise<SandboxProcess> | undefined;
+  let launchFailure: Error | undefined;
+  let stopping: Promise<SandboxTermination> | undefined;
+  let active: PendingEffect | undefined;
+  let pumping = false;
+  const queue: PendingEffect[] = [];
+
+  function settle(effect: PendingEffect, result: SandboxExecResult): void {
+    if (effect.settled) return;
+    effect.settled = true;
+    if (effect.abort) effect.signal?.removeEventListener("abort", effect.abort);
+    effect.result.resolve(result);
+  }
+
+  function invalidate(message: string, next: typeof state): number {
+    state = state === "closed" ? "closed" : next;
+    reason = message;
+    generation++;
+    const failure = { success: false, output: "", error: message };
+    if (active) settle(active, failure);
+    for (const effect of queue.splice(0)) settle(effect, failure);
+    return generation;
+  }
+
+  function terminate(): Promise<SandboxTermination> {
+    if (stopping) return stopping;
+    const removal = (async (): Promise<SandboxTermination> => {
+      const owned = worker ?? (launching ? await launching.catch(() => undefined) : undefined);
+      const residual = owned ? [owned.name] : launchFailure instanceof SandboxLaunchError ? [...launchFailure.residual] : launchFailure ? [launchFailure.message] : [];
+      try {
+        const result = owned ? await owned.stop() : launchFailure instanceof SandboxLaunchError ? await launchFailure.cleanup() : launchFailure ? { gone: false, residual } : { gone: true, residual: [] };
+        if (!result.gone || result.residual.length) {
+          const remaining = result.residual.length ? [...result.residual] : residual;
+          invalidate(`REVOKE_INCOMPLETE: ${remaining.join(", ") || "launch cleanup remains unverified"}`, "failed");
+          return { gone: false, residual: remaining };
+        }
+        if (worker === owned) worker = undefined;
+        launchFailure = undefined;
+        return { gone: true, residual: [] };
+      } catch (error) {
+        invalidate(`REVOKE_INCOMPLETE: ${String(error)}`, "failed");
+        return { gone: false, residual: residual.length ? residual : [String(error)] };
+      }
+    })();
+    stopping = removal;
+    void removal.then(result => { if (!result.gone && stopping === removal) stopping = undefined; });
+    return removal;
+  }
+
+  function fail(error: unknown): void {
+    if (state !== "ready") return;
+    invalidate(String(error), "failed");
+    void terminate();
+  }
+
+  async function start(): Promise<SandboxProcess> {
+    if (worker) return worker;
+    if (launching) return launching;
+    const epoch = generation;
+    launching = (async () => {
+      const bundle = options.bundlePath ?? await prepareHandsBundle();
+      const process = await backend.launch(policy, bundle).catch(error => {
+        if (error instanceof SandboxLaunchError || (error instanceof Error && /REVOKE_INCOMPLETE/.test(error.message))) launchFailure = error;
+        throw error;
+      });
+      worker = process;
+      void (async () => {
+        try {
+          for await (const value of readHandsFrames(process.stdout)) {
+            if (generation !== epoch || state !== "ready") continue;
+            const response = parseHandsResponse(value);
+            const effect = active;
+            if (!effect || effect.settled || response.id !== effect.request.id) throw new Error("SANDBOX_PROTOCOL: unknown response correlation identity");
+            if (response.type === "result") settle(effect, response.result);
+            else { try { effect.progress?.(response.text); } catch { /* A UI progress callback is not authority. */ } }
+          }
+          if (generation === epoch) fail(new Error("SANDBOX_PROTOCOL: hands output closed"));
+        } catch (error) { if (generation === epoch) fail(error); }
+      })();
+      void (async () => {
+        const reader = process.stderr.getReader();
+        try { while (!(await reader.read()).done) { /* Drain diagnostics without an unbounded parent buffer. */ } }
+        catch (error) { if (generation === epoch) fail(error); }
+        finally { reader.releaseLock(); }
+      })();
+      void process.exited.then(() => {
+        if (generation === epoch) fail(new Error("SANDBOX_EXIT: hands runtime exited"));
+      }, error => { if (generation === epoch) fail(error); });
+      return process;
+    })();
+    try { return await launching; }
+    finally { launching = undefined; }
+  }
+
+  async function pump(): Promise<void> {
+    if (pumping) return;
+    pumping = true;
+    try {
+      while (state === "ready" && queue.length) {
+        const effect = queue.shift()!;
+        if (effect.settled) continue;
+        active = effect;
+        const epoch = generation;
+        try {
+          const process = await start();
+          if (state !== "ready" || generation !== epoch || effect.settled) continue;
+          await process.stdin.write(effect.frame);
+          await process.stdin.flush();
+          await effect.result.promise;
+        } catch (error) { fail(error); }
+        finally { if (active === effect) active = undefined; }
+      }
+    } finally { pumping = false; }
+  }
+
+  function enqueue(request: HandsRequest, callOptions: SandboxCallOptions = {}): Promise<SandboxExecResult> {
+    if (state !== "ready") return Promise.resolve({ success: false, output: "", error: reason || "SANDBOX_BLOCKED" });
+    if (callOptions.signal?.aborted) return Promise.resolve({ success: false, output: "", error: "SANDBOX_ABORTED: request cancelled" });
+    if (queue.length >= 100) return Promise.resolve({ success: false, output: "", error: "SANDBOX_QUEUE: capacity exceeded" });
+    let frame: string;
+    try { frame = encodeHandsFrame(request); }
+    catch (error) { return Promise.resolve({ success: false, output: "", error: String(error) }); }
+    const effect: PendingEffect = { request, frame, settled: false, result: Promise.withResolvers<SandboxExecResult>(), progress: callOptions.onProgress, signal: callOptions.signal };
+    effect.abort = () => {
+      if (effect.settled) return;
+      if (active !== effect) { settle(effect, { success: false, output: "", error: "SANDBOX_ABORTED: queued request cancelled" }); return; }
+      const epoch = invalidate("SANDBOX_ABORTED: active generation cancelled", "changing");
+      void terminate().then(result => {
+        if (result.gone && generation === epoch && state === "changing") { stopping = undefined; state = "ready"; reason = ""; }
+      });
+    };
+    effect.signal?.addEventListener("abort", effect.abort, { once: true });
+    queue.push(effect);
+    void pump();
+    return effect.result.promise;
+  }
+
+  function guestPath(value: string): string {
+    if (!path.isAbsolute(value)) return value;
+    const mount = [...policy.mounts].sort((a, b) => b.host.length - a.host.length).find(item => sandboxPathContains(item.host, value));
+    if (!mount) return value;
+    const relative = path.relative(mount.host, value).split(path.sep).join("/");
+    return relative ? `${mount.guest}/${relative}` : mount.guest;
+  }
+
+  function call(tool: string, args: Record<string, unknown>, callOptions?: SandboxCallOptions): Promise<ToolResult> {
+    const mapped = { ...args };
+    for (const key of ["filePath", "path", "dirPath", "dir", "targetPath", "cwd", "subdir"]) {
+      if (typeof mapped[key] === "string") mapped[key] = guestPath(mapped[key]);
+    }
+    return enqueue({ id: crypto.randomUUID(), type: "tool", tool: tool === "approve" ? "__plan_approve" : tool, args: mapped, ...(callOptions?.cwd ? { cwd: guestPath(callOptions.cwd) } : {}) }, callOptions);
+  }
+
+  return {
+    call,
+    toolMap(names): Record<string, ToolHandler> {
+      return Object.fromEntries(names.map(name => [name, (args: Record<string, unknown>, cwd: string, onProgress?: (text: string) => void) => call(name, args, { cwd, onProgress })]));
+    },
+    exec(argv: readonly string[], execOptions: SandboxExecOptions = {}): Promise<SandboxExecResult> {
+      return enqueue({ id: crypto.randomUUID(), type: "exec", argv: [...argv], ...(execOptions.cwd ? { cwd: guestPath(execOptions.cwd) } : {}), ...(execOptions.env ? { env: execOptions.env } : {}), ...(execOptions.stdin !== undefined ? { stdin: execOptions.stdin } : {}) }, { signal: execOptions.signal });
+    },
+    async replacePolicy(next): Promise<void> {
+      if (state === "closed" || state === "changing" || next.sessionKey !== policy.sessionKey || next.revision <= policy.revision) throw new Error("SANDBOX_POLICY: closed, changing or invalid policy revision");
+      const epoch = invalidate("SANDBOX_POLICY: replacing active generation", "changing");
+      const result = await terminate();
+      if (!result.gone) throw new Error(reason || "REVOKE_INCOMPLETE");
+      if (generation !== epoch) throw new Error(reason || "SANDBOX_POLICY: generation changed");
+      policy = next;
+      stopping = undefined;
+      state = "ready";
+      reason = "";
+    },
+    async revoke(): Promise<SandboxTermination> {
+      if (state !== "closed") invalidate("SANDBOX_REVOKED: session authority removed", "revoked");
+      return terminate();
+    },
+    async close(): Promise<void> {
+      invalidate("SANDBOX_CLOSED: supervisor closed", "closed");
+      const result = await terminate();
+      if (!result.gone) throw new Error("REVOKE_INCOMPLETE: sandbox close did not remove its environment");
+    },
+  };
+}