@elizaos/autonomous 2.0.0-alpha.72 → 2.0.0-alpha.73

package/src/api/sandbox-routes.ts

@@ -0,0 +1,1480 @@
+/** Sandbox capability API routes: status, exec, browser, screen, audio, computer use. */
+
+import { execFileSync, execSync } from "node:child_process";
+import { readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { platform, tmpdir } from "node:os";
+import { join } from "node:path";
+import type { RemoteSigningService } from "../services/remote-signing-service";
+import type { SandboxManager } from "../services/sandbox-manager";
+import type { SigningRequest } from "../services/signing-policy";
+import {
+  readJsonBody as parseJsonBody,
+  readRequestBody,
+  sendJson as sendJsonResponse,
+} from "./http-helpers";
+
+interface SandboxRouteState {
+  sandboxManager: SandboxManager | null;
+  signingService?: RemoteSigningService | null;
+}
+
+const MAX_COMPUTER_INPUT_LENGTH = 4096;
+const MAX_KEYPRESS_LENGTH = 128;
+const SAFE_KEYPRESS_PATTERN = /^[A-Za-z0-9+_.,: -]+$/;
+const ALLOWED_AUDIO_FORMATS = new Set(["wav", "mp3", "ogg", "flac", "m4a"]);
+const MIN_AUDIO_RECORD_DURATION_MS = 250;
+const MAX_AUDIO_RECORD_DURATION_MS = 30_000;
+
+// ── Route handler ────────────────────────────────────────────────────────────
+
+/** Returns `true` if handled, `false` to fall through. */
+export async function handleSandboxRoute(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathname: string,
+  method: string,
+  state: SandboxRouteState,
+): Promise<boolean> {
+  if (!pathname.startsWith("/api/sandbox")) {
+    return false;
+  }
+
+  const mgr = state.sandboxManager;
+
+  // Platform info doesn't require a running manager
+  if (method === "GET" && pathname === "/api/sandbox/platform") {
+    sendJson(res, 200, getPlatformInfo());
+    return true;
+  }
+
+  // ── POST /api/sandbox/docker/start ────────────────────────────────
+  // Attempt to start Docker Desktop (works on macOS/Windows desktop builds)
+  if (method === "POST" && pathname === "/api/sandbox/docker/start") {
+    try {
+      const result = attemptDockerStart();
+      sendJson(res, 200, result);
+    } catch (err) {
+      sendJson(res, 500, {
+        success: false,
+        error: `Failed to start Docker: ${err instanceof Error ? err.message : String(err)}`,
+      });
+    }
+    return true;
+  }
+
+  if (!mgr) {
+    sendJson(res, 503, {
+      error: "Sandbox manager not initialized",
+    });
+    return true;
+  }
+
+  // ── GET /api/sandbox/status ─────────────────────────────────────────
+  if (method === "GET" && pathname === "/api/sandbox/status") {
+    sendJson(res, 200, mgr.getStatus());
+    return true;
+  }
+
+  // ── GET /api/sandbox/events ─────────────────────────────────────────
+  if (method === "GET" && pathname === "/api/sandbox/events") {
+    const events = mgr.getEventLog();
+    sendJson(res, 200, { events: events.slice(-100) });
+    return true;
+  }
+
+  // ── POST /api/sandbox/start ─────────────────────────────────────────
+  if (method === "POST" && pathname === "/api/sandbox/start") {
+    try {
+      await mgr.start();
+      sendJson(res, 200, mgr.getStatus());
+    } catch (err) {
+      sendJson(res, 500, {
+        error: `Failed to start sandbox: ${err instanceof Error ? err.message : String(err)}`,
+      });
+    }
+    return true;
+  }
+
+  // ── POST /api/sandbox/stop ──────────────────────────────────────────
+  if (method === "POST" && pathname === "/api/sandbox/stop") {
+    try {
+      await mgr.stop();
+      sendJson(res, 200, mgr.getStatus());
+    } catch (err) {
+      sendJson(res, 500, {
+        error: `Failed to stop sandbox: ${err instanceof Error ? err.message : String(err)}`,
+      });
+    }
+    return true;
+  }
+
+  // ── POST /api/sandbox/recover ───────────────────────────────────────
+  if (method === "POST" && pathname === "/api/sandbox/recover") {
+    try {
+      await mgr.recover();
+      sendJson(res, 200, mgr.getStatus());
+    } catch (err) {
+      sendJson(res, 500, {
+        error: `Recovery failed: ${err instanceof Error ? err.message : String(err)}`,
+      });
+    }
+    return true;
+  }
+
+  // ── POST /api/sandbox/exec ──────────────────────────────────────────
+  if (method === "POST" && pathname === "/api/sandbox/exec") {
+    const parsed = await readJsonBody<{
+      command?: string;
+      workdir?: string;
+      timeoutMs?: number;
+    }>(req, res);
+    if (!parsed) return true;
+
+    if (!parsed.command || typeof parsed.command !== "string") {
+      sendJson(res, 400, { error: "Missing 'command' field" });
+      return true;
+    }
+
+    const result = await mgr.exec({
+      command: parsed.command,
+      workdir: parsed.workdir,
+      timeoutMs: parsed.timeoutMs,
+    });
+
+    sendJson(res, result.exitCode === 0 ? 200 : 422, result);
+    return true;
+  }
+
+  // ── GET /api/sandbox/browser ────────────────────────────────────────
+  if (method === "GET" && pathname === "/api/sandbox/browser") {
+    sendJson(res, 200, {
+      cdpEndpoint: mgr.getBrowserCdpEndpoint(),
+      wsEndpoint: mgr.getBrowserWsEndpoint(),
+      noVncEndpoint: mgr.getBrowserNoVncEndpoint(),
+    });
+    return true;
+  }
+
+  // ── Capability bridges ──────────────────────────────────────────────
+  if (method === "GET" && pathname === "/api/sandbox/screen/screenshot") {
+    try {
+      const screenshot = captureScreenshot();
+      res.writeHead(200, {
+        "Content-Type": "image/png",
+        "Content-Length": screenshot.length,
+      });
+      res.end(screenshot);
+    } catch (err) {
+      sendJson(res, 500, {
+        error: `Screenshot failed: ${err instanceof Error ? err.message : String(err)}`,
+      });
+    }
+    return true;
+  }
+
+  // ── POST /api/sandbox/screen/screenshot ─────────────────────────────
+  // Returns base64-encoded screenshot for easy consumption by agents
+  if (method === "POST" && pathname === "/api/sandbox/screen/screenshot") {
+    const rawBody = await readBody(req);
+    if (!rawBody || !rawBody.trim()) {
+      sendJson(res, 200, {
+        format: "png",
+        encoding: "base64",
+        width: null,
+        height: null,
+        data: captureScreenshot().toString("base64"),
+      });
+      return true;
+    }
+
+    let regionInput: unknown;
+    try {
+      regionInput = JSON.parse(rawBody);
+    } catch {
+      sendJson(res, 400, { error: "Invalid JSON body" });
+      return true;
+    }
+
+    const region = resolveScreenshotRegion(regionInput);
+    if (region.error) {
+      sendJson(res, 400, { error: region.error });
+      return true;
+    }
+
+    try {
+      const screenshot = captureScreenshot(region.region);
+      const base64 = screenshot.toString("base64");
+      sendJson(res, 200, {
+        format: "png",
+        encoding: "base64",
+        width: null, // platform-dependent
+        height: null,
+        data: base64,
+      });
+    } catch (err) {
+      sendJson(res, 500, {
+        error: `Screenshot failed: ${err instanceof Error ? err.message : String(err)}`,
+      });
+    }
+    return true;
+  }
+
+  // ── GET /api/sandbox/screen/windows ─────────────────────────────────
+  if (method === "GET" && pathname === "/api/sandbox/screen/windows") {
+    try {
+      const windows = listWindows();
+      sendJson(res, 200, { windows });
+    } catch (err) {
+      sendJson(res, 200, { windows: [], error: String(err) });
+    }
+    return true;
+  }
+
+  // ── POST /api/sandbox/audio/record ──────────────────────────────────
+  if (method === "POST" && pathname === "/api/sandbox/audio/record") {
+    const body = await readBody(req);
+    let durationMs = 5000;
+    if (body) {
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(body);
+      } catch {
+        sendJson(res, 400, {
+          error: "Invalid JSON in request body",
+        });
+        return true;
+      }
+
+      if (
+        parsed === null ||
+        typeof parsed !== "object" ||
+        Array.isArray(parsed)
+      ) {
+        sendJson(res, 400, { error: "Request body must be a JSON object" });
+        return true;
+      }
+
+      const bodyValues = parsed as Record<string, unknown>;
+
+      if (Object.hasOwn(bodyValues, "durationMs")) {
+        const durationValue = bodyValues.durationMs;
+        if (typeof durationValue !== "number") {
+          sendJson(res, 400, {
+            error: "durationMs must be a finite number",
+          });
+          return true;
+        }
+        // Defense in depth: JSON.parse only produces finite numbers, but this guard
+        // keeps behavior explicit against future parser/runtime changes.
+        if (!Number.isFinite(durationValue)) {
+          sendJson(res, 400, {
+            error: "durationMs must be a finite number",
+          });
+          return true;
+        }
+        if (!Number.isInteger(durationValue)) {
+          sendJson(res, 400, {
+            error: "durationMs must be an integer number of milliseconds",
+          });
+          return true;
+        }
+        if (
+          durationValue < MIN_AUDIO_RECORD_DURATION_MS ||
+          durationValue > MAX_AUDIO_RECORD_DURATION_MS
+        ) {
+          sendJson(res, 400, {
+            error: `durationMs must be between ${MIN_AUDIO_RECORD_DURATION_MS} and ${MAX_AUDIO_RECORD_DURATION_MS} milliseconds`,
+          });
+          return true;
+        }
+        durationMs = durationValue;
+      }
+    }
+    try {
+      const audio = await recordAudio(durationMs);
+      sendJson(res, 200, {
+        format: "wav",
+        encoding: "base64",
+        durationMs,
+        data: audio.toString("base64"),
+      });
+    } catch (err) {
+      sendJson(res, 500, {
+        error: `Audio recording failed: ${err instanceof Error ? err.message : String(err)}`,
+      });
+    }
+    return true;
+  }
+
+  // ── POST /api/sandbox/audio/play ────────────────────────────────────
+  if (method === "POST" && pathname === "/api/sandbox/audio/play") {
+    const parsed = await readJsonBody(req, res);
+    if (!parsed) return true;
+
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      sendJson(res, 400, { error: "Body must be a JSON object" });
+      return true;
+    }
+
+    const payload = parsed as { data?: unknown; format?: unknown };
+    if (typeof payload.data !== "string" || !payload.data.trim()) {
+      sendJson(res, 400, { error: "Missing 'data' field (base64 audio)" });
+      return true;
+    }
+
+    const formatResult = resolveAudioFormat(payload.format);
+    if (formatResult.error) {
+      sendJson(res, 400, { error: formatResult.error });
+      return true;
+    }
+
+    try {
+      await playAudio(Buffer.from(payload.data, "base64"), formatResult.format);
+      sendJson(res, 200, { success: true });
+    } catch (err) {
+      sendJson(res, 500, {
+        error: `Audio playback failed: ${err instanceof Error ? err.message : String(err)}`,
+      });
+    }
+    return true;
+  }
+
+  // ── POST /api/sandbox/computer/click ────────────────────────────────
+  if (method === "POST" && pathname === "/api/sandbox/computer/click") {
+    const parsed = await readJsonBody(req, res);
+    if (!parsed) return true;
+
+    const clickPayload = resolveClickPayload(parsed);
+    if (clickPayload.error) {
+      sendJson(res, 400, { error: clickPayload.error });
+      return true;
+    }
+
+    try {
+      const { x, y, button } = clickPayload;
+      performClick(x, y, button);
+      sendJson(res, 200, { success: true, x, y, button });
+    } catch (err) {
+      sendJson(res, 500, {
+        error: `Click failed: ${err instanceof Error ? err.message : String(err)}`,
+      });
+    }
+    return true;
+  }
+
+  // ── POST /api/sandbox/computer/type ─────────────────────────────────
+  if (method === "POST" && pathname === "/api/sandbox/computer/type") {
+    const parsed = await readJsonBody(req, res);
+    if (!parsed) return true;
+
+    const typePayload = resolveTypePayload(parsed);
+    if (typePayload.error) {
+      sendJson(res, 400, { error: typePayload.error });
+      return true;
+    }
+
+    try {
+      const { text } = typePayload;
+      performType(text);
+      sendJson(res, 200, { success: true, length: text.length });
+    } catch (err) {
+      sendJson(res, 500, {
+        error: `Type failed: ${err instanceof Error ? err.message : String(err)}`,
+      });
+    }
+    return true;
+  }
+
+  // ── POST /api/sandbox/computer/keypress ─────────────────────────────
+  if (method === "POST" && pathname === "/api/sandbox/computer/keypress") {
+    const parsed = await readJsonBody(req, res);
+    if (!parsed) return true;
+
+    const keypressPayload = resolveKeypressPayload(parsed);
+    if (keypressPayload.error) {
+      sendJson(res, 400, { error: keypressPayload.error });
+      return true;
+    }
+
+    try {
+      const { keys } = keypressPayload;
+      performKeypress(keys);
+      sendJson(res, 200, { success: true, keys });
+    } catch (err) {
+      sendJson(res, 500, {
+        error: `Keypress failed: ${err instanceof Error ? err.message : String(err)}`,
+      });
+    }
+    return true;
+  }
+
+  // ── Signing routes ─────────────────────────────────────────────────
+
+  if (method === "POST" && pathname === "/api/sandbox/sign") {
+    const signer = state.signingService;
+    if (!signer) {
+      sendJson(res, 503, { error: "Signing service not configured" });
+      return true;
+    }
+    const body = await readJsonBody<unknown>(req, res);
+    if (body === null) return true;
+    const parsed = resolveSigningRequestPayload(body);
+    if ("error" in parsed) {
+      sendJson(res, 400, { error: parsed.error });
+      return true;
+    }
+    try {
+      const result = await signer.submitSigningRequest(parsed.request);
+      sendJson(res, result.success ? 200 : 403, result);
+    } catch (err) {
+      sendJson(res, 400, {
+        error: `Invalid request: ${err instanceof Error ? err.message : String(err)}`,
+      });
+    }
+    return true;
+  }
+
+  if (method === "POST" && pathname === "/api/sandbox/sign/approve") {
+    const signer = state.signingService;
+    if (!signer) {
+      sendJson(res, 503, { error: "Signing service not configured" });
+      return true;
+    }
+    const body = await readJsonBody<{ requestId?: string }>(req, res);
+    if (!body) return true;
+    try {
+      const { requestId } = body as { requestId: string };
+      const result = await signer.approveRequest(requestId);
+      sendJson(res, result.success ? 200 : 403, result);
+    } catch (err) {
+      sendJson(res, 400, { error: String(err) });
+    }
+    return true;
+  }
+
+  if (method === "POST" && pathname === "/api/sandbox/sign/reject") {
+    const signer = state.signingService;
+    if (!signer) {
+      sendJson(res, 503, { error: "Signing service not configured" });
+      return true;
+    }
+    const body = await readJsonBody<{ requestId?: string }>(req, res);
+    if (!body) return true;
+    try {
+      const { requestId } = body as { requestId: string };
+      const rejected = signer.rejectRequest(requestId);
+      sendJson(res, 200, { rejected });
+    } catch (err) {
+      sendJson(res, 400, { error: String(err) });
+    }
+    return true;
+  }
+
+  if (method === "GET" && pathname === "/api/sandbox/sign/pending") {
+    const signer = state.signingService;
+    if (!signer) {
+      sendJson(res, 503, { error: "Signing service not configured" });
+      return true;
+    }
+    sendJson(res, 200, { pending: signer.getPendingApprovals() });
+    return true;
+  }
+
+  if (method === "GET" && pathname === "/api/sandbox/sign/address") {
+    const signer = state.signingService;
+    if (!signer) {
+      sendJson(res, 503, { error: "Signing service not configured" });
+      return true;
+    }
+    try {
+      const address = await signer.getAddress();
+      sendJson(res, 200, { address });
+    } catch (err) {
+      sendJson(res, 500, { error: String(err) });
+    }
+    return true;
+  }
+
+  // ── GET /api/sandbox/capabilities ───────────────────────────────────
+  if (method === "GET" && pathname === "/api/sandbox/capabilities") {
+    sendJson(res, 200, detectCapabilities());
+    return true;
+  }
+
+  // ── Fallthrough ─────────────────────────────────────────────────────
+  sendJson(res, 404, { error: `Unknown sandbox route: ${method} ${pathname}` });
+  return true;
+}
+
+function asObject(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  return value as Record<string, unknown>;
+}
+
+function resolveSigningRequestPayload(
+  input: unknown,
+): { request: SigningRequest } | { error: string } {
+  const obj = asObject(input);
+  if (!obj) {
+    return { error: "Signing payload must be a JSON object" };
+  }
+
+  const requestId = obj.requestId;
+  const chainId = parseFiniteInteger(obj.chainId);
+  const to = obj.to;
+  const value = obj.value;
+  const data = obj.data;
+  const nonce =
+    obj.nonce === undefined ? undefined : parseFiniteInteger(obj.nonce);
+  const rawGasLimit = obj.gasLimit;
+  const createdAt = parseFiniteInteger(obj.createdAt);
+
+  if (typeof requestId !== "string" || !requestId.trim()) {
+    return { error: "Signing payload requires a non-empty string 'requestId'" };
+  }
+  if (chainId === null || chainId < 0) {
+    return { error: "Signing payload requires an integer 'chainId' >= 0" };
+  }
+  if (typeof to !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(to.trim())) {
+    return {
+      error:
+        "Signing payload requires a hex 'to' address (e.g., 0x followed by 40 hex characters)",
+    };
+  }
+  if (typeof value !== "string" || !value.trim()) {
+    return { error: "Signing payload requires a non-empty string 'value'" };
+  }
+  if (typeof data !== "string" || !data.trim()) {
+    return { error: "Signing payload requires a non-empty string 'data'" };
+  }
+  if (nonce === null) {
+    return { error: "'nonce' must be a non-negative integer when provided" };
+  }
+  if (createdAt === null) {
+    return { error: "Signing payload requires an integer 'createdAt'" };
+  }
+  if (rawGasLimit !== undefined && typeof rawGasLimit !== "string") {
+    return {
+      error: "Signing payload 'gasLimit' must be a string when provided",
+    };
+  }
+
+  const gasLimit = (rawGasLimit as string | undefined)?.trim();
+  if (gasLimit === "") {
+    return {
+      error: "Signing payload 'gasLimit' cannot be empty when provided",
+    };
+  }
+
+  return {
+    request: {
+      requestId: requestId.trim(),
+      chainId,
+      to: to.trim(),
+      value: value.trim(),
+      data,
+      ...(nonce === undefined ? {} : { nonce }),
+      ...(gasLimit === undefined ? {} : { gasLimit }),
+      createdAt,
+    },
+  };
+}
+
+function parseFiniteInteger(value: unknown): number | null {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  if (!Number.isInteger(value)) return null;
+  return value;
+}
+
+function resolveScreenshotRegion(input: unknown): {
+  region?: { x: number; y: number; width: number; height: number };
+  error?: string;
+} {
+  if (input === undefined || input === null) return {};
+  const obj = asObject(input);
+  if (!obj) return { error: "Screenshot region payload must be a JSON object" };
+
+  const hasRegionField =
+    "x" in obj || "y" in obj || "width" in obj || "height" in obj;
+  if (!hasRegionField) return {};
+
+  const x = parseFiniteInteger(obj.x);
+  const y = parseFiniteInteger(obj.y);
+  const width = parseFiniteInteger(obj.width);
+  const height = parseFiniteInteger(obj.height);
+
+  if (x === null || y === null || width === null || height === null) {
+    return {
+      error: "Region requires integer x, y, width, and height values",
+    };
+  }
+  if (width <= 0 || height <= 0) {
+    return { error: "Region width and height must be greater than 0" };
+  }
+
+  return {
+    region: { x, y, width, height },
+  };
+}
+
+function resolveClickPayload(input: unknown): {
+  x: number;
+  y: number;
+  button: "left" | "right";
+  error?: string;
+} {
+  const obj = asObject(input);
+  if (!obj) {
+    return {
+      x: 0,
+      y: 0,
+      button: "left",
+      error: "Click payload must be a JSON object",
+    };
+  }
+
+  const x = parseFiniteInteger(obj.x);
+  const y = parseFiniteInteger(obj.y);
+  if (x === null || y === null) {
+    return {
+      x: 0,
+      y: 0,
+      button: "left",
+      error: "Click payload requires integer x and y coordinates",
+    };
+  }
+
+  const rawButton = obj.button;
+  let button: "left" | "right" = "left";
+  if (rawButton !== undefined) {
+    if (rawButton !== "left" && rawButton !== "right") {
+      return {
+        x,
+        y,
+        button,
+        error: "button must be either 'left' or 'right'",
+      };
+    }
+    button = rawButton;
+  }
+
+  return { x, y, button };
+}
+
+function resolveTypePayload(input: unknown): { text: string; error?: string } {
+  const obj = asObject(input);
+  if (!obj) return { text: "", error: "Type payload must be a JSON object" };
+  if (typeof obj.text !== "string") {
+    return { text: "", error: "Type payload requires a string 'text' field" };
+  }
+  if (obj.text.length === 0) {
+    return { text: "", error: "text cannot be empty" };
+  }
+  if (obj.text.length > MAX_COMPUTER_INPUT_LENGTH) {
+    return {
+      text: "",
+      error: `text exceeds maximum length (${MAX_COMPUTER_INPUT_LENGTH})`,
+    };
+  }
+  return { text: obj.text };
+}
+
+function resolveKeypressPayload(input: unknown): {
+  keys: string;
+  error?: string;
+} {
+  const obj = asObject(input);
+  if (!obj) {
+    return { keys: "", error: "Keypress payload must be a JSON object" };
+  }
+  if (typeof obj.keys !== "string") {
+    return {
+      keys: "",
+      error: "Keypress payload requires a string 'keys' field",
+    };
+  }
+
+  const keys = obj.keys.trim();
+  if (!keys) return { keys: "", error: "keys cannot be empty" };
+  if (keys.length > MAX_KEYPRESS_LENGTH) {
+    return {
+      keys: "",
+      error: `keys exceeds maximum length (${MAX_KEYPRESS_LENGTH})`,
+    };
+  }
+  if (!SAFE_KEYPRESS_PATTERN.test(keys)) {
+    return {
+      keys: "",
+      error:
+        "keys contains unsupported characters; allowed: letters, numbers, space, +, _, ., ,, :, -",
+    };
+  }
+
+  return { keys };
+}
+
+function resolveAudioFormat(input: unknown): {
+  format: string;
+  error?: string;
+} {
+  if (input === undefined || input === null) return { format: "wav" };
+  if (typeof input !== "string") {
+    return { format: "wav", error: "format must be a string" };
+  }
+
+  const normalized = input.trim().toLowerCase();
+  if (!normalized) return { format: "wav" };
+  if (!/^[a-z0-9]+$/.test(normalized)) {
+    return {
+      format: "wav",
+      error:
+        "format contains unsupported characters; use one of: wav, mp3, ogg, flac, m4a",
+    };
+  }
+  if (!ALLOWED_AUDIO_FORMATS.has(normalized)) {
+    return {
+      format: "wav",
+      error: "format must be one of: wav, mp3, ogg, flac, m4a",
+    };
+  }
+
+  return { format: normalized };
+}
+
+function runCommand(command: string, args: string[], timeout: number): void {
+  execFileSync(command, args, {
+    timeout,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+}
+
+function captureScreenshot(region?: {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}): Buffer {
+  const os = platform();
+  const tmpFile = join(tmpdir(), `sandbox-screenshot-${Date.now()}.png`);
+
+  try {
+    if (os === "darwin") {
+      if (region) {
+        runCommand(
+          "screencapture",
+          [
+            `-R${region.x},${region.y},${region.width},${region.height}`,
+            "-x",
+            tmpFile,
+          ],
+          10000,
+        );
+      } else {
+        runCommand("screencapture", ["-x", tmpFile], 10000);
+      }
+    } else if (os === "linux") {
+      // Try tools in preference order
+      if (commandExists("import")) {
+        if (region) {
+          runCommand(
+            "import",
+            [
+              "-window",
+              "root",
+              "-crop",
+              `${region.width}x${region.height}+${region.x}+${region.y}`,
+              tmpFile,
+            ],
+            10000,
+          );
+        } else {
+          runCommand("import", ["-window", "root", tmpFile], 10000);
+        }
+      } else if (commandExists("scrot")) {
+        runCommand("scrot", [tmpFile], 10000);
+      } else if (commandExists("gnome-screenshot")) {
+        runCommand("gnome-screenshot", ["-f", tmpFile], 10000);
+      } else {
+        throw new Error(
+          "No screenshot tool available. Install ImageMagick, scrot, or gnome-screenshot.",
+        );
+      }
+    } else if (os === "win32") {
+      // PowerShell screenshot
+      const psCmd = [
+        `Add-Type -AssemblyName System.Windows.Forms`,
+        `$screen = [System.Windows.Forms.Screen]::PrimaryScreen.Bounds`,
+        `$bitmap = New-Object System.Drawing.Bitmap($screen.Width, $screen.Height)`,
+        `$graphics = [System.Drawing.Graphics]::FromImage($bitmap)`,
+        `$graphics.CopyFromScreen($screen.Location, [System.Drawing.Point]::Empty, $screen.Size)`,
+        `$bitmap.Save('${tmpFile.replace(/\//g, "\\")}')`,
+        `$graphics.Dispose()`,
+        `$bitmap.Dispose()`,
+      ].join("; ");
+      execSync(`powershell -Command "${psCmd}"`, {
+        timeout: 15000,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+    } else {
+      throw new Error(`Screenshot not supported on platform: ${os}`);
+    }
+
+    const data = readFileSync(tmpFile);
+    try {
+      unlinkSync(tmpFile);
+    } catch {
+      /* cleanup best effort */
+    }
+    return data;
+  } catch (err) {
+    // Clean up temp file on error
+    try {
+      unlinkSync(tmpFile);
+    } catch {
+      /* ignore */
+    }
+    throw err;
+  }
+}
+
+function listWindows(): Array<{ id: string; title: string; app: string }> {
+  const os = platform();
+
+  if (os === "darwin") {
+    try {
+      const script = `
+        tell application "System Events"
+          set windowList to {}
+          repeat with proc in (every process whose visible is true)
+            try
+              repeat with w in (every window of proc)
+                set end of windowList to (name of proc) & "|||" & (name of w) & "|||" & (id of w as text)
+              end repeat
+            end try
+          end repeat
+          return windowList as text
+        end tell`;
+      const output = execSync(`osascript -e '${script}'`, {
+        encoding: "utf-8",
+        timeout: 10000,
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+      return output
+        .split(", ")
+        .filter(Boolean)
+        .map((entry) => {
+          const parts = entry.split("|||");
+          return {
+            app: parts[0] ?? "unknown",
+            title: parts[1] ?? "unknown",
+            id: parts[2] ?? "0",
+          };
+        });
+    } catch {
+      return [];
+    }
+  }
+
+  if (os === "linux") {
+    try {
+      const output = execSync(
+        'wmctrl -l 2>/dev/null || xdotool search --name "" getwindowname 2>/dev/null',
+        {
+          encoding: "utf-8",
+          timeout: 5000,
+        },
+      );
+      return output
+        .split("\n")
+        .filter(Boolean)
+        .map((line, i) => ({
+          id: String(i),
+          title: line.trim(),
+          app: "unknown",
+        }));
+    } catch {
+      return [];
+    }
+  }
+
+  if (os === "win32") {
+    try {
+      const output = execSync(
+        `powershell -Command "Get-Process | Where-Object {$_.MainWindowTitle} | Select-Object Id, MainWindowTitle | ConvertTo-Json"`,
+        { encoding: "utf-8", timeout: 10000 },
+      );
+      const processes = JSON.parse(output);
+      const list = Array.isArray(processes) ? processes : [processes];
+      return list.map((p: { Id: number; MainWindowTitle: string }) => ({
+        id: String(p.Id),
+        title: p.MainWindowTitle,
+        app: "unknown",
+      }));
+    } catch {
+      return [];
+    }
+  }
+
+  return [];
+}
+
+async function recordAudio(durationMs: number): Promise<Buffer> {
+  const os = platform();
+  const durationSec = Math.ceil(durationMs / 1000);
+  const tmpFile = join(tmpdir(), `sandbox-audio-${Date.now()}.wav`);
+
+  if (os === "darwin") {
+    // Use sox (rec) on macOS
+    if (commandExists("rec")) {
+      execSync(`rec -q ${tmpFile} trim 0 ${durationSec}`, {
+        timeout: durationMs + 5000,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+    } else if (commandExists("ffmpeg")) {
+      execSync(
+        `ffmpeg -f avfoundation -i ":0" -t ${durationSec} -y ${tmpFile} 2>/dev/null`,
+        { timeout: durationMs + 10000, stdio: ["ignore", "pipe", "pipe"] },
+      );
+    } else {
+      throw new Error(
+        "No audio recording tool available. Install sox or ffmpeg.",
+      );
+    }
+  } else if (os === "linux") {
+    if (commandExists("arecord")) {
+      execSync(`arecord -d ${durationSec} -f cd ${tmpFile}`, {
+        timeout: durationMs + 5000,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+    } else if (commandExists("ffmpeg")) {
+      execSync(
+        `ffmpeg -f pulse -i default -t ${durationSec} -y ${tmpFile} 2>/dev/null`,
+        { timeout: durationMs + 10000, stdio: ["ignore", "pipe", "pipe"] },
+      );
+    } else {
+      throw new Error(
+        "No audio recording tool available. Install alsa-utils or ffmpeg.",
+      );
+    }
+  } else if (os === "win32") {
+    // Use ffmpeg on Windows (most portable)
+    if (commandExists("ffmpeg")) {
+      execSync(
+        `ffmpeg -f dshow -i audio="Microphone" -t ${durationSec} -y "${tmpFile.replace(/\//g, "\\")}" 2>NUL`,
+        { timeout: durationMs + 10000, stdio: ["ignore", "pipe", "pipe"] },
+      );
+    } else {
+      throw new Error("No audio recording tool available. Install ffmpeg.");
+    }
+  } else {
+    throw new Error(`Audio recording not supported on platform: ${os}`);
+  }
+
+  const data = readFileSync(tmpFile);
+  try {
+    unlinkSync(tmpFile);
+  } catch {
+    /* cleanup */
+  }
+  return data;
+}
+
+async function playAudio(data: Buffer, format: string): Promise<void> {
+  const os = platform();
+  const tmpFile = join(tmpdir(), `sandbox-play-${Date.now()}.${format}`);
+  writeFileSync(tmpFile, data);
+
+  try {
+    if (os === "darwin") {
+      runCommand("afplay", [tmpFile], 60000);
+    } else if (os === "linux") {
+      if (commandExists("aplay")) {
+        runCommand("aplay", [tmpFile], 60000);
+      } else if (commandExists("paplay")) {
+        runCommand("paplay", [tmpFile], 60000);
+      } else if (commandExists("ffplay")) {
+        runCommand("ffplay", ["-autoexit", "-nodisp", tmpFile], 60000);
+      } else {
+        throw new Error("No audio playback tool available.");
+      }
+    } else if (os === "win32") {
+      const escapedPath = tmpFile.replace(/\//g, "\\").replace(/'/g, "''");
+      runCommand(
+        "powershell",
+        [
+          "-Command",
+          `(New-Object Media.SoundPlayer '${escapedPath}').PlaySync()`,
+        ],
+        60000,
+      );
+    }
+  } finally {
+    try {
+      unlinkSync(tmpFile);
+    } catch {
+      /* cleanup */
+    }
+  }
+}
+
+function toAppleScriptStringLiteral(value: string): string {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+function performClick(x: number, y: number, button: "left" | "right"): void {
+  const os = platform();
+
+  if (os === "darwin") {
+    // Use cliclick on macOS (brew install cliclick)
+    if (commandExists("cliclick")) {
+      const btn = button === "right" ? "rc" : "c";
+      runCommand("cliclick", [`${btn}:${x},${y}`], 5000);
+    } else {
+      // AppleScript fallback
+      runCommand(
+        "osascript",
+        ["-e", `tell application "System Events" to click at {${x}, ${y}}`],
+        5000,
+      );
+    }
+  } else if (os === "linux") {
+    if (commandExists("xdotool")) {
+      const btn = button === "right" ? "3" : "1";
+      runCommand(
+        "xdotool",
+        ["mousemove", String(x), String(y), "click", btn],
+        5000,
+      );
+    } else {
+      throw new Error("xdotool required for mouse control on Linux.");
+    }
+  } else if (os === "win32") {
+    // Use Win32 API via PowerShell to perform an actual mouse click
+    const psScript = [
+      `Add-Type -AssemblyName System.Windows.Forms`,
+      `[System.Windows.Forms.Cursor]::Position = New-Object System.Drawing.Point(${x},${y})`,
+      `Add-Type -MemberDefinition '[DllImport("user32.dll")] public static extern void mouse_event(int dwFlags, int dx, int dy, int dwData, int dwExtraInfo);' -Name Win32Mouse -Namespace Win32`,
+      button === "right"
+        ? `[Win32.Win32Mouse]::mouse_event(0x0008, 0, 0, 0, 0); [Win32.Win32Mouse]::mouse_event(0x0010, 0, 0, 0, 0)` // right down + up
+        : `[Win32.Win32Mouse]::mouse_event(0x0002, 0, 0, 0, 0); [Win32.Win32Mouse]::mouse_event(0x0004, 0, 0, 0, 0)`, // left down + up
+    ].join("; ");
+    runCommand("powershell", ["-Command", psScript], 5000);
+  }
+}
+
+function performType(text: string): void {
+  const os = platform();
+
+  if (os === "darwin") {
+    if (commandExists("cliclick")) {
+      runCommand("cliclick", [`t:${text}`], 10000);
+    } else {
+      runCommand(
+        "osascript",
+        [
+          "-e",
+          `tell application "System Events" to keystroke ${toAppleScriptStringLiteral(text)}`,
+        ],
+        10000,
+      );
+    }
+  } else if (os === "linux") {
+    if (commandExists("xdotool")) {
+      runCommand("xdotool", ["type", "--", text], 10000);
+    } else {
+      throw new Error("xdotool required for keyboard input on Linux.");
+    }
+  } else if (os === "win32") {
+    const escaped = text.replace(/'/g, "''");
+    runCommand(
+      "powershell",
+      [
+        "-Command",
+        `Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.SendKeys]::SendWait('${escaped}')`,
+      ],
+      10000,
+    );
+  }
+}
+
+function performKeypress(keys: string): void {
+  const os = platform();
+
+  if (os === "darwin") {
+    if (commandExists("cliclick")) {
+      runCommand("cliclick", [`kp:${keys}`], 5000);
+    } else {
+      const symbolicKeyCodes: Record<string, number> = {
+        return: 36,
+        enter: 36,
+        tab: 48,
+        space: 49,
+        escape: 53,
+        esc: 53,
+        left: 123,
+        right: 124,
+        down: 125,
+        up: 126,
+      };
+      const normalized = keys.trim().toLowerCase();
+      const mappedCode = symbolicKeyCodes[normalized];
+      const numericCode =
+        mappedCode ??
+        (Number.isInteger(Number(keys.trim())) ? Number(keys.trim()) : null);
+
+      if (numericCode !== null) {
+        runCommand(
+          "osascript",
+          ["-e", `tell application "System Events" to key code ${numericCode}`],
+          5000,
+        );
+      } else {
+        runCommand(
+          "osascript",
+          [
+            "-e",
+            `tell application "System Events" to keystroke ${toAppleScriptStringLiteral(keys)}`,
+          ],
+          5000,
+        );
+      }
+    }
+  } else if (os === "linux") {
+    if (commandExists("xdotool")) {
+      runCommand("xdotool", ["key", keys], 5000);
+    } else {
+      throw new Error("xdotool required for key input on Linux.");
+    }
+  } else if (os === "win32") {
+    const escaped = keys.replace(/'/g, "''");
+    runCommand(
+      "powershell",
+      [
+        "-Command",
+        `Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.SendKeys]::SendWait('${escaped}')`,
+      ],
+      5000,
+    );
+  }
+}
+
+function detectCapabilities(): Record<
+  string,
+  { available: boolean; tool: string }
+> {
+  const os = platform();
+  const caps: Record<string, { available: boolean; tool: string }> = {};
+
+  // Screenshot
+  if (os === "darwin") {
+    caps.screenshot = { available: true, tool: "screencapture (built-in)" };
+  } else if (os === "linux") {
+    if (commandExists("import"))
+      caps.screenshot = { available: true, tool: "ImageMagick import" };
+    else if (commandExists("scrot"))
+      caps.screenshot = { available: true, tool: "scrot" };
+    else if (commandExists("gnome-screenshot"))
+      caps.screenshot = { available: true, tool: "gnome-screenshot" };
+    else
+      caps.screenshot = {
+        available: false,
+        tool: "none (install ImageMagick, scrot, or gnome-screenshot)",
+      };
+  } else if (os === "win32") {
+    caps.screenshot = { available: true, tool: "PowerShell System.Drawing" };
+  } else {
+    caps.screenshot = { available: false, tool: "unsupported platform" };
+  }
+
+  // Audio record
+  if (os === "darwin") {
+    if (commandExists("rec"))
+      caps.audioRecord = { available: true, tool: "sox rec" };
+    else if (commandExists("ffmpeg"))
+      caps.audioRecord = { available: true, tool: "ffmpeg" };
+    else
+      caps.audioRecord = {
+        available: false,
+        tool: "none (install sox or ffmpeg)",
+      };
+  } else if (os === "linux") {
+    if (commandExists("arecord"))
+      caps.audioRecord = { available: true, tool: "arecord" };
+    else if (commandExists("ffmpeg"))
+      caps.audioRecord = { available: true, tool: "ffmpeg" };
+    else
+      caps.audioRecord = {
+        available: false,
+        tool: "none (install alsa-utils or ffmpeg)",
+      };
+  } else if (os === "win32") {
+    if (commandExists("ffmpeg"))
+      caps.audioRecord = { available: true, tool: "ffmpeg" };
+    else caps.audioRecord = { available: false, tool: "none (install ffmpeg)" };
+  } else {
+    caps.audioRecord = { available: false, tool: "unsupported" };
+  }
+
+  // Audio play
+  if (os === "darwin")
+    caps.audioPlay = { available: true, tool: "afplay (built-in)" };
+  else if (os === "linux") {
+    if (commandExists("aplay"))
+      caps.audioPlay = { available: true, tool: "aplay" };
+    else if (commandExists("paplay"))
+      caps.audioPlay = { available: true, tool: "paplay" };
+    else if (commandExists("ffplay"))
+      caps.audioPlay = { available: true, tool: "ffplay" };
+    else caps.audioPlay = { available: false, tool: "none" };
+  } else if (os === "win32") {
+    caps.audioPlay = { available: true, tool: "PowerShell SoundPlayer" };
+  } else {
+    caps.audioPlay = { available: false, tool: "unsupported" };
+  }
+
+  // Mouse/keyboard control
+  if (os === "darwin") {
+    if (commandExists("cliclick"))
+      caps.computerUse = { available: true, tool: "cliclick" };
+    else caps.computerUse = { available: true, tool: "AppleScript (limited)" };
+  } else if (os === "linux") {
+    if (commandExists("xdotool"))
+      caps.computerUse = { available: true, tool: "xdotool" };
+    else
+      caps.computerUse = { available: false, tool: "none (install xdotool)" };
+  } else if (os === "win32") {
+    caps.computerUse = { available: true, tool: "PowerShell SendKeys" };
+  } else {
+    caps.computerUse = { available: false, tool: "unsupported" };
+  }
+
+  // Window listing
+  if (os === "darwin")
+    caps.windowList = { available: true, tool: "AppleScript" };
+  else if (os === "linux") {
+    if (commandExists("wmctrl"))
+      caps.windowList = { available: true, tool: "wmctrl" };
+    else if (commandExists("xdotool"))
+      caps.windowList = { available: true, tool: "xdotool" };
+    else
+      caps.windowList = {
+        available: false,
+        tool: "none (install wmctrl or xdotool)",
+      };
+  } else if (os === "win32") {
+    caps.windowList = { available: true, tool: "PowerShell Get-Process" };
+  } else {
+    caps.windowList = { available: false, tool: "unsupported" };
+  }
+
+  // Browser
+  caps.browser = { available: true, tool: "CDP via sandbox browser container" };
+
+  // Shell
+  caps.shell = { available: true, tool: "docker exec" };
+
+  return caps;
+}
+
+function getPlatformInfo(): Record<string, string | boolean> {
+  const os = platform();
+  let dockerInstalled = false;
+  let dockerRunning = false;
+  let appleContainerAvailable = false;
+
+  // Check if docker binary exists (installed)
+  try {
+    const which = os === "win32" ? "where" : "which";
+    execSync(`${which} docker`, { stdio: "ignore", timeout: 3000 });
+    dockerInstalled = true;
+  } catch {
+    /* not installed */
+  }
+
+  // Check if docker daemon is running (docker info succeeds only when daemon is up)
+  if (dockerInstalled) {
+    try {
+      execSync("docker info", { stdio: "ignore", timeout: 5000 });
+      dockerRunning = true;
+    } catch {
+      /* installed but not running */
+    }
+  }
+
+  if (os === "darwin") {
+    try {
+      execSync("which container", { stdio: "ignore", timeout: 3000 });
+      appleContainerAvailable = true;
+    } catch {
+      /* */
+    }
+  }
+
+  return {
+    platform: os,
+    arch: require("node:os").arch(),
+    dockerInstalled,
+    dockerRunning,
+    // Legacy compat: dockerAvailable = running (old clients check this)
+    dockerAvailable: dockerRunning,
+    appleContainerAvailable,
+    wsl2: os === "win32" ? isWsl2Available() : false,
+    recommended:
+      os === "darwin" && appleContainerAvailable ? "apple-container" : "docker",
+  };
+}
+
+function isWsl2Available(): boolean {
+  try {
+    execSync("wsl --status", { stdio: "ignore", timeout: 5000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function attemptDockerStart(): {
+  success: boolean;
+  message: string;
+  waitMs: number;
+} {
+  const os = platform();
+
+  try {
+    if (os === "darwin") {
+      execSync('open -a "Docker"', { timeout: 5000, stdio: "ignore" });
+      return {
+        success: true,
+        message: "Docker Desktop is starting on macOS. Give it a moment~",
+        waitMs: 15000,
+      };
+    }
+
+    if (os === "win32") {
+      // Try common install locations
+      const paths = [
+        '"C:\\Program Files\\Docker\\Docker\\Docker Desktop.exe"',
+        '"C:\\Program Files (x86)\\Docker\\Docker\\Docker Desktop.exe"',
+      ];
+      let started = false;
+      for (const p of paths) {
+        try {
+          execSync(`start "" ${p}`, {
+            timeout: 5000,
+            stdio: "ignore",
+            shell: "cmd.exe",
+          });
+          started = true;
+          break;
+        } catch {
+          /* try next path */
+        }
+      }
+      if (!started) {
+        // Try via start menu
+        execSync('start "" "Docker Desktop"', {
+          timeout: 5000,
+          stdio: "ignore",
+          shell: "cmd.exe",
+        });
+      }
+      return {
+        success: true,
+        message:
+          "Docker Desktop is starting on Windows. This may take 30 seconds~",
+        waitMs: 30000,
+      };
+    }
+
+    if (os === "linux") {
+      // Try systemctl first (most common)
+      try {
+        execSync("sudo systemctl start docker", {
+          timeout: 10000,
+          stdio: "ignore",
+        });
+        return {
+          success: true,
+          message: "Docker daemon started via systemctl",
+          waitMs: 5000,
+        };
+      } catch {
+        /* systemctl may not be available */
+      }
+
+      // Try service command
+      try {
+        execSync("sudo service docker start", {
+          timeout: 10000,
+          stdio: "ignore",
+        });
+        return {
+          success: true,
+          message: "Docker daemon started via service",
+          waitMs: 5000,
+        };
+      } catch {
+        /* */
+      }
+
+      return {
+        success: false,
+        message:
+          "Could not auto-start Docker on Linux. Run: sudo systemctl start docker",
+        waitMs: 0,
+      };
+    }
+
+    return {
+      success: false,
+      message: `Auto-start not supported on ${os}`,
+      waitMs: 0,
+    };
+  } catch (err) {
+    return {
+      success: false,
+      message: `Failed: ${err instanceof Error ? err.message : String(err)}`,
+      waitMs: 0,
+    };
+  }
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function commandExists(cmd: string): boolean {
+  try {
+    const which = platform() === "win32" ? "where" : "which";
+    execSync(`${which} ${cmd}`, { stdio: "ignore", timeout: 3000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function sendJson(res: ServerResponse, status: number, data: object): void {
+  sendJsonResponse(res, data, status);
+}
+
+function readBody(req: IncomingMessage): Promise<string | null> {
+  return readRequestBody(req, {
+    maxBytes: 10 * 1024 * 1024,
+    returnNullOnTooLarge: true,
+    returnNullOnError: true,
+    destroyOnTooLarge: true,
+  });
+}
+
+function readJsonBody<T = unknown>(
+  req: IncomingMessage,
+  res: ServerResponse,
+): Promise<T | null> {
+  return parseJsonBody(req, res, {
+    maxBytes: 10 * 1024 * 1024,
+    requireObject: false,
+    readErrorStatus: 400,
+    parseErrorStatus: 400,
+    readErrorMessage: "Missing request body",
+    parseErrorMessage: "Invalid JSON in request body",
+  });
+}