agentbox-sdk 0.1.0 → 0.1.3

package/dist/chunk-4MBB6QHD.js

@@ -0,0 +1,4658 @@
+import {
+  createNormalizedEvent,
+  normalizeRawAgentEvent,
+  toAISDKStream
+} from "./chunk-ZOWBRUQR.js";
+import {
+  AgentBoxError,
+  AsyncQueue,
+  UnsupportedProviderError,
+  asError,
+  debugAgent,
+  debugClaude,
+  debugCodex,
+  debugOpencode,
+  debugRelay,
+  debugRuntime,
+  debugSetup,
+  linesFromTextChunks,
+  sleep,
+  time,
+  waitFor
+} from "./chunk-INMA52FV.js";
+import {
+  shellQuote
+} from "./chunk-NSJM57Z4.js";
+import {
+  AgentProvider,
+  SandboxProvider
+} from "./chunk-GOFJNFAD.js";
+
+// src/agents/Agent.ts
+import { randomUUID as randomUUID2 } from "crypto";
+
+// src/agents/providers/claude-code.ts
+import { randomUUID } from "crypto";
+import path8 from "path";
+
+// src/agents/approval.ts
+function getApprovalMode(options) {
+  return options.approvalMode ?? "auto";
+}
+function isInteractiveApproval(options) {
+  return getApprovalMode(options) === "interactive";
+}
+function shouldAutoApproveClaudeTools(options) {
+  if (options.provider?.autoApproveTools !== void 0) {
+    return options.provider.autoApproveTools;
+  }
+  return !isInteractiveApproval(options);
+}
+
+// src/agents/input.ts
+import { readFile } from "fs/promises";
+import path from "path";
+import { fileURLToPath } from "url";
+var IMAGE_MEDIA_TYPE_BY_EXTENSION = {
+  ".gif": "image/gif",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".png": "image/png",
+  ".webp": "image/webp"
+};
+var FILE_MEDIA_TYPE_BY_EXTENSION = {
+  ...IMAGE_MEDIA_TYPE_BY_EXTENSION,
+  ".csv": "text/csv",
+  ".htm": "text/html",
+  ".html": "text/html",
+  ".json": "application/json",
+  ".md": "text/markdown",
+  ".pdf": "application/pdf",
+  ".txt": "text/plain",
+  ".xml": "application/xml",
+  ".yaml": "application/yaml",
+  ".yml": "application/yaml"
+};
+var CLAUDE_IMAGE_MEDIA_TYPES = /* @__PURE__ */ new Set([
+  "image/gif",
+  "image/jpeg",
+  "image/png",
+  "image/webp"
+]);
+var CLAUDE_TEXT_LIKE_MEDIA_TYPES = /* @__PURE__ */ new Set([
+  "application/json",
+  "application/xml",
+  "application/yaml",
+  "text/csv",
+  "text/html",
+  "text/markdown",
+  "text/plain",
+  "text/xml"
+]);
+function normalizeUserInput(input) {
+  return typeof input === "string" ? [{ type: "text", text: input }] : input;
+}
+async function resolveUserInputParts(input) {
+  const parts = normalizeUserInput(input);
+  return Promise.all(parts.map((part) => resolveUserInputPart(part)));
+}
+async function validateProviderUserInput(provider, input) {
+  const parts = await resolveUserInputParts(input);
+  if (provider === AgentProvider.Codex) {
+    const unsupportedPart = parts.find((part) => part.type === "file");
+    if (unsupportedPart) {
+      throw new AgentBoxError(
+        `The codex provider does not yet support "${unsupportedPart.type}" input parts through codex app-server. Codex currently supports text and image input items.`,
+        {
+          code: "UNSUPPORTED_INPUT_PART",
+          details: {
+            provider,
+            partType: unsupportedPart.type
+          }
+        }
+      );
+    }
+    return parts;
+  }
+  if (provider === AgentProvider.ClaudeCode) {
+    for (const part of parts) {
+      if (part.type === "image") {
+        if (!CLAUDE_IMAGE_MEDIA_TYPES.has(part.mediaType)) {
+          throw new AgentBoxError(
+            `Claude Code only supports image inputs with one of these media types: ${Array.from(CLAUDE_IMAGE_MEDIA_TYPES).join(", ")}.`,
+            {
+              code: "UNSUPPORTED_INPUT_MEDIA_TYPE",
+              details: {
+                provider,
+                partType: part.type,
+                mediaType: part.mediaType
+              }
+            }
+          );
+        }
+      }
+      if (part.type === "file") {
+        if (part.mediaType !== "application/pdf" && !isClaudeTextLikeMediaType(part.mediaType)) {
+          throw new AgentBoxError(
+            `Claude Code only supports PDF and text-like file inputs. Received "${part.mediaType}".`,
+            {
+              code: "UNSUPPORTED_INPUT_MEDIA_TYPE",
+              details: {
+                provider,
+                partType: part.type,
+                mediaType: part.mediaType
+              }
+            }
+          );
+        }
+        if (part.source.type === "url" && part.mediaType !== "application/pdf" && isClaudeTextLikeMediaType(part.mediaType)) {
+          throw new AgentBoxError(
+            "Claude Code text-like file inputs must be provided as inline data, not a remote URL.",
+            {
+              code: "UNSUPPORTED_INPUT_SOURCE",
+              details: {
+                provider,
+                partType: part.type,
+                mediaType: part.mediaType,
+                sourceType: part.source.type
+              }
+            }
+          );
+        }
+      }
+    }
+  }
+  return parts;
+}
+function mapToOpenCodeParts(parts) {
+  return parts.map((part) => {
+    if (part.type === "text") {
+      return {
+        type: "text",
+        text: part.text
+      };
+    }
+    return {
+      type: "file",
+      url: binarySourceToUrl(part.source, part.mediaType),
+      mime: part.mediaType,
+      ...part.type === "file" && part.filename ? { filename: part.filename } : {}
+    };
+  });
+}
+function mapToClaudeUserContent(parts) {
+  if (parts.every((part) => part.type === "text")) {
+    return joinTextParts(parts);
+  }
+  return parts.map((part) => {
+    if (part.type === "text") {
+      return {
+        type: "text",
+        text: part.text
+      };
+    }
+    if (part.type === "image") {
+      if (part.source.type === "url" && isRemoteUrl(part.source.url)) {
+        return {
+          type: "image",
+          source: {
+            type: "url",
+            url: part.source.url
+          }
+        };
+      }
+      return {
+        type: "image",
+        source: {
+          type: "base64",
+          media_type: part.mediaType,
+          data: part.source.type === "base64" ? part.source.data : dataUrlToBase64(part.source.url)
+        }
+      };
+    }
+    if (part.mediaType === "application/pdf") {
+      if (part.source.type === "url" && isRemoteUrl(part.source.url)) {
+        return {
+          type: "document",
+          source: {
+            type: "url",
+            url: part.source.url
+          }
+        };
+      }
+      return {
+        type: "document",
+        source: {
+          type: "base64",
+          media_type: part.mediaType,
+          data: part.source.type === "base64" ? part.source.data : dataUrlToBase64(part.source.url)
+        }
+      };
+    }
+    if (!isClaudeTextLikeMediaType(part.mediaType)) {
+      throw new AgentBoxError(
+        `Claude Code cannot map file inputs with media type "${part.mediaType}".`,
+        {
+          code: "UNSUPPORTED_INPUT_MEDIA_TYPE",
+          details: {
+            partType: part.type,
+            mediaType: part.mediaType
+          }
+        }
+      );
+    }
+    return {
+      type: "document",
+      source: {
+        type: "text",
+        media_type: "text/plain",
+        data: Buffer.from(
+          part.source.type === "base64" ? part.source.data : dataUrlToBase64(part.source.url),
+          "base64"
+        ).toString("utf8")
+      }
+    };
+  });
+}
+async function mapToCodexPromptParts(parts, materializeLocalImage) {
+  const mapped = [];
+  for (const [index, part] of parts.entries()) {
+    if (part.type !== "image") {
+      continue;
+    }
+    if (part.source.type === "url" && isRemoteUrl(part.source.url)) {
+      mapped.push({
+        type: "image",
+        url: part.source.url
+      });
+      continue;
+    }
+    mapped.push({
+      type: "localImage",
+      path: await materializeLocalImage(part, index)
+    });
+  }
+  return mapped;
+}
+function joinTextParts(parts) {
+  return parts.map((part) => {
+    if (part.type !== "text") {
+      throw new AgentBoxError(
+        `Cannot join "${part.type}" input parts into a text-only prompt.`,
+        {
+          code: "UNSUPPORTED_INPUT_PART",
+          details: {
+            partType: part.type
+          }
+        }
+      );
+    }
+    return part.text;
+  }).join("");
+}
+async function resolveUserInputPart(part) {
+  if (part.type === "text") {
+    return part;
+  }
+  if (part.type === "image") {
+    const resolved2 = await resolveBinaryContent(part.image, {
+      kind: "image",
+      mediaType: part.mediaType
+    });
+    return {
+      type: "image",
+      mediaType: resolved2.mediaType,
+      source: resolved2.source
+    };
+  }
+  const resolved = await resolveBinaryContent(part.data, {
+    kind: "file",
+    mediaType: part.mediaType,
+    filename: part.filename
+  });
+  return {
+    type: "file",
+    mediaType: resolved.mediaType,
+    filename: resolved.filename,
+    source: resolved.source
+  };
+}
+async function resolveBinaryContent(content, options) {
+  if (content instanceof URL) {
+    return resolveUrlContent(content, options);
+  }
+  if (typeof content === "string") {
+    const url = parseStructuredUrl(content);
+    if (url) {
+      return resolveUrlContent(url, options);
+    }
+    const mediaType = resolveMediaType("", options);
+    return {
+      mediaType,
+      filename: options.filename,
+      source: {
+        type: "base64",
+        data: content
+      }
+    };
+  }
+  if (Buffer.isBuffer(content)) {
+    return {
+      mediaType: resolveMediaType("", options),
+      filename: options.filename,
+      source: {
+        type: "base64",
+        data: content.toString("base64")
+      }
+    };
+  }
+  if (content instanceof Uint8Array) {
+    return {
+      mediaType: resolveMediaType("", options),
+      filename: options.filename,
+      source: {
+        type: "base64",
+        data: Buffer.from(content).toString("base64")
+      }
+    };
+  }
+  if (content instanceof ArrayBuffer) {
+    return {
+      mediaType: resolveMediaType("", options),
+      filename: options.filename,
+      source: {
+        type: "base64",
+        data: Buffer.from(content).toString("base64")
+      }
+    };
+  }
+  throw new AgentBoxError("Unsupported input content type.", {
+    code: "UNSUPPORTED_INPUT_SOURCE",
+    details: {
+      kind: options.kind,
+      valueType: typeof content
+    }
+  });
+}
+async function resolveUrlContent(url, options) {
+  if (url.protocol === "data:") {
+    const parsed = parseDataUrl(url.toString());
+    return {
+      mediaType: resolveMediaType("", options, parsed.mediaType),
+      filename: options.filename,
+      source: {
+        type: "base64",
+        data: parsed.base64Data
+      }
+    };
+  }
+  if (url.protocol === "file:") {
+    const filePath = fileURLToPath(url);
+    const buffer = await readFile(filePath);
+    return {
+      mediaType: resolveMediaType(filePath, options),
+      filename: options.filename ?? path.basename(filePath),
+      source: {
+        type: "base64",
+        data: buffer.toString("base64")
+      }
+    };
+  }
+  if (url.protocol === "http:" || url.protocol === "https:") {
+    return {
+      mediaType: resolveMediaType(url.pathname, options),
+      filename: options.filename ?? inferFilename(url.pathname),
+      source: {
+        type: "url",
+        url: url.toString()
+      }
+    };
+  }
+  throw new AgentBoxError(
+    `Unsupported input URL protocol "${url.protocol}" for ${options.kind} parts.`,
+    {
+      code: "UNSUPPORTED_INPUT_SOURCE",
+      details: {
+        kind: options.kind,
+        protocol: url.protocol
+      }
+    }
+  );
+}
+function resolveMediaType(pathname, options, parsedMediaType) {
+  const explicitMediaType = options.mediaType ?? parsedMediaType;
+  if (explicitMediaType) {
+    return explicitMediaType;
+  }
+  const inferredMediaType = inferMediaType(pathname);
+  if (inferredMediaType) {
+    return inferredMediaType;
+  }
+  throw new AgentBoxError(
+    `Could not determine a media type for the ${options.kind} input part.`,
+    {
+      code: "MISSING_INPUT_MEDIA_TYPE",
+      details: {
+        kind: options.kind,
+        pathname
+      }
+    }
+  );
+}
+function inferMediaType(pathname) {
+  const extension = path.extname(pathname).toLowerCase();
+  return FILE_MEDIA_TYPE_BY_EXTENSION[extension];
+}
+function inferFilename(pathname) {
+  const name = path.basename(pathname);
+  return name && name !== "." ? name : void 0;
+}
+function parseStructuredUrl(value) {
+  if (!/^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(value)) {
+    return null;
+  }
+  try {
+    return new URL(value);
+  } catch {
+    return null;
+  }
+}
+function parseDataUrl(value) {
+  const separatorIndex = value.indexOf(",");
+  if (separatorIndex === -1) {
+    throw new AgentBoxError("Invalid data URL input.", {
+      code: "INVALID_INPUT_DATA_URL"
+    });
+  }
+  const header = value.slice(5, separatorIndex);
+  const body = value.slice(separatorIndex + 1);
+  const mediaType = header.split(";")[0] || void 0;
+  const isBase64 = header.includes(";base64");
+  return {
+    mediaType,
+    base64Data: isBase64 ? body : Buffer.from(decodeURIComponent(body), "utf8").toString("base64")
+  };
+}
+function binarySourceToUrl(source, mediaType) {
+  return source.type === "url" ? source.url : `data:${mediaType};base64,${source.data}`;
+}
+function dataUrlToBase64(value) {
+  return parseDataUrl(value).base64Data;
+}
+function isRemoteUrl(value) {
+  return value.startsWith("http://") || value.startsWith("https://");
+}
+function isClaudeTextLikeMediaType(mediaType) {
+  return mediaType.startsWith("text/") || CLAUDE_TEXT_LIKE_MEDIA_TYPES.has(mediaType);
+}
+
+// src/agents/config/commands.ts
+import path2 from "path";
+function buildFrontmatter(values) {
+  const lines = Object.entries(values).filter(([, value]) => value !== void 0).map(([key, value]) => `${key}: ${JSON.stringify(value)}`);
+  return lines.length > 0 ? `---
+${lines.join("\n")}
+---
+
+` : "";
+}
+function buildClaudeCommandArtifacts(commands, layout) {
+  return (commands ?? []).map((command) => ({
+    path: path2.join(layout.claudeDir, "commands", `${command.name}.md`),
+    content: buildFrontmatter({
+      description: command.description
+    }) + command.template
+  }));
+}
+function buildOpenCodeCommandsConfig(commands) {
+  if (!commands || commands.length === 0) {
+    return void 0;
+  }
+  return Object.fromEntries(
+    commands.map((command) => [
+      command.name,
+      {
+        template: command.template,
+        ...command.description ? { description: command.description } : {},
+        ...command.agent ? { agent: command.agent } : {},
+        ...command.model ? { model: command.model } : {},
+        ...command.subtask !== void 0 ? { subtask: command.subtask } : {}
+      }
+    ])
+  );
+}
+function assertCommandsSupported(provider, commands) {
+  if (!commands || commands.length === 0) {
+    return;
+  }
+  if (provider === AgentProvider.Codex) {
+    throw new Error(
+      "Custom commands are not supported for Codex in this package yet."
+    );
+  }
+}
+
+// src/agents/config/hooks.ts
+import path3 from "path";
+function hasHookEntries(hooks) {
+  if (!hooks || typeof hooks !== "object") {
+    return false;
+  }
+  return Object.values(hooks).some(
+    (groups) => Array.isArray(groups) && groups.length > 0
+  );
+}
+function readTopLevelHooks(options) {
+  if (!options || typeof options !== "object" || !("hooks" in options)) {
+    return void 0;
+  }
+  return options.hooks;
+}
+function readProviderHooks(options) {
+  if (!options || typeof options !== "object" || !("provider" in options)) {
+    return void 0;
+  }
+  return options.provider?.hooks;
+}
+function readProviderPlugins(options) {
+  if (!options || typeof options !== "object" || !("provider" in options)) {
+    return void 0;
+  }
+  return options.provider?.plugins;
+}
+function legacySharedHooksError(provider) {
+  return provider === AgentProvider.OpenCode ? "OpenCode hook plugins must be configured on options.provider.plugins. The shared options.hooks field was removed because hook semantics differ by provider." : `${provider === AgentProvider.ClaudeCode ? "Claude Code" : "Codex"} hooks must be configured on options.provider.hooks. The shared options.hooks field was removed because hook semantics differ by provider.`;
+}
+function invalidGroupedHooksShapeError(provider) {
+  return `${provider === AgentProvider.ClaudeCode ? "Claude Code" : "Codex"} hooks must use the native grouped hooks object shape under options.provider.hooks, with each event mapped to an array of matcher groups.`;
+}
+function hasMalformedGroupedHookEntries(hooks) {
+  return Object.values(hooks).some(
+    (groups) => groups !== void 0 && !Array.isArray(groups)
+  );
+}
+function opencodeHooksFieldError() {
+  return "OpenCode uses options.provider.plugins for native hook support. options.provider.hooks is not supported for opencode.";
+}
+function unexpectedPluginsFieldError(provider) {
+  return `OpenCode plugins are only supported for the opencode provider in this package. Configure them on options.provider.plugins for opencode; received plugin configuration for ${provider}.`;
+}
+function buildClaudeHookSettings(hooks) {
+  if (!hasHookEntries(hooks)) {
+    return void 0;
+  }
+  return { hooks };
+}
+function buildCodexHooksFile(hooks) {
+  if (!hasHookEntries(hooks)) {
+    return void 0;
+  }
+  return { hooks };
+}
+function toPluginFileName(name, extension) {
+  const base = name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return `${base || "agentbox-plugin"}.${extension}`;
+}
+function toPluginExportName(name) {
+  const base = name.replace(/[^a-zA-Z0-9]+/g, " ").trim();
+  const parts = base.split(/\s+/).filter(Boolean).map((part) => part[0].toUpperCase() + part.slice(1));
+  const identifier = parts.join("") || "AgentBoxPlugin";
+  return /^[A-Za-z_]/.test(identifier) ? identifier : `AgentBoxPlugin${identifier}`;
+}
+function indentBlock(input, spaces) {
+  const indent = " ".repeat(spaces);
+  return input.split("\n").map((line) => `${indent}${line}`).join("\n");
+}
+function renderOpenCodePluginHook(hook) {
+  const body = hook.body.trim().length > 0 ? hook.body.trim() : "return undefined;";
+  return [
+    `    ${JSON.stringify(hook.event)}: async (input, output) => {`,
+    indentBlock(body, 6),
+    "    },"
+  ].join("\n");
+}
+function buildOpenCodePluginSource(plugin) {
+  const exportName = toPluginExportName(plugin.name);
+  const setup = plugin.setup?.trim();
+  const preamble = plugin.preamble?.trim();
+  return [
+    ...preamble ? [preamble, ""] : [],
+    `export const ${exportName} = async (ctx) => {`,
+    ...setup ? [indentBlock(setup, 2)] : [],
+    "  return {",
+    ...plugin.hooks.map((hook) => renderOpenCodePluginHook(hook)),
+    "  };",
+    "};",
+    "",
+    `export default ${exportName};`,
+    ""
+  ].join("\n");
+}
+function buildOpenCodePluginArtifacts(plugins, opencodeDir) {
+  if (!plugins || plugins.length === 0) {
+    return [];
+  }
+  const seenFileNames = /* @__PURE__ */ new Set();
+  return plugins.map((plugin) => {
+    const fileExtension = plugin.fileExtension ?? "ts";
+    const fileName = toPluginFileName(plugin.name, fileExtension);
+    if (seenFileNames.has(fileName)) {
+      throw new Error(
+        `OpenCode plugin names must be unique after normalization. Duplicate plugin file: ${fileName}`
+      );
+    }
+    seenFileNames.add(fileName);
+    return {
+      path: path3.join(opencodeDir, "plugins", fileName),
+      content: buildOpenCodePluginSource(plugin)
+    };
+  });
+}
+function assertHooksSupported(provider, options) {
+  const topLevelHooks = readTopLevelHooks(options);
+  if (topLevelHooks !== void 0) {
+    throw new Error(legacySharedHooksError(provider));
+  }
+  const providerHooks = readProviderHooks(options);
+  const providerPlugins = readProviderPlugins(options);
+  if (provider === AgentProvider.OpenCode) {
+    if (providerHooks !== void 0) {
+      throw new Error(opencodeHooksFieldError());
+    }
+    if (providerPlugins === void 0) {
+      return void 0;
+    }
+    if (!Array.isArray(providerPlugins)) {
+      throw new Error(
+        "OpenCode plugins must be configured as an array on options.provider.plugins."
+      );
+    }
+    return providerPlugins.length > 0 ? providerPlugins : void 0;
+  }
+  if (providerPlugins !== void 0) {
+    throw new Error(unexpectedPluginsFieldError(provider));
+  }
+  if (providerHooks === void 0) {
+    return void 0;
+  }
+  if (!providerHooks || typeof providerHooks !== "object" || Array.isArray(providerHooks)) {
+    throw new Error(invalidGroupedHooksShapeError(provider));
+  }
+  if (hasMalformedGroupedHookEntries(providerHooks)) {
+    throw new Error(invalidGroupedHooksShapeError(provider));
+  }
+  if (!hasHookEntries(providerHooks)) {
+    return void 0;
+  }
+  return providerHooks;
+}
+
+// src/agents/config/mcp.ts
+var SAFE_TOML_KEY = /^[a-zA-Z0-9_-]+$/;
+function assertSafeTomlKey(name, context) {
+  if (!SAFE_TOML_KEY.test(name)) {
+    throw new Error(
+      `${context} name ${JSON.stringify(name)} contains characters that are not safe for TOML keys. Use only alphanumeric characters, hyphens, and underscores.`
+    );
+  }
+}
+function tomlString(value) {
+  return JSON.stringify(value);
+}
+function tomlStringArray(values) {
+  return `[${values.map(tomlString).join(", ")}]`;
+}
+function buildClaudeMcpConfig(mcps) {
+  if (!mcps || mcps.length === 0) {
+    return void 0;
+  }
+  const mcpServers = Object.fromEntries(
+    mcps.filter((mcp) => mcp.enabled !== false).map((mcp) => {
+      if (mcp.type === "remote") {
+        const headers = {
+          ...mcp.headers ?? {},
+          ...mcp.bearerTokenEnvVar ? {
+            Authorization: `Bearer \${${mcp.bearerTokenEnvVar}}`
+          } : {}
+        };
+        return [
+          mcp.name,
+          {
+            type: "http",
+            url: mcp.url,
+            ...Object.keys(headers).length > 0 ? { headers } : {}
+          }
+        ];
+      }
+      return [
+        mcp.name,
+        {
+          type: "stdio",
+          command: mcp.command,
+          ...mcp.args?.length ? { args: mcp.args } : {},
+          ...mcp.env ? { env: mcp.env } : {}
+        }
+      ];
+    })
+  );
+  return JSON.stringify({ mcpServers }, null, 2);
+}
+function buildOpenCodeMcpConfig(mcps) {
+  if (!mcps || mcps.length === 0) {
+    return void 0;
+  }
+  return Object.fromEntries(
+    mcps.filter((mcp) => mcp.enabled !== false).map((mcp) => {
+      if (mcp.type === "remote") {
+        const headers = {
+          ...mcp.headers ?? {},
+          ...mcp.bearerTokenEnvVar ? { Authorization: `Bearer {env:${mcp.bearerTokenEnvVar}}` } : {}
+        };
+        return [
+          mcp.name,
+          {
+            type: "remote",
+            url: mcp.url,
+            enabled: true,
+            ...Object.keys(headers).length > 0 ? { headers } : {}
+          }
+        ];
+      }
+      return [
+        mcp.name,
+        {
+          type: "local",
+          command: [mcp.command, ...mcp.args ?? []],
+          enabled: true,
+          ...mcp.env ? { env: mcp.env } : {}
+        }
+      ];
+    })
+  );
+}
+function buildCodexConfigToml(opts = {}) {
+  const {
+    mcps,
+    agentSections = [],
+    enableHooks = false,
+    enableSkills = false,
+    enableMultiAgent = false,
+    openAiBaseUrl
+  } = opts;
+  const blocks = [];
+  if (openAiBaseUrl) {
+    blocks.push(`openai_base_url = ${tomlString(openAiBaseUrl)}`);
+    blocks.push("");
+  }
+  for (const mcp of mcps ?? []) {
+    if (mcp.enabled === false) {
+      continue;
+    }
+    assertSafeTomlKey(mcp.name, "MCP server");
+    if (mcp.type === "remote") {
+      if (mcp.headers && Object.keys(mcp.headers).length > 0) {
+        throw new Error(
+          `Codex only supports remote MCPs with bearerTokenEnvVar in this package. MCP "${mcp.name}" includes raw headers.`
+        );
+      }
+      blocks.push(`[mcp_servers.${mcp.name}]`);
+      blocks.push(`url = ${tomlString(mcp.url)}`);
+      if (mcp.bearerTokenEnvVar) {
+        blocks.push(
+          `bearer_token_env_var = ${tomlString(mcp.bearerTokenEnvVar)}`
+        );
+      }
+      blocks.push("");
+      continue;
+    }
+    blocks.push(`[mcp_servers.${mcp.name}]`);
+    blocks.push(`command = ${tomlString(mcp.command)}`);
+    if (mcp.args?.length) {
+      blocks.push(`args = ${tomlStringArray(mcp.args)}`);
+    }
+    if (mcp.env && Object.keys(mcp.env).length > 0) {
+      blocks.push(`env_vars = ${tomlStringArray(Object.keys(mcp.env))}`);
+    }
+    blocks.push("");
+  }
+  const featureLines = [];
+  if (enableHooks) featureLines.push("codex_hooks = true");
+  if (enableSkills) featureLines.push("skills = true");
+  if (enableMultiAgent) featureLines.push("multi_agent = true");
+  if (featureLines.length > 0) {
+    blocks.push("[features]");
+    blocks.push(...featureLines);
+    blocks.push("");
+  }
+  blocks.push(...agentSections);
+  if (blocks.length === 0) {
+    return void 0;
+  }
+  return `${blocks.join("\n").trim()}
+`;
+}
+
+// src/agents/config/setup.ts
+import { mkdir, chmod, rm, writeFile } from "fs/promises";
+import os from "os";
+import path4 from "path";
+
+// src/agents/transports/spawn.ts
+import { spawn } from "child_process";
+import { createInterface } from "readline";
+function spawnCommand(options) {
+  const child = spawn(options.command, options.args ?? [], {
+    cwd: options.cwd,
+    env: options.env,
+    stdio: "pipe",
+    shell: process.platform === "win32",
+    windowsHide: true
+  });
+  const exitPromise = new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("close", (code) => resolve(code ?? 0));
+  });
+  return {
+    child,
+    wait: () => exitPromise,
+    kill: async (signal = "SIGTERM") => {
+      child.kill(signal);
+      await exitPromise.catch(() => void 0);
+    }
+  };
+}
+async function waitForHttpReady(url, options) {
+  await waitFor(
+    async () => {
+      try {
+        const response = await fetch(url, options?.init);
+        return response.ok;
+      } catch {
+        return false;
+      }
+    },
+    {
+      timeoutMs: options?.timeoutMs,
+      intervalMs: options?.intervalMs
+    }
+  );
+}
+async function* linesFromNodeStream(stream) {
+  const lineReader = createInterface({ input: stream });
+  try {
+    for await (const line of lineReader) {
+      yield line;
+    }
+  } finally {
+    lineReader.close();
+  }
+}
+
+// src/agents/config/setup.ts
+function shortLabel(command) {
+  const oneLine = command.replace(/\s+/g, " ").trim();
+  return oneLine.length > 60 ? `${oneLine.slice(0, 60)}\u2026` : oneLine;
+}
+function agentboxRoot(provider, hasSandbox) {
+  return hasSandbox ? `/tmp/agentbox/${provider}` : path4.join(os.tmpdir(), `agentbox-${provider}`);
+}
+function buildLayout(rootDir) {
+  const xdgConfigHome = path4.join(rootDir, ".config");
+  return {
+    rootDir,
+    homeDir: rootDir,
+    xdgConfigHome,
+    agentsDir: path4.join(rootDir, ".agents"),
+    claudeDir: path4.join(rootDir, ".claude"),
+    opencodeDir: path4.join(xdgConfigHome, "opencode"),
+    codexDir: path4.join(rootDir, ".codex")
+  };
+}
+function buildLayoutEnv(provider, layout) {
+  switch (provider) {
+    case "claude-code":
+      return { CLAUDE_CONFIG_DIR: layout.claudeDir };
+    case "codex":
+      return { CODEX_HOME: layout.codexDir };
+    case "open-code":
+      return {
+        OPENCODE_CONFIG: path4.join(layout.opencodeDir, "agentbox.json"),
+        OPENCODE_CONFIG_DIR: layout.opencodeDir
+      };
+  }
+}
+var HostSetupTarget = class {
+  constructor(provider, layout, cwd, baseEnv) {
+    this.provider = provider;
+    this.layout = layout;
+    this.cwd = cwd;
+    this.baseEnv = baseEnv;
+    this.env = buildLayoutEnv(provider, layout);
+  }
+  provider;
+  layout;
+  cwd;
+  baseEnv;
+  env;
+  /**
+   * Host implementation: write each artifact directly to the local
+   * filesystem (we're already on the box), then run the command via
+   * `sh -c`. No tarball needed since there's no RPC to amortize.
+   */
+  async uploadAndRun(files, command) {
+    return time(
+      debugRuntime,
+      `host uploadAndRun ${shortLabel(command)}`,
+      async () => {
+        await Promise.all(
+          files.map(async (entry) => {
+            await mkdir(path4.dirname(entry.path), { recursive: true });
+            const content = typeof entry.content === "string" ? entry.content : entry.content;
+            await writeFile(entry.path, content);
+            if (entry.mode && (entry.mode & 73) !== 0) {
+              await chmod(entry.path, entry.mode);
+            }
+          })
+        );
+        const handle = spawnCommand({
+          command: "sh",
+          args: ["-c", command],
+          cwd: this.cwd,
+          env: {
+            ...process.env,
+            ...this.baseEnv,
+            ...this.env
+          }
+        });
+        const exitCode = await handle.wait();
+        return {
+          exitCode,
+          stdout: "",
+          stderr: "",
+          combinedOutput: ""
+        };
+      },
+      (result) => ({ exit: result.exitCode, files: files.length })
+    );
+  }
+  async runCommand(command, extraEnv) {
+    await time(
+      debugRuntime,
+      `host runCommand ${shortLabel(command)}`,
+      async () => {
+        const handle = spawnCommand({
+          command: process.env.SHELL || "sh",
+          args: ["-c", command],
+          cwd: this.cwd,
+          env: {
+            ...process.env,
+            ...this.baseEnv,
+            ...this.env,
+            ...extraEnv ?? {}
+          }
+        });
+        const exitCode = await handle.wait();
+        if (exitCode !== 0) {
+          throw new Error(`Setup command failed (${exitCode}): ${command}`);
+        }
+      }
+    );
+  }
+  async cleanup() {
+    await rm(this.layout.rootDir, { recursive: true, force: true });
+  }
+};
+var SandboxSetupTarget = class {
+  constructor(provider, layout, options) {
+    this.provider = provider;
+    this.layout = layout;
+    this.options = options;
+    this.env = buildLayoutEnv(provider, layout);
+  }
+  provider;
+  layout;
+  options;
+  env;
+  /**
+   * Sandbox implementation: delegate to `Sandbox.uploadAndRun` so the
+   * tarball + extract + exec all happen in a single Modal RPC. This is
+   * the hot path used by `applyDifferentialSetup`.
+   */
+  async uploadAndRun(files, command) {
+    const sandbox = this.options.sandbox;
+    if (!sandbox) {
+      throw new Error(
+        "SandboxSetupTarget.uploadAndRun called without a sandbox."
+      );
+    }
+    return time(
+      debugRuntime,
+      `sandbox uploadAndRun ${shortLabel(command)}`,
+      () => sandbox.uploadAndRun(files, command, {
+        cwd: this.options.cwd,
+        env: {
+          ...this.options.env ?? {},
+          ...this.env
+        }
+      }),
+      (result) => ({ exit: result.exitCode, files: files.length })
+    );
+  }
+  async runCommand(command, extraEnv) {
+    await time(
+      debugRuntime,
+      `sandbox runCommand ${shortLabel(command)}`,
+      async () => {
+        const result = await this.options.sandbox?.run(command, {
+          cwd: this.options.cwd,
+          env: {
+            ...this.options.env ?? {},
+            ...this.env,
+            ...extraEnv ?? {}
+          }
+        });
+        if (result && result.exitCode !== 0) {
+          throw new Error(
+            `Sandbox setup command failed (${result.exitCode}): ${command}`
+          );
+        }
+      }
+    );
+  }
+  async cleanup() {
+  }
+};
+async function createSetupTarget(provider, setupId, options) {
+  return time(debugRuntime, `createSetupTarget ${provider}`, async () => {
+    void setupId;
+    const layout = buildLayout(
+      agentboxRoot(provider, Boolean(options.sandbox))
+    );
+    if (options.sandbox) {
+      return new SandboxSetupTarget(provider, layout, options);
+    }
+    await mkdir(layout.homeDir, { recursive: true });
+    await mkdir(layout.xdgConfigHome, { recursive: true });
+    await mkdir(layout.agentsDir, { recursive: true });
+    await mkdir(layout.claudeDir, { recursive: true });
+    await mkdir(layout.opencodeDir, { recursive: true });
+    await mkdir(layout.codexDir, { recursive: true });
+    return new HostSetupTarget(
+      provider,
+      layout,
+      options.cwd ?? process.cwd(),
+      options.env ?? {}
+    );
+  });
+}
+
+// src/agents/config/setup-manifest.ts
+import { createHash } from "crypto";
+import path5 from "path";
+var MANIFEST_FILENAME = "setup-manifest.json";
+var TARGET_MANIFEST_FILENAME = "setup-target.json";
+var INSTALL_SCRIPT_FILENAME = "install.sh";
+var MANIFEST_VERSION = 1;
+function hashArtifact(artifact) {
+  const hasher = createHash("sha256");
+  hasher.update(artifact.executable ? "1" : "0");
+  hasher.update("\0");
+  hasher.update(artifact.content, "utf8");
+  return hasher.digest("hex");
+}
+function hashCommand(command) {
+  return createHash("sha256").update(command, "utf8").digest("hex");
+}
+function computeTargetArtifacts(artifacts) {
+  const result = {};
+  for (const artifact of artifacts) {
+    result[artifact.path] = hashArtifact(artifact);
+  }
+  return result;
+}
+function buildInstallScript(rootDir, installCommandsByKey) {
+  const commandsB64 = Buffer.from(
+    JSON.stringify(installCommandsByKey),
+    "utf8"
+  ).toString("base64");
+  return `#!/usr/bin/env bash
+set -e
+ROOT_DIR=${shellQuote(rootDir)}
+TARGET_MANIFEST="$ROOT_DIR/${TARGET_MANIFEST_FILENAME}"
+EXISTING_MANIFEST="$ROOT_DIR/${MANIFEST_FILENAME}"
+export TARGET_MANIFEST EXISTING_MANIFEST
+
+# Compute stale commands: any command whose hash in the target manifest
+# differs from (or is missing in) the existing manifest. The python block
+# emits the commands themselves, NUL-separated, so bash never has to
+# deserialize JSON.
+STALE_CMDS_FILE="$(mktemp)"
+trap 'rm -f "$STALE_CMDS_FILE"' EXIT
+COMMANDS_B64=${shellQuote(commandsB64)} \\
+MANIFEST_VERSION=${MANIFEST_VERSION} \\
+python3 - <<'PY' > "$STALE_CMDS_FILE"
+import base64, json, os, sys
+with open(os.environ["TARGET_MANIFEST"], "r", encoding="utf-8") as fh:
+    target = json.load(fh)
+existing = {}
+try:
+    with open(os.environ["EXISTING_MANIFEST"], "r", encoding="utf-8") as fh:
+        existing = json.load(fh)
+except FileNotFoundError:
+    pass
+expected_version = int(os.environ["MANIFEST_VERSION"])
+target_cmds = target.get("installCommands", {})
+existing_cmds = (
+    existing.get("installCommands", {})
+    if existing.get("version") == expected_version
+    else {}
+)
+commands = json.loads(base64.b64decode(os.environ["COMMANDS_B64"]))
+stale = [
+    commands[key]
+    for key, hashed in target_cmds.items()
+    if commands.get(key) is not None and existing_cmds.get(key) != hashed
+]
+sys.stdout.write("\\0".join(stale))
+PY
+
+if [ -s "$STALE_CMDS_FILE" ]; then
+  while IFS= read -r -d '' CMD; do
+    [ -z "$CMD" ] && continue
+    bash -c "$CMD" &
+  done < "$STALE_CMDS_FILE"
+  wait
+fi
+
+# Persist target manifest as the new manifest atomically. Doing this last
+# means an interrupted install run doesn't poison the cache for next time.
+mv "$TARGET_MANIFEST" "$EXISTING_MANIFEST"
+`;
+}
+async function applyDifferentialSetup(target, artifacts, installCommands) {
+  await time(
+    debugSetup,
+    `applyDifferentialSetup ${target.provider}`,
+    async () => {
+      const installCommandsByKey = {};
+      for (let i = 0; i < installCommands.length; i++) {
+        installCommandsByKey[`cmd${i}`] = installCommands[i];
+      }
+      const targetForSandbox = {
+        version: MANIFEST_VERSION,
+        artifacts: computeTargetArtifacts(artifacts),
+        installCommands: Object.fromEntries(
+          Object.entries(installCommandsByKey).map(([key, command]) => [
+            key,
+            hashCommand(command)
+          ])
+        )
+      };
+      const rootDir = target.layout.rootDir;
+      const tarballEntries = [
+        ...artifacts.map((artifact) => ({
+          path: artifact.path,
+          content: artifact.content,
+          mode: artifact.executable ? 493 : 420
+        })),
+        {
+          path: path5.posix.join(rootDir, TARGET_MANIFEST_FILENAME),
+          content: JSON.stringify(targetForSandbox),
+          mode: 420
+        },
+        {
+          path: path5.posix.join(rootDir, INSTALL_SCRIPT_FILENAME),
+          content: buildInstallScript(rootDir, installCommandsByKey),
+          mode: 493
+        }
+      ];
+      await target.uploadAndRun(
+        tarballEntries,
+        `bash ${shellQuote(path5.posix.join(rootDir, INSTALL_SCRIPT_FILENAME))}`
+      );
+    },
+    () => ({
+      artifacts: artifacts.length,
+      installCommands: installCommands.length
+    })
+  );
+}
+
+// src/agents/config/skills.ts
+import path6 from "path";
+function getSkillTargetDir(provider, layout, skillName) {
+  switch (provider) {
+    case AgentProvider.ClaudeCode:
+      return path6.join(layout.claudeDir, "skills", skillName);
+    case AgentProvider.OpenCode:
+      return path6.join(layout.opencodeDir, "skills", skillName);
+    case AgentProvider.Codex:
+      return path6.join(layout.codexDir, "skills", skillName);
+  }
+}
+function skillsCliAgentName(provider) {
+  return provider === AgentProvider.OpenCode ? "opencode" : provider;
+}
+function buildSkillsInstallerCommand(provider, skill) {
+  const repo = skill.repo ?? "https://github.com/anthropics/skills";
+  return `npx skills add ${shellQuote(repo)} -g --skill ${shellQuote(skill.name)} --agent ${shellQuote(skillsCliAgentName(provider))} -y`;
+}
+async function prepareSkillArtifacts(provider, skills, layout) {
+  const artifacts = [];
+  const installCommands = [];
+  const preparedSkills = [];
+  for (const skill of skills ?? []) {
+    const targetDir = getSkillTargetDir(provider, layout, skill.name);
+    const skillFilePath = path6.join(targetDir, "SKILL.md");
+    if (!("files" in skill)) {
+      installCommands.push(buildSkillsInstallerCommand(provider, skill));
+      preparedSkills.push({ name: skill.name, skillFilePath });
+      continue;
+    }
+    for (const [relativePath, content] of Object.entries(skill.files)) {
+      artifacts.push({
+        path: path6.join(targetDir, relativePath),
+        content,
+        executable: relativePath.startsWith("scripts/")
+      });
+    }
+    preparedSkills.push({ name: skill.name, skillFilePath });
+  }
+  return {
+    artifacts,
+    installCommands,
+    preparedSkills
+  };
+}
+
+// src/agents/config/subagents.ts
+import path7 from "path";
+function toToolsArray(tools) {
+  const filtered = tools?.map((tool) => tool.trim()).filter(Boolean);
+  return filtered && filtered.length > 0 ? filtered : void 0;
+}
+function tomlString2(value) {
+  return JSON.stringify(value);
+}
+function yamlScalar(value) {
+  return `'${value.replace(/'/g, "''")}'`;
+}
+function buildClaudeSubagentArtifacts(subAgents, layout) {
+  if (!subAgents || subAgents.length === 0) {
+    return [];
+  }
+  return subAgents.map((subAgent) => {
+    const tools = toToolsArray(subAgent.tools);
+    const frontmatterLines = [
+      `name: ${yamlScalar(subAgent.name)}`,
+      `description: ${yamlScalar(subAgent.description)}`,
+      ...subAgent.model ? [`model: ${yamlScalar(subAgent.model)}`] : [],
+      ...tools ? [`tools: ${tools.join(", ")}`] : []
+    ];
+    const content = `---
+${frontmatterLines.join("\n")}
+---
+
+${subAgent.instructions.trim()}
+`;
+    return {
+      path: path7.join(layout.claudeDir, "agents", `${subAgent.name}.md`),
+      content
+    };
+  });
+}
+function mapOpenCodeTools(tools) {
+  if (!tools || tools.length === 0) {
+    return void 0;
+  }
+  return Object.fromEntries(tools.map((tool) => [tool, true]));
+}
+function buildOpenCodeSubagentConfig(subAgents) {
+  return Object.fromEntries(
+    (subAgents ?? []).map((subAgent) => [
+      subAgent.name,
+      {
+        mode: "subagent",
+        description: subAgent.description,
+        prompt: subAgent.instructions,
+        ...mapOpenCodeTools(subAgent.tools) ? { tools: mapOpenCodeTools(subAgent.tools) } : {}
+      }
+    ])
+  );
+}
+function buildCodexSubagentArtifacts(subAgents, layout) {
+  const artifacts = [];
+  const agentSections = [];
+  for (const subAgent of subAgents ?? []) {
+    const roleConfigRelativePath = `./agents/${subAgent.name}.toml`;
+    const roleConfigPromptPath = `../prompts/${subAgent.name}.md`;
+    artifacts.push({
+      path: path7.join(layout.codexDir, "prompts", `${subAgent.name}.md`),
+      content: subAgent.instructions
+    });
+    const tomlLines = [
+      `model_instructions_file = ${tomlString2(roleConfigPromptPath)}`
+    ];
+    if (subAgent.model) {
+      tomlLines.push(`model = ${tomlString2(subAgent.model)}`);
+    }
+    tomlLines.push(
+      `model_reasoning_effort = ${tomlString2("medium")}`,
+      "",
+      "[features]",
+      "multi_agent = false",
+      ""
+    );
+    artifacts.push({
+      path: path7.join(layout.codexDir, "agents", `${subAgent.name}.toml`),
+      content: tomlLines.join("\n")
+    });
+    agentSections.push(
+      `[agents.${subAgent.name}]`,
+      `description = ${tomlString2(subAgent.description)}`,
+      `config_file = ${tomlString2(roleConfigRelativePath)}`,
+      ""
+    );
+  }
+  return {
+    artifacts,
+    agentSections,
+    enableMultiAgent: (subAgents?.length ?? 0) > 0
+  };
+}
+
+// src/agents/cost.ts
+function addIfNumber(target, key, value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return;
+  }
+  target[key] = (target[key] ?? 0) + value;
+}
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function mergeUsage(target, source) {
+  if (!source) {
+    return;
+  }
+  addIfNumber(target, "input_tokens", source.input_tokens);
+  addIfNumber(target, "input_tokens", source.inputTokens);
+  addIfNumber(target, "input_tokens", source.input);
+  addIfNumber(target, "output_tokens", source.output_tokens);
+  addIfNumber(target, "output_tokens", source.outputTokens);
+  addIfNumber(target, "output_tokens", source.output);
+  addIfNumber(
+    target,
+    "cache_read_input_tokens",
+    source.cache_read_input_tokens
+  );
+  addIfNumber(target, "cache_read_input_tokens", source.cached_input_tokens);
+  addIfNumber(target, "cache_read_input_tokens", source.cachedInputTokens);
+  addIfNumber(
+    target,
+    "cache_creation_input_tokens",
+    source.cache_creation_input_tokens
+  );
+  addIfNumber(target, "cache_creation_input_tokens", source.cacheWrite);
+  const cache = asRecord(source.cache);
+  if (cache) {
+    addIfNumber(target, "cache_read_input_tokens", cache.read);
+    addIfNumber(target, "cache_creation_input_tokens", cache.write);
+  }
+}
+function compactCostData(costData) {
+  const usage = costData.usage ? Object.fromEntries(
+    Object.entries(costData.usage).filter(([, value]) => value !== 0)
+  ) : void 0;
+  const compacted = {
+    ...costData.total_cost_usd !== void 0 ? { total_cost_usd: costData.total_cost_usd } : {},
+    ...costData.duration_ms !== void 0 ? { duration_ms: costData.duration_ms } : {},
+    ...costData.duration_api_ms !== void 0 ? { duration_api_ms: costData.duration_api_ms } : {},
+    ...costData.num_turns !== void 0 ? { num_turns: costData.num_turns } : {},
+    ...usage && Object.keys(usage).length > 0 ? { usage } : {}
+  };
+  return Object.keys(compacted).length > 0 ? compacted : null;
+}
+function extractClaudeCostData(events) {
+  for (let i = events.length - 1; i >= 0; i--) {
+    const event = events[i];
+    if (!event) {
+      continue;
+    }
+    if (event.type !== "result") {
+      continue;
+    }
+    const totalCost = typeof event.total_cost_usd === "number" ? event.total_cost_usd : void 0;
+    const usage = {};
+    const modelUsage = asRecord(event.modelUsage);
+    if (modelUsage) {
+      for (const value of Object.values(modelUsage)) {
+        mergeUsage(usage, asRecord(value));
+      }
+    }
+    return compactCostData({
+      ...totalCost !== void 0 ? { total_cost_usd: totalCost } : {},
+      duration_ms: typeof event.duration_ms === "number" ? event.duration_ms : void 0,
+      duration_api_ms: typeof event.duration_api_ms === "number" ? event.duration_api_ms : void 0,
+      num_turns: typeof event.num_turns === "number" ? event.num_turns : void 0,
+      usage
+    });
+  }
+  return null;
+}
+function extractCodexCostData(events) {
+  const usage = {};
+  let sawUsage = false;
+  for (const event of events) {
+    const params = asRecord(event.params);
+    const usageCandidate = asRecord(event.usage) ?? asRecord(params?.usage) ?? asRecord(params?.tokenUsage) ?? asRecord(asRecord(params?.turn)?.usage) ?? asRecord(asRecord(params?.turn)?.tokenUsage);
+    if (usageCandidate) {
+      sawUsage = true;
+      mergeUsage(usage, usageCandidate);
+    }
+  }
+  return sawUsage ? compactCostData({ usage }) : null;
+}
+function extractOpenCodeCostData(events) {
+  const usage = {};
+  let totalCost = 0;
+  let sawCostData = false;
+  for (const event of events) {
+    const properties = asRecord(event.properties);
+    const part = asRecord(properties?.part) ?? asRecord(event.part);
+    if (part?.type !== "step-finish") {
+      continue;
+    }
+    if (typeof part.cost === "number") {
+      totalCost += part.cost;
+      sawCostData = true;
+    }
+    const tokens = asRecord(part.tokens);
+    if (tokens) {
+      sawCostData = true;
+      mergeUsage(usage, tokens);
+    }
+  }
+  return sawCostData ? compactCostData({
+    ...totalCost > 0 ? { total_cost_usd: totalCost } : {},
+    usage
+  }) : null;
+}
+
+// src/agents/providers/claude-code.ts
+var DAEMON_PROTOCOL_VERSION = "1";
+var DAEMON_PORT = 43180;
+var DAEMON_PATH = "/tmp/agentbox/claude-code/daemon.mjs";
+var DAEMON_LOG_PATH = "/tmp/agentbox/claude-code/daemon.log";
+var DAEMON_PID_PATH = "/tmp/agentbox/claude-code/daemon.pid";
+function claudeConfigDir(options) {
+  return path8.join(
+    agentboxRoot(AgentProvider.ClaudeCode, Boolean(options.sandbox)),
+    ".claude"
+  );
+}
+function buildClaudeQueryOptions(params) {
+  const provider = params.request.options.provider;
+  const run = params.request.run;
+  const extraArgs = {
+    "mcp-config": params.mcpConfigPath
+  };
+  for (const arg of provider?.args ?? []) {
+    if (typeof arg !== "string") continue;
+    if (arg.startsWith("--")) {
+      extraArgs[arg.slice(2)] = null;
+    }
+  }
+  if (run.systemPrompt) {
+    extraArgs["append-system-prompt"] = run.systemPrompt;
+  }
+  return {
+    cwd: params.cwd ?? params.request.options.cwd,
+    env: params.env,
+    pathToClaudeCodeExecutable: provider?.binary ?? "claude",
+    settings: params.settingsPath,
+    extraArgs,
+    includePartialMessages: true,
+    ...run.model ? { model: run.model } : {},
+    ...run.reasoning ? { effort: run.reasoning } : {},
+    ...provider?.permissionMode ? { permissionMode: provider.permissionMode } : {},
+    ...provider?.permissionMode === "bypassPermissions" ? { allowDangerouslySkipPermissions: true } : {},
+    ...provider?.allowedTools?.length ? { allowedTools: provider.allowedTools } : {},
+    ...run.resumeSessionId ? { resume: run.resumeSessionId } : {}
+  };
+}
+function toRawEvent(runId, payload, type) {
+  return {
+    provider: AgentProvider.ClaudeCode,
+    runId,
+    type,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    payload
+  };
+}
+function extractAssistantText(message) {
+  const content = message.message?.content;
+  if (!Array.isArray(content)) return "";
+  return content.filter((block) => block.type === "text").map((block) => String(block.text ?? "")).join("");
+}
+function extractAssistantThinking(message) {
+  const content = message.message?.content;
+  if (!Array.isArray(content)) return "";
+  return content.filter(
+    (block) => block.type === "thinking" || block.type === "redacted_thinking"
+  ).map((block) => String(block.thinking ?? "")).filter(Boolean).join("");
+}
+function extractStreamDeltas(message) {
+  const event = message.event;
+  if (!event || event.type !== "content_block_delta") {
+    return { text: "", thinking: "" };
+  }
+  const delta = event.delta;
+  if (!delta) return { text: "", thinking: "" };
+  if (delta.type === "text_delta" && typeof delta.text === "string") {
+    return { text: delta.text, thinking: "" };
+  }
+  if (delta.type === "thinking_delta" && typeof delta.thinking === "string") {
+    return { text: "", thinking: delta.thinking };
+  }
+  return { text: "", thinking: "" };
+}
+function createClaudeCodeDaemonScript() {
+  const version = JSON.stringify(DAEMON_PROTOCOL_VERSION);
+  return `import http from "node:http";
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+const VERSION = ${version};
+const port = Number(process.argv[2] ?? "${DAEMON_PORT}");
+const liveRuns = new Map();
+
+// The SDK's default spawn does \`existsSync(pathToClaudeCodeExecutable)\`
+// before invoking child_process.spawn \u2014 that check fails on bare names
+// like "claude" because existsSync doesn't do PATH lookup. Resolve to an
+// absolute path once at daemon startup so the SDK is happy regardless of
+// what the host passes.
+function resolveClaudeBinary(hint) {
+  if (hint && (hint.includes("/") || hint.includes(String.fromCharCode(92)))) {
+    return hint;
+  }
+  const name = hint || "claude";
+  try {
+    const out = execSync("command -v " + name + " || which " + name, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (out && existsSync(out)) return out;
+  } catch {}
+  return name;
+}
+
+function createPromptStream() {
+  const queue = [];
+  let resolver = null;
+  let ended = false;
+  return {
+    [Symbol.asyncIterator]: async function* () {
+      while (true) {
+        if (queue.length > 0) { yield queue.shift(); continue; }
+        if (ended) return;
+        await new Promise((r) => { resolver = r; });
+      }
+    },
+    push(message) {
+      queue.push(message);
+      const r = resolver; resolver = null; r?.();
+    },
+    end() {
+      ended = true;
+      const r = resolver; resolver = null; r?.();
+    },
+  };
+}
+
+function readJsonBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let total = 0;
+    req.on("data", (c) => {
+      total += c.length;
+      if (total > 8 * 1024 * 1024) {
+        req.destroy(new Error("body too large"));
+        return;
+      }
+      chunks.push(c);
+    });
+    req.on("end", () => {
+      try {
+        const text = Buffer.concat(chunks).toString("utf8");
+        resolve(text ? JSON.parse(text) : {});
+      } catch (e) { reject(e); }
+    });
+    req.on("error", reject);
+  });
+}
+
+function autoApproveCanUseTool(_toolName, input) {
+  return { behavior: "allow", updatedInput: input };
+}
+
+async function handleStart(req, res, runId) {
+  let body;
+  try { body = await readJsonBody(req); }
+  catch (e) {
+    res.writeHead(400, { "content-type": "application/json" });
+    res.end(JSON.stringify({ error: String(e?.message ?? e) }));
+    return;
+  }
+  const { prompt, options } = body || {};
+  if (!prompt) {
+    res.writeHead(400);
+    res.end("missing prompt");
+    return;
+  }
+
+  const promptStream = createPromptStream();
+  promptStream.push(prompt);
+
+  res.writeHead(200, {
+    "content-type": "application/x-ndjson",
+    "transfer-encoding": "chunked",
+    "x-daemon-version": VERSION,
+  });
+
+  const opts = { ...(options || {}) };
+  const autoApprove = !!opts.autoApproveTools;
+  delete opts.autoApproveTools;
+  opts.pathToClaudeCodeExecutable = resolveClaudeBinary(
+    opts.pathToClaudeCodeExecutable,
+  );
+
+  let queryHandle;
+  try {
+    queryHandle = query({
+      prompt: promptStream,
+      options: {
+        ...opts,
+        ...(autoApprove ? { canUseTool: autoApproveCanUseTool } : {}),
+      },
+    });
+  } catch (e) {
+    res.write(JSON.stringify({ _error: String(e?.message ?? e) }) + "\\n");
+    res.end();
+    return;
+  }
+
+  liveRuns.set(runId, { query: queryHandle, prompt: promptStream });
+
+  // Client disconnected (e.g. host process killed) \u2192 tear down.
+  req.on("close", () => {
+    if (!liveRuns.has(runId)) return;
+    liveRuns.delete(runId);
+    promptStream.end();
+    queryHandle.interrupt().catch(() => {});
+  });
+
+  try {
+    for await (const message of queryHandle) {
+      res.write(JSON.stringify(message) + "\\n");
+      if (message.type === "result") break;
+    }
+  } catch (e) {
+    res.write(JSON.stringify({ _error: String(e?.message ?? e) }) + "\\n");
+  } finally {
+    liveRuns.delete(runId);
+    promptStream.end();
+    res.end();
+  }
+}
+
+async function handleSendMessage(req, res, runId) {
+  const run = liveRuns.get(runId);
+  if (!run) {
+    res.writeHead(404, { "content-type": "application/json" });
+    res.end(JSON.stringify({ error: "no such run" }));
+    return;
+  }
+  let body;
+  try { body = await readJsonBody(req); }
+  catch (e) {
+    res.writeHead(400);
+    res.end(String(e?.message ?? e));
+    return;
+  }
+  run.prompt.push({
+    type: "user",
+    message: { role: "user", content: body.content },
+    parent_tool_use_id: null,
+  });
+  res.writeHead(204);
+  res.end();
+}
+
+async function handleAbort(_req, res, runId) {
+  const run = liveRuns.get(runId);
+  if (!run) {
+    res.writeHead(404);
+    res.end();
+    return;
+  }
+  await run.query.interrupt().catch(() => {});
+  res.writeHead(204);
+  res.end();
+}
+
+async function handleDelete(_req, res, runId) {
+  const run = liveRuns.get(runId);
+  if (run) {
+    liveRuns.delete(runId);
+    run.prompt.end();
+    await run.query.interrupt().catch(() => {});
+  }
+  res.writeHead(204);
+  res.end();
+}
+
+const server = http.createServer((req, res) => {
+  if (req.method === "GET" && req.url === "/__version") {
+    res.writeHead(200, { "content-type": "text/plain" });
+    res.end(VERSION);
+    return;
+  }
+  const url = req.url ?? "";
+  let m;
+  if (req.method === "POST" && (m = url.match(/^\\/runs\\/([^/]+)\\/start$/))) {
+    handleStart(req, res, decodeURIComponent(m[1]));
+    return;
+  }
+  if (req.method === "POST" && (m = url.match(/^\\/runs\\/([^/]+)\\/sendMessage$/))) {
+    handleSendMessage(req, res, decodeURIComponent(m[1]));
+    return;
+  }
+  if (req.method === "POST" && (m = url.match(/^\\/runs\\/([^/]+)\\/abort$/))) {
+    handleAbort(req, res, decodeURIComponent(m[1]));
+    return;
+  }
+  if (req.method === "DELETE" && (m = url.match(/^\\/runs\\/([^/]+)$/))) {
+    handleDelete(req, res, decodeURIComponent(m[1]));
+    return;
+  }
+  res.writeHead(404, { "content-type": "text/plain" });
+  res.end("not found");
+});
+
+server.listen(port, "0.0.0.0", () => {
+  console.error("[claude-code-daemon] listening on :" + port + " v" + VERSION);
+});
+
+const shutdown = () => {
+  for (const r of liveRuns.values()) {
+    r.prompt.end();
+    r.query.interrupt().catch(() => {});
+  }
+  server.close();
+  setTimeout(() => process.exit(0), 100).unref();
+};
+process.on("SIGTERM", shutdown);
+process.on("SIGINT", shutdown);
+`;
+}
+var daemonInflight = /* @__PURE__ */ new WeakMap();
+async function ensureClaudeCodeDaemon(options, env) {
+  const sandbox = options.sandbox;
+  if (!sandbox) return;
+  const key = sandbox;
+  const existing = daemonInflight.get(key);
+  if (existing) return existing;
+  const promise = ensureClaudeCodeDaemonUncached(options, env);
+  daemonInflight.set(key, promise);
+  promise.finally(() => {
+    if (daemonInflight.get(key) === promise) daemonInflight.delete(key);
+  });
+  return promise;
+}
+async function ensureClaudeCodeDaemonUncached(options, env) {
+  return time(debugRelay, "ensureClaudeCodeDaemon", async () => {
+    const sandbox = options.sandbox;
+    const probe = await time(
+      debugRelay,
+      "probe daemon version",
+      () => sandbox.run(
+        `curl -fsS --max-time 1 http://127.0.0.1:${DAEMON_PORT}/__version 2>/dev/null`,
+        { cwd: options.cwd, timeoutMs: 1e4 }
+      )
+    );
+    if (probe.exitCode === 0 && probe.combinedOutput.trim() === DAEMON_PROTOCOL_VERSION) {
+      debugRelay(
+        "daemon v%s already running \u2014 reusing",
+        DAEMON_PROTOCOL_VERSION
+      );
+      return;
+    }
+    const daemonDir = path8.posix.dirname(DAEMON_PATH);
+    const daemonNodeModules = `${daemonDir}/node_modules/@anthropic-ai`;
+    const launchCommand = [
+      `NPM_ROOT="$(npm root -g 2>/dev/null)"`,
+      `if [ -z "$NPM_ROOT" ] || [ ! -d "$NPM_ROOT/@anthropic-ai/claude-agent-sdk" ]; then echo "claude-code daemon launch: @anthropic-ai/claude-agent-sdk not found under $NPM_ROOT" >&2; exit 1; fi`,
+      `mkdir -p ${shellQuote(daemonNodeModules)}`,
+      `ln -sfn "$NPM_ROOT/@anthropic-ai/claude-agent-sdk" ${shellQuote(daemonNodeModules + "/claude-agent-sdk")}`,
+      `if [ -f ${shellQuote(DAEMON_PID_PATH)} ]; then kill -TERM "$(cat ${shellQuote(DAEMON_PID_PATH)})" 2>/dev/null || true; fi`,
+      `(fuser -k -n tcp ${DAEMON_PORT} 2>/dev/null || true)`,
+      // Brief grace so the kernel releases the port before the new
+      // daemon's listen() — only matters on warm-sandbox respawns;
+      // adds 200ms otherwise.
+      `sleep 0.2`,
+      `(nohup node ${shellQuote(DAEMON_PATH)} ${DAEMON_PORT} > ${shellQuote(DAEMON_LOG_PATH)} 2>&1 & echo $! > ${shellQuote(DAEMON_PID_PATH)})`
+    ].join(" && ");
+    const launch = await time(
+      debugRelay,
+      "uploadAndRun daemon (write + spawn)",
+      () => sandbox.uploadAndRun(
+        [
+          {
+            path: DAEMON_PATH,
+            content: createClaudeCodeDaemonScript(),
+            mode: 420
+          }
+        ],
+        launchCommand,
+        { cwd: options.cwd, env: { ...env, IS_SANDBOX: "1" } }
+      )
+    );
+    if (launch.exitCode !== 0) {
+      throw new Error(
+        `Could not start claude-code daemon: ${launch.stderr || launch.combinedOutput || "(no output)"}`
+      );
+    }
+  });
+}
+var DAEMON_FIRST_REQUEST_RETRY_BUDGET_MS = 3e4;
+var DAEMON_FIRST_REQUEST_RETRY_INTERVAL_MS = 250;
+async function fetchWithDaemonRetry(input, init) {
+  const deadline = Date.now() + DAEMON_FIRST_REQUEST_RETRY_BUDGET_MS;
+  let lastError;
+  while (Date.now() < deadline) {
+    try {
+      return await fetch(input, init);
+    } catch (error) {
+      lastError = error;
+      const aborted = error?.name === "AbortError";
+      if (aborted) {
+        throw error;
+      }
+      await sleep(DAEMON_FIRST_REQUEST_RETRY_INTERVAL_MS);
+    }
+  }
+  throw lastError ?? new Error("claude-code daemon request timed out");
+}
+async function* parseNdjsonStream(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    let idx;
+    while ((idx = buffer.indexOf("\n")) !== -1) {
+      const line = buffer.slice(0, idx).trim();
+      buffer = buffer.slice(idx + 1);
+      if (line) {
+        try {
+          yield JSON.parse(line);
+        } catch {
+        }
+      }
+    }
+  }
+  buffer += decoder.decode();
+  if (buffer.trim()) {
+    try {
+      yield JSON.parse(buffer);
+    } catch {
+    }
+  }
+}
+async function daemonBaseUrl(sandbox) {
+  const url = await sandbox.getPreviewLink(DAEMON_PORT);
+  return url.replace(/\/$/, "");
+}
+var ClaudeCodeAgentAdapter = class {
+  /**
+   * Sandbox-side preparation. Uploads `.claude/` artifacts and ensures
+   * the daemon is running. `execute()` then dials the daemon directly.
+   */
+  async setup(request) {
+    await time(debugClaude, "claude-code setup()", async () => {
+      const options = request.options;
+      const provider = request.provider;
+      const sandbox = options.sandbox;
+      if (!sandbox) {
+        throw new Error(
+          "claude-code requires a sandbox (the SDK transport runs as a daemon inside the sandbox)."
+        );
+      }
+      const target = await createSetupTarget(provider, "shared-setup", options);
+      const settingsPath = path8.join(target.layout.claudeDir, "settings.json");
+      const mcpConfigPath = path8.join(
+        target.layout.claudeDir,
+        "agentbox-mcp.json"
+      );
+      const hooks = assertHooksSupported(provider, options);
+      assertCommandsSupported(provider, options.commands);
+      const { artifacts: skillArtifacts, installCommands } = await time(
+        debugClaude,
+        "prepareSkillArtifacts",
+        () => prepareSkillArtifacts(provider, options.skills, target.layout)
+      );
+      const hookSettings = buildClaudeHookSettings(hooks) ?? {};
+      const mcpConfigJson = buildClaudeMcpConfig(options.mcps) ?? JSON.stringify({ mcpServers: {} }, null, 2);
+      const artifacts = [
+        ...skillArtifacts,
+        ...buildClaudeCommandArtifacts(options.commands, target.layout),
+        ...buildClaudeSubagentArtifacts(options.subAgents, target.layout),
+        { path: settingsPath, content: JSON.stringify(hookSettings, null, 2) },
+        { path: mcpConfigPath, content: mcpConfigJson }
+      ];
+      const env = { ...options.env ?? {}, ...target.env };
+      await Promise.all([
+        time(
+          debugClaude,
+          "applyDifferentialSetup",
+          () => applyDifferentialSetup(target, artifacts, installCommands)
+        ),
+        ensureClaudeCodeDaemon(options, env)
+      ]);
+    });
+  }
+  async execute(request, sink) {
+    const executeStartedAt = Date.now();
+    debugClaude("execute() start runId=%s", request.runId);
+    const sandbox = request.options.sandbox;
+    if (!sandbox) {
+      throw new Error(
+        "claude-code requires a sandbox (the SDK transport runs as a daemon inside the sandbox)."
+      );
+    }
+    const claudeDir = claudeConfigDir(request.options);
+    const settingsPath = path8.join(claudeDir, "settings.json");
+    const mcpConfigPath = path8.join(claudeDir, "agentbox-mcp.json");
+    const env = {
+      ...request.options.env ?? {},
+      CLAUDE_CONFIG_DIR: claudeDir,
+      // `IS_SANDBOX=1` lets the in-sandbox claude binary accept
+      // `--dangerously-skip-permissions` (i.e. permissionMode
+      // bypassPermissions) when running as root, which is the default
+      // user inside our images.
+      IS_SANDBOX: "1"
+    };
+    const inputParts = await time(
+      debugClaude,
+      "validateProviderUserInput",
+      () => validateProviderUserInput(request.provider, request.run.input)
+    );
+    const userContent = mapToClaudeUserContent(inputParts);
+    const initialUuid = randomUUID();
+    const presetSessionId = request.run.resumeSessionId ?? randomUUID();
+    sink.setSessionId(presetSessionId);
+    const baseUrl = await time(
+      debugClaude,
+      "getPreviewLink daemon",
+      () => daemonBaseUrl(sandbox)
+    );
+    const startUrl = `${baseUrl}/runs/${encodeURIComponent(request.runId)}/start`;
+    const sdkOptions = buildClaudeQueryOptions({
+      request,
+      settingsPath,
+      mcpConfigPath,
+      env
+    });
+    const autoApproveTools = shouldAutoApproveClaudeTools(request.options);
+    const requestBody = {
+      prompt: {
+        type: "user",
+        message: {
+          role: "user",
+          content: userContent
+        },
+        parent_tool_use_id: null
+      },
+      options: {
+        ...sdkOptions,
+        // `sessionId` and `resume` are mutually exclusive — buildClaudeQueryOptions
+        // already set `resume` for the resume path, so only stamp `sessionId` for
+        // fresh runs.
+        ...request.run.resumeSessionId ? {} : { sessionId: presetSessionId },
+        autoApproveTools
+      }
+    };
+    const fetchAbort = new AbortController();
+    const cleanup = async () => {
+      try {
+        await fetch(
+          `${baseUrl}/runs/${encodeURIComponent(request.runId)}/abort`,
+          { method: "POST", headers: sandbox.previewHeaders }
+        );
+      } catch {
+      }
+      fetchAbort.abort();
+    };
+    sink.setAbort(cleanup);
+    sink.onMessage(async (content) => {
+      const parts = await validateProviderUserInput(request.provider, content);
+      const mapped = mapToClaudeUserContent(parts);
+      const messageUuid = randomUUID();
+      await fetch(
+        `${baseUrl}/runs/${encodeURIComponent(request.runId)}/sendMessage`,
+        {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            ...sandbox.previewHeaders
+          },
+          body: JSON.stringify({ content: mapped })
+        }
+      );
+      return { messageId: messageUuid };
+    });
+    const response = await time(
+      debugClaude,
+      "POST /runs/<id>/start",
+      () => fetchWithDaemonRetry(startUrl, {
+        method: "POST",
+        signal: fetchAbort.signal,
+        headers: {
+          "content-type": "application/json",
+          ...sandbox.previewHeaders
+        },
+        body: JSON.stringify(requestBody)
+      })
+    );
+    if (!response.ok || !response.body) {
+      const text = await response.text().catch(() => "");
+      throw new Error(
+        `claude-code daemon /start failed: ${response.status} ${text}`
+      );
+    }
+    sink.setRaw({ baseUrl, runId: request.runId, claudeDir });
+    sink.emitEvent(
+      createNormalizedEvent("run.started", {
+        provider: request.provider,
+        runId: request.runId
+      })
+    );
+    sink.emitEvent(
+      createNormalizedEvent(
+        "message.started",
+        { provider: request.provider, runId: request.runId },
+        { messageId: initialUuid }
+      )
+    );
+    let accumulatedText = "";
+    let pendingMessages = 1;
+    let firstStreamEventLogged = false;
+    let firstTextDeltaLogged = false;
+    const rawPayloads = [];
+    try {
+      for await (const item of parseNdjsonStream(response.body)) {
+        if (item && typeof item === "object" && "_error" in item) {
+          throw new Error(
+            String(item._error ?? "daemon error")
+          );
+        }
+        const message = item;
+        rawPayloads.push(message);
+        sink.emitRaw(toRawEvent(request.runId, message, message.type));
+        if (message.type === "system") {
+          const sys = message;
+          if (sys.subtype === "init" && sys.session_id) {
+            debugClaude(
+              "\u2605 session.init session_id=%s (%dms)",
+              sys.session_id.slice(0, 8),
+              Date.now() - executeStartedAt
+            );
+          }
+          continue;
+        }
+        if (message.type === "stream_event") {
+          if (!firstStreamEventLogged) {
+            firstStreamEventLogged = true;
+            debugClaude(
+              "\u2605 first stream_event (%dms since execute start)",
+              Date.now() - executeStartedAt
+            );
+          }
+          const partial = message;
+          const { text, thinking } = extractStreamDeltas(partial);
+          if (thinking) {
+            sink.emitEvent(
+              createNormalizedEvent(
+                "reasoning.delta",
+                { provider: request.provider, runId: request.runId },
+                { delta: thinking }
+              )
+            );
+          }
+          if (text) {
+            if (!firstTextDeltaLogged) {
+              firstTextDeltaLogged = true;
+              debugClaude(
+                "\u2605 first text delta (%dms since execute start)",
+                Date.now() - executeStartedAt
+              );
+            }
+            accumulatedText += text;
+            sink.emitEvent(
+              createNormalizedEvent(
+                "text.delta",
+                { provider: request.provider, runId: request.runId },
+                { delta: text }
+              )
+            );
+          }
+          continue;
+        }
+        if (message.type === "assistant") {
+          const asst = message;
+          const thinking = extractAssistantThinking(asst);
+          if (thinking) {
+            sink.emitEvent(
+              createNormalizedEvent(
+                "reasoning.delta",
+                { provider: request.provider, runId: request.runId },
+                { delta: thinking }
+              )
+            );
+          }
+          const text = extractAssistantText(asst);
+          sink.emitEvent(
+            createNormalizedEvent(
+              "message.completed",
+              { provider: request.provider, runId: request.runId },
+              {
+                text,
+                ...asst.uuid ? { messageId: String(asst.uuid) } : {}
+              }
+            )
+          );
+          continue;
+        }
+        if (message.type === "result") {
+          const result = message;
+          const resultText = result.subtype === "success" ? result.result : accumulatedText;
+          if (resultText && resultText !== accumulatedText) {
+            accumulatedText = resultText;
+          }
+          pendingMessages--;
+          if (pendingMessages <= 0) break;
+          continue;
+        }
+      }
+      const finalText = accumulatedText;
+      debugClaude(
+        "\u2605 run.completed (%dms since execute start) chars=%d",
+        Date.now() - executeStartedAt,
+        finalText.length
+      );
+      sink.emitEvent(
+        createNormalizedEvent(
+          "run.completed",
+          { provider: request.provider, runId: request.runId },
+          { text: finalText }
+        )
+      );
+      sink.complete({
+        text: finalText,
+        costData: extractClaudeCostData(rawPayloads)
+      });
+    } finally {
+      fetchAbort.abort();
+    }
+    return async () => void 0;
+  }
+  /**
+   * Stateless abort. POSTs to the in-sandbox daemon's
+   * `/runs/<id>/abort`. The daemon calls `query.interrupt()` on the
+   * matching live run; the originating instance's NDJSON read loop
+   * sees the run unwind via a non-success `result` (or stream close).
+   */
+  async attachAbort(request) {
+    const baseUrl = await daemonBaseUrl(request.sandbox);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 3e3);
+    try {
+      await fetch(
+        `${baseUrl}/runs/${encodeURIComponent(request.runId)}/abort`,
+        {
+          method: "POST",
+          signal: controller.signal,
+          headers: request.sandbox.previewHeaders
+        }
+      ).catch((error) => {
+        debugClaude("attachAbort POST failed: %o", error);
+      });
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  /**
+   * Stateless message injection. POSTs `{ content }` to the daemon's
+   * `/runs/<id>/sendMessage`. The daemon pushes the message into the
+   * matching run's prompt iterable, which the SDK forwards to claude
+   * as a fresh user turn.
+   */
+  async attachSendMessage(request, content) {
+    const baseUrl = await daemonBaseUrl(request.sandbox);
+    const inputParts = await validateProviderUserInput(
+      AgentProvider.ClaudeCode,
+      content
+    );
+    const mapped = mapToClaudeUserContent(inputParts);
+    const response = await fetch(
+      `${baseUrl}/runs/${encodeURIComponent(request.runId)}/sendMessage`,
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          ...request.sandbox.previewHeaders
+        },
+        body: JSON.stringify({ content: mapped })
+      }
+    );
+    if (!response.ok) {
+      throw new Error(
+        `claude-code attachSendMessage failed: ${response.status} ${await response.text().catch(() => "")}`
+      );
+    }
+  }
+};
+
+// src/agents/providers/codex.ts
+import path9 from "path";
+
+// src/agents/transports/app-server.ts
+import { createParser } from "eventsource-parser";
+import { WebSocket } from "ws";
+async function fetchJson(url, init) {
+  const response = await fetch(url, init);
+  if (!response.ok) {
+    throw new Error(`Request to ${url} failed with ${response.status}.`);
+  }
+  const text = await response.text();
+  if (text.length === 0) {
+    throw new Error(
+      `Request to ${url} returned status ${response.status} with an empty body.`
+    );
+  }
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    const preview = text.length > 200 ? `${text.slice(0, 200)}\u2026` : text;
+    const cause = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Could not parse JSON response from ${url} (status ${response.status}): ${cause}. Body: ${preview}`
+    );
+  }
+}
+async function* streamSse(url, init) {
+  const response = await fetch(url, init);
+  if (!response.ok || !response.body) {
+    throw new Error(`Could not open SSE stream at ${url}.`);
+  }
+  const queue = new AsyncQueue();
+  const parser = createParser({
+    onEvent(event) {
+      queue.push({
+        event: event.event || void 0,
+        id: event.id || void 0,
+        data: event.data
+      });
+    },
+    onError(error) {
+      queue.fail(error);
+    }
+  });
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  void (async () => {
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+          break;
+        }
+        parser.feed(decoder.decode(value, { stream: true }));
+      }
+      parser.feed(decoder.decode());
+      queue.finish();
+    } catch (error) {
+      queue.fail(error);
+    } finally {
+      reader.releaseLock();
+    }
+  })();
+  yield* queue;
+}
+async function connectJsonRpcWebSocket(url, options) {
+  const notifications = new AsyncQueue();
+  const socket = new WebSocket(url, { headers: options?.headers });
+  await new Promise((resolve, reject) => {
+    const cleanup = () => {
+      socket.off("open", handleOpen);
+      socket.off("error", handleError);
+    };
+    const handleOpen = () => {
+      cleanup();
+      resolve();
+    };
+    const handleError = (error) => {
+      cleanup();
+      reject(error);
+    };
+    socket.once("open", handleOpen);
+    socket.once("error", handleError);
+  });
+  socket.on("message", (data) => {
+    notifications.push(data.toString());
+  });
+  socket.on("close", () => {
+    notifications.finish();
+  });
+  socket.on("error", (error) => {
+    notifications.fail(error);
+  });
+  return {
+    source: notifications,
+    send: async (line) => {
+      await new Promise((resolve, reject) => {
+        socket.send(line, (error) => {
+          if (error) {
+            reject(error);
+            return;
+          }
+          resolve();
+        });
+      });
+    },
+    close: async () => {
+      await new Promise((resolve) => {
+        if (socket.readyState === WebSocket.CLOSED || socket.readyState === WebSocket.CLOSING) {
+          resolve();
+          return;
+        }
+        socket.once("close", () => resolve());
+        socket.close();
+      });
+    },
+    raw: socket
+  };
+}
+var JsonRpcLineClient = class {
+  constructor(source, writeLine) {
+    this.writeLine = writeLine;
+    void this.consume(source);
+  }
+  writeLine;
+  pending = /* @__PURE__ */ new Map();
+  notifications = new AsyncQueue();
+  nextId = 1;
+  async request(method, params) {
+    const id = this.nextId++;
+    const response = new Promise((resolve, reject) => {
+      this.pending.set(id, {
+        resolve,
+        reject
+      });
+    });
+    await this.writeLine(JSON.stringify({ id, method, params }));
+    return response;
+  }
+  async notify(method, params) {
+    await this.writeLine(JSON.stringify({ method, params: params ?? {} }));
+  }
+  async respond(id, result) {
+    await this.writeLine(JSON.stringify({ id, result }));
+  }
+  async respondError(id, error) {
+    await this.writeLine(JSON.stringify({ id, error }));
+  }
+  async *messages() {
+    yield* this.notifications;
+  }
+  async consume(source) {
+    try {
+      for await (const line of source) {
+        if (!line.trim()) {
+          continue;
+        }
+        const message = JSON.parse(line);
+        if (typeof message.method === "string") {
+          this.notifications.push(message);
+          continue;
+        }
+        if (typeof message.id === "number") {
+          const pending = this.pending.get(message.id);
+          if (!pending) {
+            continue;
+          }
+          this.pending.delete(message.id);
+          if (message.error) {
+            pending.reject(message.error);
+          } else {
+            pending.resolve(message.result);
+          }
+          continue;
+        }
+      }
+      const closeError = new Error("JSON-RPC transport closed.");
+      for (const pending of this.pending.values()) {
+        pending.reject(closeError);
+      }
+      this.pending.clear();
+      this.notifications.finish();
+    } catch (error) {
+      for (const pending of this.pending.values()) {
+        pending.reject(error);
+      }
+      this.pending.clear();
+      this.notifications.fail(error);
+    }
+  }
+};
+
+// src/agents/providers/codex.ts
+function codexConfigDir(options) {
+  return path9.join(
+    agentboxRoot(AgentProvider.Codex, Boolean(options.sandbox)),
+    ".codex"
+  );
+}
+var REMOTE_CODEX_APP_SERVER_PORT = 43181;
+var REMOTE_CODEX_APP_SERVER_ID = "shared-app-server";
+function compactEnv(values) {
+  return Object.fromEntries(
+    Object.entries(values).filter(([, value]) => value !== void 0)
+  );
+}
+function buildCodexSandboxMode(options) {
+  return options.sandbox ? "workspace-write" : "read-only";
+}
+function buildThreadParams(cwd, options, request) {
+  return {
+    cwd,
+    model: request.run.model ?? null,
+    approvalPolicy: isInteractiveApproval(options) ? "untrusted" : "never",
+    sandbox: buildCodexSandboxMode(options),
+    serviceName: "agentbox",
+    // Persist the rollout on disk so follow-up runs can call `thread/resume`.
+    // `ephemeral: true` threads have no rollout file and resume fails with
+    // "no rollout found for thread id ...".
+    experimentalRawEvents: true
+  };
+}
+function buildResumeParams(cwd, options, request) {
+  return {
+    threadId: request.run.resumeSessionId,
+    cwd,
+    model: request.run.model ?? null,
+    approvalPolicy: isInteractiveApproval(options) ? "untrusted" : "never",
+    sandbox: buildCodexSandboxMode(options)
+  };
+}
+function buildTurnSandboxPolicy(options) {
+  if (!options.sandbox) {
+    return void 0;
+  }
+  if (options.sandbox.provider === SandboxProvider.LocalDocker) {
+    return {
+      type: "workspaceWrite",
+      networkAccess: true
+    };
+  }
+  return {
+    type: "externalSandbox",
+    networkAccess: "enabled"
+  };
+}
+function buildTurnCollaborationMode(request) {
+  const systemPrompt = request.run.systemPrompt;
+  if (!systemPrompt) {
+    return void 0;
+  }
+  return {
+    mode: "custom",
+    settings: {
+      developer_instructions: systemPrompt
+    }
+  };
+}
+function buildCodexTurnStartParams(params) {
+  const { threadId, inputItems, request, turnStartOverrides } = params;
+  const sandboxPolicy = buildTurnSandboxPolicy(request.options);
+  return {
+    threadId,
+    input: inputItems,
+    approvalPolicy: isInteractiveApproval(request.options) ? "untrusted" : "never",
+    ...sandboxPolicy ? { sandboxPolicy } : {},
+    ...turnStartOverrides ?? {},
+    model: request.run.model ?? null,
+    effort: request.run.reasoning ?? null,
+    outputSchema: null
+  };
+}
+function toRawEvent2(runId, payload, type) {
+  return {
+    provider: AgentProvider.Codex,
+    runId,
+    type,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    payload
+  };
+}
+function shouldIgnoreCodexError(notification) {
+  if (notification.method !== "error") {
+    return false;
+  }
+  return notification.params?.willRetry === true;
+}
+function buildCodexCommandArgs(binary, args, options) {
+  const overrides = [];
+  if (options?.provider?.supportsWebsockets === false) {
+    overrides.push(["supports_websockets", "false"]);
+  }
+  const overrideArgs = overrides.flatMap(([k, v]) => ["-c", `${k}=${v}`]);
+  return ["-u", "XDG_CONFIG_HOME", binary, ...overrideArgs, ...args];
+}
+function toNormalizedCodexEvents(runId, notification) {
+  const base = {
+    provider: AgentProvider.Codex,
+    runId,
+    raw: toRawEvent2(runId, notification, notification.method)
+  };
+  if (notification.method === "turn/started") {
+    const turn = notification.params?.turn;
+    const turnId = typeof turn?.id === "string" ? turn.id : void 0;
+    return [
+      createNormalizedEvent(
+        "message.started",
+        base,
+        turnId ? { messageId: turnId } : void 0
+      )
+    ];
+  }
+  if (notification.method === "item/agentMessage/delta") {
+    const delta = typeof notification.params?.delta === "string" ? notification.params.delta : "";
+    return delta ? [createNormalizedEvent("text.delta", base, { delta })] : [];
+  }
+  if (notification.method === "item/reasoning/summaryTextDelta" || notification.method === "item/reasoning/textDelta") {
+    const delta = typeof notification.params?.delta === "string" ? notification.params.delta : typeof notification.params?.text === "string" ? notification.params.text : "";
+    return delta ? [createNormalizedEvent("reasoning.delta", base, { delta })] : [];
+  }
+  if (notification.method === "item/completed") {
+    const item = notification.params?.item;
+    if (!item) {
+      return [];
+    }
+    if (item.type === "agentMessage" && typeof item.text === "string") {
+      return [
+        createNormalizedEvent("message.completed", base, { text: item.text })
+      ];
+    }
+    if (item.type === "reasoning" && item.summary) {
+      return [
+        createNormalizedEvent("reasoning.delta", base, {
+          delta: typeof item.summary === "string" ? item.summary : JSON.stringify(item.summary)
+        })
+      ];
+    }
+    if (item.type === "commandExecution" || item.type === "dynamicToolCall" || item.type === "mcpToolCall" || item.type === "webSearch") {
+      return [
+        createNormalizedEvent("tool.call.completed", base, {
+          toolName: String(
+            item.tool ?? item.command ?? item.server ?? item.query ?? item.type
+          ),
+          callId: String(item.id ?? ""),
+          output: item
+        })
+      ];
+    }
+  }
+  if (notification.method === "item/started") {
+    const item = notification.params?.item;
+    if (item && (item.type === "commandExecution" || item.type === "dynamicToolCall" || item.type === "mcpToolCall" || item.type === "webSearch")) {
+      return [
+        createNormalizedEvent("tool.call.started", base, {
+          toolName: String(
+            item.tool ?? item.command ?? item.server ?? item.query ?? item.type
+          ),
+          callId: String(item.id ?? ""),
+          input: item
+        })
+      ];
+    }
+  }
+  if (notification.method === "turn/completed") {
+    const turn = notification.params?.turn;
+    const text = typeof turn?.lastAgentMessage === "string" ? turn.lastAgentMessage : void 0;
+    return [createNormalizedEvent("run.completed", base, { text })];
+  }
+  if (notification.method === "error") {
+    const error = notification.params?.error;
+    return [
+      createNormalizedEvent("run.error", base, {
+        error: String(error?.message ?? "Codex app-server error")
+      })
+    ];
+  }
+  return [];
+}
+function createCodexPermissionEvent(request, notification) {
+  const raw = toRawEvent2(request.runId, notification, notification.method);
+  const params = notification.params;
+  const requestId = notification.id;
+  if (!params || requestId === void 0) {
+    return null;
+  }
+  if (notification.method === "item/commandExecution/requestApproval") {
+    const networkContext = params.networkApprovalContext;
+    const availableDecisions = Array.isArray(params.availableDecisions) ? params.availableDecisions : [];
+    const title = networkContext ? "Approve network access" : "Approve command execution";
+    const message = typeof params.reason === "string" ? params.reason : typeof params.command === "string" ? params.command : void 0;
+    return createNormalizedEvent(
+      "permission.requested",
+      {
+        provider: request.provider,
+        runId: request.runId,
+        raw
+      },
+      {
+        requestId: String(requestId),
+        kind: networkContext ? "network" : "bash",
+        title,
+        message,
+        input: params,
+        canRemember: availableDecisions.includes("acceptForSession")
+      }
+    );
+  }
+  if (notification.method === "item/fileChange/requestApproval") {
+    const availableDecisions = Array.isArray(params.availableDecisions) ? params.availableDecisions : [];
+    return createNormalizedEvent(
+      "permission.requested",
+      {
+        provider: request.provider,
+        runId: request.runId,
+        raw
+      },
+      {
+        requestId: String(requestId),
+        kind: "file-change",
+        title: "Approve file changes",
+        message: typeof params.reason === "string" ? params.reason : "Codex wants to modify files.",
+        input: params,
+        canRemember: availableDecisions.includes("acceptForSession")
+      }
+    );
+  }
+  return null;
+}
+function toCodexApprovalDecision(notification, response) {
+  const params = notification.params ?? {};
+  const availableDecisions = Array.isArray(params.availableDecisions) ? params.availableDecisions : [];
+  const proposedExecpolicyAmendment = Array.isArray(
+    params.proposedExecpolicyAmendment
+  ) ? params.proposedExecpolicyAmendment.filter(
+    (part) => typeof part === "string"
+  ) : [];
+  if (response.decision === "deny") {
+    return availableDecisions.includes("decline") ? "decline" : "cancel";
+  }
+  if (response.remember && availableDecisions.includes("acceptForSession")) {
+    return "acceptForSession";
+  }
+  if (proposedExecpolicyAmendment.length > 0 && availableDecisions.some(
+    (decision) => typeof decision === "object" && decision !== null && "acceptWithExecpolicyAmendment" in decision
+  )) {
+    return {
+      acceptWithExecpolicyAmendment: {
+        execpolicy_amendment: proposedExecpolicyAmendment
+      }
+    };
+  }
+  return "accept";
+}
+function codexImageExtension(mediaType) {
+  switch (mediaType) {
+    case "image/gif":
+      return ".gif";
+    case "image/jpeg":
+      return ".jpg";
+    case "image/png":
+      return ".png";
+    case "image/webp":
+      return ".webp";
+    default:
+      return ".img";
+  }
+}
+async function materializeCodexImage(options, part, index) {
+  if (part.source.type === "url") {
+    return part.source.url;
+  }
+  const root = agentboxRoot(AgentProvider.Codex, Boolean(options.sandbox));
+  const imagePath = path9.join(
+    root,
+    "inputs",
+    `codex-image-${index}${codexImageExtension(part.mediaType)}`
+  );
+  if (options.sandbox) {
+    const encodedPath = `${imagePath}.b64`;
+    await options.sandbox.uploadAndRun(
+      [{ path: encodedPath, content: part.source.data }],
+      [
+        `mkdir -p ${shellQuote(path9.posix.dirname(imagePath))}`,
+        `(base64 --decode < ${shellQuote(encodedPath)} > ${shellQuote(imagePath)} || base64 -D < ${shellQuote(encodedPath)} > ${shellQuote(imagePath)})`,
+        `rm -f ${shellQuote(encodedPath)}`
+      ].join(" && "),
+      { cwd: options.cwd, env: options.env }
+    );
+    return imagePath;
+  }
+  const fs = await import("fs/promises");
+  await fs.mkdir(path9.dirname(imagePath), { recursive: true });
+  await fs.writeFile(imagePath, Buffer.from(part.source.data, "base64"));
+  return imagePath;
+}
+function resolveCodexOpenAiBaseUrlFromOptions(options) {
+  return options.env?.OPENAI_BASE_URL ?? options.provider?.env?.OPENAI_BASE_URL;
+}
+async function ensureCodexLoginViaConfig(request, target) {
+  const options = request.options;
+  const openAiApiKey = options.env?.OPENAI_API_KEY ?? options.provider?.env?.OPENAI_API_KEY;
+  const openAiBaseUrl = resolveCodexOpenAiBaseUrlFromOptions(options);
+  const extraEnv = {};
+  if (openAiApiKey) {
+    extraEnv.OPENAI_API_KEY = openAiApiKey;
+  }
+  if (openAiBaseUrl) {
+    extraEnv.OPENAI_BASE_URL = openAiBaseUrl;
+  }
+  await target.runCommand(
+    [
+      'if [ -z "${OPENAI_API_KEY:-}" ]; then exit 0; fi',
+      'mkdir -p "${CODEX_HOME:-$HOME/.codex}"',
+      "printenv OPENAI_API_KEY | env -u XDG_CONFIG_HOME codex login --with-api-key"
+    ].join("; "),
+    Object.keys(extraEnv).length > 0 ? extraEnv : void 0
+  );
+}
+function toRemoteCodexWebSocketUrl(url) {
+  const parsed = new URL(url);
+  parsed.protocol = parsed.protocol === "https:" ? "wss:" : "ws:";
+  return parsed.toString();
+}
+async function withCodexAppServer(request, body) {
+  const sandbox = request.sandbox;
+  if (sandbox.provider === SandboxProvider.LocalDocker) {
+    throw new Error(
+      "Codex stateless attach is not supported for local-docker sandboxes; the app-server is in-process."
+    );
+  }
+  const previewUrl = await sandbox.getPreviewLink(REMOTE_CODEX_APP_SERVER_PORT);
+  const transport = await connectJsonRpcWebSocket(
+    toRemoteCodexWebSocketUrl(previewUrl),
+    { headers: sandbox.previewHeaders }
+  );
+  const client = new JsonRpcLineClient(
+    transport.source,
+    transport.send
+  );
+  try {
+    await client.request("initialize", {
+      clientInfo: { title: "AgentBox", name: "AgentBox", version: "0.1.0" },
+      capabilities: { experimentalApi: true }
+    });
+    await client.notify("initialized", {});
+    return await body(client);
+  } finally {
+    await transport.close().catch(() => void 0);
+  }
+}
+async function connectRemoteCodexAppServer(url, headers = {}) {
+  return time(debugCodex, "connectRemoteCodexAppServer", async () => {
+    const startedAt = Date.now();
+    let attempt = 0;
+    let lastError;
+    while (Date.now() - startedAt < 3e4) {
+      attempt++;
+      try {
+        const conn = await connectJsonRpcWebSocket(url, { headers });
+        if (attempt > 1) {
+          debugCodex("connected after %d attempt(s)", attempt);
+        }
+        return conn;
+      } catch (error) {
+        lastError = error;
+        await sleep(250);
+      }
+    }
+    throw lastError ?? new Error(`Could not connect to Codex app-server at ${url}.`);
+  });
+}
+async function setupCodex(request) {
+  const options = request.options;
+  const provider = request.provider;
+  const hooks = assertHooksSupported(provider, options);
+  assertCommandsSupported(provider, options.commands);
+  const usesRemoteWebSocket = options.sandbox && options.sandbox.provider !== SandboxProvider.LocalDocker;
+  function buildArtifactsFor(layoutTarget) {
+    const { artifacts: subAgentArtifacts, agentSections } = buildCodexSubagentArtifacts(options.subAgents, layoutTarget.layout);
+    const hooksFile = buildCodexHooksFile(hooks);
+    const enableMultiAgent = (options.subAgents?.length ?? 0) > 0;
+    const enableSkills = (options.skills?.length ?? 0) > 0;
+    const openAiBaseUrl = resolveCodexOpenAiBaseUrlFromOptions(options);
+    const configToml = buildCodexConfigToml({
+      mcps: options.mcps,
+      agentSections,
+      enableHooks: Boolean(hooksFile),
+      enableSkills,
+      enableMultiAgent,
+      openAiBaseUrl
+    });
+    const artifacts = [...subAgentArtifacts];
+    if (configToml) {
+      artifacts.push({
+        path: path9.join(layoutTarget.layout.codexDir, "config.toml"),
+        content: configToml
+      });
+    }
+    if (hooksFile) {
+      artifacts.push({
+        path: path9.join(layoutTarget.layout.codexDir, "hooks.json"),
+        content: JSON.stringify(hooksFile, null, 2)
+      });
+    }
+    return { artifacts, installCommands: [] };
+  }
+  if (usesRemoteWebSocket && options.sandbox) {
+    const sandbox = options.sandbox;
+    const sharedTarget = await createSetupTarget(
+      provider,
+      REMOTE_CODEX_APP_SERVER_ID,
+      options
+    );
+    const target2 = await createSetupTarget(provider, "shared-setup", options);
+    const env = compactEnv({
+      ...options.env ?? {},
+      ...sharedTarget.env,
+      ...options.provider?.env ?? {}
+    });
+    await time(
+      debugCodex,
+      "ensureCodexLogin",
+      () => ensureCodexLoginViaConfig(request, sharedTarget)
+    );
+    const { artifacts: serverArtifacts } = buildArtifactsFor(sharedTarget);
+    await applyDifferentialSetup(sharedTarget, serverArtifacts, []);
+    const binary = options.provider?.binary ?? "codex";
+    const pidFilePath = path9.posix.join(
+      sharedTarget.layout.rootDir,
+      "codex-app-server.pid"
+    );
+    const logFilePath = path9.posix.join(
+      sharedTarget.layout.rootDir,
+      "codex-app-server.log"
+    );
+    const serverCwd = sharedTarget.layout.rootDir;
+    const launchResult = await time(
+      debugCodex,
+      "launch app-server (probe + spawn-if-cold)",
+      () => sandbox.run(
+        [
+          `mkdir -p ${shellQuote(sharedTarget.layout.rootDir)}`,
+          `if curl -fsS http://127.0.0.1:${REMOTE_CODEX_APP_SERVER_PORT}/readyz >/dev/null 2>&1; then exit 0; fi`,
+          `if [ -f ${shellQuote(pidFilePath)} ]; then kill "$(cat ${shellQuote(pidFilePath)})" >/dev/null 2>&1 || true; rm -f ${shellQuote(pidFilePath)}; fi`,
+          `(${[
+            `nohup ${[
+              "env",
+              ...buildCodexCommandArgs(
+                binary,
+                [
+                  "app-server",
+                  "--listen",
+                  `ws://0.0.0.0:${REMOTE_CODEX_APP_SERVER_PORT}`
+                ],
+                options
+              )
+            ].map(shellQuote).join(" ")} > ${shellQuote(logFilePath)} 2>&1 &`,
+            `echo $! > ${shellQuote(pidFilePath)}`
+          ].join(" ")})`
+        ].join(" && "),
+        {
+          cwd: serverCwd,
+          env
+        }
+      )
+    );
+    if (launchResult.exitCode !== 0) {
+      throw new Error(
+        `Could not start Codex app-server: ${launchResult.combinedOutput || launchResult.stderr}`
+      );
+    }
+    try {
+      const { artifacts: skillArtifacts2, installCommands: installCommands2 } = await prepareSkillArtifacts(provider, options.skills, target2.layout);
+      await applyDifferentialSetup(target2, skillArtifacts2, installCommands2);
+    } catch (error) {
+      await target2.cleanup().catch(() => void 0);
+      throw error;
+    }
+    return;
+  }
+  const target = await createSetupTarget(provider, "shared-setup", options);
+  try {
+    await ensureCodexLoginViaConfig(request, target);
+  } catch (error) {
+    await target.cleanup().catch(() => void 0);
+    throw error;
+  }
+  const { artifacts: skillArtifacts, installCommands } = await prepareSkillArtifacts(provider, options.skills, target.layout);
+  const { artifacts: configArtifacts } = buildArtifactsFor(target);
+  await applyDifferentialSetup(
+    target,
+    [...skillArtifacts, ...configArtifacts],
+    installCommands
+  );
+}
+async function createRuntime(request, inputParts) {
+  const options = request.options;
+  const codexDir = codexConfigDir(options);
+  const env = compactEnv({
+    ...options.env ?? {},
+    CODEX_HOME: codexDir,
+    ...options.provider?.env ?? {}
+  });
+  const runtimeCwd = path9.dirname(codexDir);
+  const inputItems = await buildCodexInputItems(options, inputParts);
+  const usesRemoteWebSocket = options.sandbox && options.sandbox.provider !== SandboxProvider.LocalDocker;
+  if (usesRemoteWebSocket && options.sandbox) {
+    const sandbox = options.sandbox;
+    const previewUrl = await time(
+      debugCodex,
+      "getPreviewLink app-server",
+      () => sandbox.getPreviewLink(REMOTE_CODEX_APP_SERVER_PORT)
+    );
+    const transport = await connectRemoteCodexAppServer(
+      toRemoteCodexWebSocketUrl(previewUrl),
+      sandbox.previewHeaders
+    );
+    debugCodex("\u2605 codex transport established");
+    return {
+      source: transport.source,
+      writeLine: transport.send,
+      cleanup: async () => {
+        await transport?.close().catch(() => void 0);
+      },
+      raw: {
+        transport: transport.raw,
+        previewUrl,
+        port: REMOTE_CODEX_APP_SERVER_PORT,
+        codexDir
+      },
+      inputItems,
+      turnStartOverrides: buildTurnCollaborationMode(request)
+    };
+  }
+  const codexArgs = buildCodexCommandArgs(
+    options.provider?.binary ?? "codex",
+    ["app-server"],
+    options
+  );
+  if (options.sandbox) {
+    const handle = await options.sandbox.runAsync(["env", ...codexArgs], {
+      cwd: runtimeCwd,
+      env
+    });
+    if (!handle.write) {
+      throw new Error(
+        "The selected sandbox does not expose an interactive stdin channel for Codex."
+      );
+    }
+    async function* stdoutLines() {
+      async function* stdoutChunks() {
+        for await (const event of handle) {
+          if (event.type === "stdout" && event.chunk) {
+            yield event.chunk;
+          }
+        }
+      }
+      yield* linesFromTextChunks(stdoutChunks());
+    }
+    return {
+      source: stdoutLines(),
+      writeLine: async (line) => {
+        await handle.write?.(`${line}
+`);
+      },
+      cleanup: async () => {
+        await handle.kill();
+      },
+      raw: { handle, codexDir },
+      inputItems,
+      turnStartOverrides: buildTurnCollaborationMode(request)
+    };
+  }
+  const processHandle = spawnCommand({
+    command: "env",
+    args: codexArgs,
+    cwd: runtimeCwd,
+    env: {
+      ...process.env,
+      ...env
+    }
+  });
+  return {
+    source: linesFromNodeStream(processHandle.child.stdout),
+    writeLine: async (line) => {
+      processHandle.child.stdin.write(`${line}
+`);
+    },
+    cleanup: async () => {
+      await processHandle.kill();
+    },
+    raw: { processHandle, codexDir },
+    inputItems,
+    turnStartOverrides: buildTurnCollaborationMode(request)
+  };
+}
+async function buildCodexInputItems(options, inputParts) {
+  const textPrompt = joinTextParts(
+    inputParts.filter(
+      (part) => part.type === "text"
+    )
+  );
+  const inputItems = [];
+  if (textPrompt.trim().length > 0) {
+    inputItems.push({
+      type: "text",
+      text: textPrompt,
+      text_elements: []
+    });
+  }
+  inputItems.push(
+    ...await mapToCodexPromptParts(
+      inputParts,
+      async (part, index) => materializeCodexImage(options, part, index)
+    )
+  );
+  return inputItems;
+}
+var CodexAgentAdapter = class {
+  async setup(request) {
+    await setupCodex(request);
+  }
+  async execute(request, sink) {
+    const executeStartedAt = Date.now();
+    debugCodex("execute() start runId=%s", request.runId);
+    const inputParts = await time(
+      debugCodex,
+      "validateProviderUserInput",
+      () => validateProviderUserInput(request.provider, request.run.input)
+    );
+    const runtime = await time(
+      debugCodex,
+      "createRuntime",
+      () => createRuntime(request, inputParts)
+    );
+    sink.setRaw(runtime.raw);
+    sink.emitEvent(
+      createNormalizedEvent("run.started", {
+        provider: request.provider,
+        runId: request.runId
+      })
+    );
+    const client = runtime.client ?? new JsonRpcLineClient(
+      runtime.source,
+      runtime.writeLine
+    );
+    const interactiveApproval = isInteractiveApproval(request.options);
+    let rootThreadId;
+    let turnId;
+    let pendingTurns = 1;
+    sink.setAbort(async () => {
+      const threadIdAtAbort = rootThreadId;
+      const turnIdAtAbort = turnId;
+      if (threadIdAtAbort && turnIdAtAbort) {
+        try {
+          await Promise.race([
+            client.request("turn/interrupt", {
+              threadId: threadIdAtAbort,
+              turnId: turnIdAtAbort
+            }),
+            new Promise(
+              (_, reject) => setTimeout(
+                () => reject(new Error("codex turn/interrupt timed out")),
+                3e3
+              )
+            )
+          ]);
+        } catch {
+        }
+      }
+      await runtime.cleanup().catch(() => void 0);
+    });
+    const sendTurn = async (content) => {
+      if (!rootThreadId) {
+        throw new Error("Cannot send message before thread is started.");
+      }
+      const parts = normalizeUserInput(content);
+      const text = parts.filter((p) => p.type === "text").map((p) => p.text).join("");
+      const inputItems = [];
+      if (text.trim().length > 0) {
+        inputItems.push({ type: "text", text, text_elements: [] });
+      }
+      const response = await client.request(
+        "turn/start",
+        buildCodexTurnStartParams({
+          threadId: rootThreadId,
+          inputItems,
+          request
+        })
+      );
+      return {
+        ...typeof response?.turn?.id === "string" ? { messageId: response.turn.id } : {}
+      };
+    };
+    sink.onMessage(sendTurn);
+    const rawPayloads = [];
+    const completion = new Promise((resolve, reject) => {
+      let finalText = "";
+      void (async () => {
+        let firstClientMessageLogged = false;
+        for await (const message of client.messages()) {
+          if (!firstClientMessageLogged) {
+            firstClientMessageLogged = true;
+            debugCodex(
+              "\u2605 first transport message (%dms since execute start) method=%s",
+              Date.now() - executeStartedAt,
+              message.method
+            );
+          }
+          const raw = toRawEvent2(request.runId, message, message.method);
+          rawPayloads.push(message);
+          sink.emitRaw(raw);
+          if (message.method === "tool/requestUserInput" && message.id !== void 0) {
+            reject(
+              new Error(
+                "Codex tool/requestUserInput approvals are not yet supported by AgentBox."
+              )
+            );
+            return;
+          }
+          const permissionEvent = createCodexPermissionEvent(request, message);
+          if (permissionEvent && message.id !== void 0) {
+            const response = interactiveApproval ? await sink.requestPermission(permissionEvent) : {
+              requestId: permissionEvent.requestId,
+              decision: "allow"
+            };
+            await client.respond(message.id, {
+              decision: toCodexApprovalDecision(message, response)
+            });
+            continue;
+          }
+          for (const event of toNormalizedCodexEvents(request.runId, message)) {
+            sink.emitEvent(event);
+            if (event.type === "text.delta") {
+              finalText += event.delta;
+            }
+          }
+          if (message.method === "thread/started" && !rootThreadId) {
+            rootThreadId = message.params?.thread?.id ?? rootThreadId;
+          }
+          if (message.method === "turn/started") {
+            turnId = message.params?.turn?.id ?? turnId;
+          }
+          if (message.method === "turn/completed" && (!message.params?.threadId || message.params.threadId === rootThreadId)) {
+            pendingTurns--;
+            if (pendingTurns <= 0) {
+              resolve({ text: finalText, turnId, threadId: rootThreadId });
+              return;
+            }
+          }
+          if (message.method === "error" && !shouldIgnoreCodexError(message)) {
+            reject(message);
+            return;
+          }
+        }
+        reject(new Error("Codex transport closed before run completed."));
+      })().catch(reject);
+    });
+    try {
+      if (!runtime.client) {
+        await client.request("initialize", {
+          clientInfo: {
+            title: "AgentBox",
+            name: "AgentBox",
+            version: "0.1.0"
+          },
+          capabilities: {
+            experimentalApi: true
+          }
+        });
+        await client.notify("initialized", {});
+      }
+      const cwd = request.options.cwd ?? process.cwd();
+      const threadResponse = request.run.resumeSessionId ? await client.request(
+        "thread/resume",
+        buildResumeParams(cwd, request.options, request)
+      ) : await client.request(
+        "thread/start",
+        buildThreadParams(cwd, request.options, request)
+      );
+      rootThreadId = threadResponse.thread.id;
+      if ("bindThread" in client && typeof client.bindThread === "function") {
+        client.bindThread(threadResponse.thread.id);
+      }
+      sink.setSessionId(threadResponse.thread.id);
+      rawPayloads.push(threadResponse);
+      sink.emitRaw(
+        toRawEvent2(
+          request.runId,
+          threadResponse,
+          request.run.resumeSessionId ? "thread/resume:result" : "thread/start:result"
+        )
+      );
+      await client.request(
+        "turn/start",
+        buildCodexTurnStartParams({
+          threadId: threadResponse.thread.id,
+          inputItems: runtime.inputItems,
+          request,
+          turnStartOverrides: runtime.turnStartOverrides
+        })
+      );
+      const { text } = await completion;
+      debugCodex(
+        "\u2605 run.completed (%dms since execute start) chars=%d",
+        Date.now() - executeStartedAt,
+        text?.length ?? 0
+      );
+      sink.complete({ text, costData: extractCodexCostData(rawPayloads) });
+    } finally {
+      await runtime.cleanup().catch(() => void 0);
+    }
+    return async () => void 0;
+  }
+  /**
+   * Stateless abort. Calls `turn/interrupt` against the in-sandbox
+   * app-server using `(sessionId, turnId)` provided by the caller —
+   * the SDK does not persist turn state itself; bookkeeping the
+   * current turnId is the caller's responsibility (e.g. via Redis,
+   * driven by the normalized `message.started` event whose
+   * `messageId` IS the codex turnId).
+   *
+   * If `sessionId` or `turnId` is missing the call is a no-op.
+   */
+  async attachAbort(request) {
+    const threadId = request.sessionId;
+    const turnId = request.turnId;
+    if (!threadId || !turnId) {
+      debugCodex(
+        "attachAbort runId=%s skipped: threadId=%s turnId=%s",
+        request.runId,
+        threadId,
+        turnId
+      );
+      return;
+    }
+    await withCodexAppServer(request, async (client) => {
+      await Promise.race([
+        client.request("turn/interrupt", { threadId, turnId }),
+        new Promise(
+          (_, reject) => setTimeout(
+            () => reject(new Error("codex turn/interrupt timed out")),
+            3e3
+          )
+        )
+      ]).catch((error) => {
+        debugCodex(
+          "attachAbort runId=%s turn/interrupt failed: %o",
+          request.runId,
+          error
+        );
+      });
+    });
+  }
+  /**
+   * Stateless message injection. Uses `request.sessionId` as the codex
+   * threadId and starts a fresh turn against it via `turn/start`.
+   */
+  async attachSendMessage(request, content) {
+    const threadId = request.sessionId;
+    if (!threadId) {
+      throw new Error(
+        `Cannot attachSendMessage to codex run ${request.runId}: sessionId (threadId) is required.`
+      );
+    }
+    const parts = normalizeUserInput(content);
+    const text = joinTextParts(
+      parts.filter(
+        (part) => part.type === "text"
+      )
+    );
+    const inputItems = [];
+    if (text.trim().length > 0) {
+      inputItems.push({ type: "text", text, text_elements: [] });
+    }
+    await withCodexAppServer(request, async (client) => {
+      await client.request("turn/start", {
+        threadId,
+        input: inputItems,
+        approvalPolicy: "never",
+        model: null,
+        effort: null,
+        outputSchema: null
+      });
+    });
+  }
+};
+
+// src/agents/providers/opencode.ts
+import path10 from "path";
+var SANDBOX_OPENCODE_PORT = 4096;
+var LOCAL_OPENCODE_PORT = 4096;
+var SANDBOX_OPENCODE_READY_TIMEOUT_MS = 9e4;
+var LOCAL_OPENCODE_READY_TIMEOUT_MS = 2e4;
+var SHARED_OPENCODE_TARGET_ID = "shared-opencode-server";
+function toRawEvent3(runId, payload, type) {
+  return {
+    provider: AgentProvider.OpenCode,
+    runId,
+    type,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    payload
+  };
+}
+function extractText(value) {
+  if (!value) {
+    return "";
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(extractText).filter(Boolean).join("");
+  }
+  if (typeof value === "object") {
+    const record = value;
+    if (record.type === "text" && typeof record.text === "string") {
+      return record.text;
+    }
+    if (record.type === "reasoning") {
+      return "";
+    }
+    if (record.message) {
+      return extractText(record.message);
+    }
+    if (record.content) {
+      return extractText(record.content);
+    }
+    if (record.parts) {
+      return extractText(record.parts);
+    }
+    if (record.text) {
+      return extractText(record.text);
+    }
+  }
+  return "";
+}
+function extractAssistantMessageId(response) {
+  if (!response || typeof response !== "object") {
+    return void 0;
+  }
+  const record = response;
+  const info = record.info && typeof record.info === "object" ? record.info : record.message && typeof record.message === "object" ? record.message : void 0;
+  const id = info?.id ?? record.id;
+  return typeof id === "string" ? id : void 0;
+}
+function extractReasoning(value) {
+  if (!value) {
+    return "";
+  }
+  if (Array.isArray(value)) {
+    return value.map(extractReasoning).filter(Boolean).join("");
+  }
+  if (typeof value === "object") {
+    const record = value;
+    if (record.type === "reasoning") {
+      if (typeof record.text === "string") {
+        return record.text;
+      }
+      if (typeof record.reasoning === "string") {
+        return record.reasoning;
+      }
+    }
+    return [
+      extractReasoning(record.message),
+      extractReasoning(record.content),
+      extractReasoning(record.parts)
+    ].filter(Boolean).join("");
+  }
+  return "";
+}
+function toOpenCodeModel(model) {
+  if (!model) {
+    return void 0;
+  }
+  const slashIndex = model.indexOf("/");
+  if (slashIndex === -1) {
+    return { modelID: model };
+  }
+  const providerID = model.slice(0, slashIndex).trim();
+  const modelID = model.slice(slashIndex + 1).trim();
+  if (!providerID || !modelID) {
+    return { modelID: model };
+  }
+  return { providerID, modelID };
+}
+function buildOpenCodePermissionConfig(interactive) {
+  if (!interactive) {
+    return {
+      read: { "*": "allow" },
+      edit: "allow",
+      bash: "allow",
+      webfetch: "allow",
+      external_directory: "allow",
+      skill: { "*": "allow" },
+      task: "allow"
+    };
+  }
+  return {
+    read: { "*": "allow" },
+    edit: "ask",
+    bash: "ask",
+    webfetch: "ask",
+    external_directory: "ask",
+    skill: { "*": "allow" },
+    task: "ask"
+  };
+}
+function createOpenCodePermissionEvent(request, raw, payload) {
+  const properties = payload.properties ?? {};
+  const permission = String(properties.permission ?? "tool");
+  return createNormalizedEvent(
+    "permission.requested",
+    {
+      provider: request.provider,
+      runId: request.runId,
+      raw
+    },
+    {
+      requestId: String(properties.id ?? ""),
+      kind: permission === "bash" ? "bash" : permission === "edit" ? "edit" : permission === "external_directory" ? "file-change" : permission === "webfetch" ? "network" : permission === "task" ? "tool" : "unknown",
+      title: `Approve ${permission} permission`,
+      message: typeof properties.metadata === "object" && properties.metadata !== null ? JSON.stringify(properties.metadata) : `OpenCode requested ${permission} permission.`,
+      input: properties,
+      canRemember: Array.isArray(properties.always) && properties.always.length > 0
+    }
+  );
+}
+var OPEN_CODE_REASONING_LEVELS = ["low", "medium", "high", "xhigh"];
+function openCodeAgentSlug(reasoning) {
+  return reasoning ? `agentbox-${reasoning}` : "agentbox";
+}
+function buildOpenCodeConfig(options, systemPrompt, interactiveApproval) {
+  const mcpConfig = buildOpenCodeMcpConfig(options.mcps);
+  const commandsConfig = buildOpenCodeCommandsConfig(options.commands);
+  const baseAgent = {
+    mode: "primary",
+    prompt: systemPrompt,
+    permission: buildOpenCodePermissionConfig(interactiveApproval),
+    tools: {
+      write: true,
+      edit: true,
+      bash: true,
+      webfetch: true,
+      skill: true
+    }
+  };
+  const reasoningVariants = Object.fromEntries(
+    OPEN_CODE_REASONING_LEVELS.map((level) => [
+      `agentbox-${level}`,
+      { ...baseAgent, reasoningEffort: level }
+    ])
+  );
+  return {
+    $schema: "https://opencode.ai/config.json",
+    ...mcpConfig ? { mcp: mcpConfig } : {},
+    ...commandsConfig ? { command: commandsConfig } : {},
+    agent: {
+      agentbox: baseAgent,
+      ...reasoningVariants,
+      ...buildOpenCodeSubagentConfig(options.subAgents)
+    }
+  };
+}
+async function ensureSandboxOpenCodeServer(request) {
+  return time(debugOpencode, "ensureSandboxOpenCodeServer", async () => {
+    const sandbox = request.options.sandbox;
+    const options = request.options;
+    const port = SANDBOX_OPENCODE_PORT;
+    const healthCheck = await time(
+      debugOpencode,
+      "health probe (warm path)",
+      () => sandbox.run(
+        `curl -fsS http://127.0.0.1:${port}/global/health >/dev/null 2>&1`,
+        { cwd: options.cwd, timeoutMs: 5e3 }
+      )
+    );
+    if (healthCheck.exitCode === 0) {
+      debugOpencode("opencode server already running \u2014 reusing");
+      return;
+    }
+    debugOpencode("opencode server not running \u2014 cold-spawning");
+    const plugins = assertHooksSupported(request.provider, options);
+    assertCommandsSupported(request.provider, options.commands);
+    const interactiveApproval = isInteractiveApproval(options);
+    const target = await createSetupTarget(
+      request.provider,
+      SHARED_OPENCODE_TARGET_ID,
+      options
+    );
+    const { artifacts: skillArtifacts, installCommands } = await prepareSkillArtifacts(
+      request.provider,
+      options.skills,
+      target.layout
+    );
+    const pluginArtifacts = buildOpenCodePluginArtifacts(
+      plugins,
+      target.layout.opencodeDir
+    );
+    const configPath = path10.join(target.layout.opencodeDir, "agentbox.json");
+    const openCodeConfig = buildOpenCodeConfig(
+      options,
+      request.config.systemPrompt ?? "",
+      interactiveApproval
+    );
+    const commonEnv = {
+      OPENCODE_CONFIG: configPath,
+      OPENCODE_CONFIG_DIR: target.layout.opencodeDir,
+      OPENCODE_DISABLE_DEFAULT_PLUGINS: "true"
+    };
+    await applyDifferentialSetup(
+      target,
+      [
+        ...skillArtifacts,
+        ...pluginArtifacts,
+        {
+          path: configPath,
+          content: JSON.stringify(openCodeConfig, null, 2)
+        }
+      ],
+      installCommands
+    );
+    const binary = options.provider?.binary ?? "opencode";
+    const pidFilePath = path10.posix.join(
+      target.layout.rootDir,
+      "opencode-serve.pid"
+    );
+    const logFilePath = path10.posix.join(
+      target.layout.rootDir,
+      "opencode-serve.log"
+    );
+    const serveEnv = { ...options.env ?? {}, ...commonEnv };
+    const launchCommand = [
+      `mkdir -p ${shellQuote(target.layout.rootDir)}`,
+      `(${[
+        `nohup ${[
+          binary,
+          "serve",
+          "--hostname",
+          "0.0.0.0",
+          "--port",
+          String(port),
+          ...options.provider?.args ?? []
+        ].map(shellQuote).join(" ")} > ${shellQuote(logFilePath)} 2>&1 &`,
+        `echo $! > ${shellQuote(pidFilePath)}`
+      ].join(" ")})`
+    ].join(" && ");
+    const launchResult = await time(
+      debugOpencode,
+      "spawn opencode serve",
+      async () => {
+        const launchHandle = await sandbox.runAsync(launchCommand, {
+          cwd: options.cwd,
+          env: serveEnv
+        });
+        return launchHandle.wait();
+      }
+    );
+    if (launchResult.exitCode !== 0) {
+      await target.cleanup().catch(() => void 0);
+      throw new Error(
+        `Could not start OpenCode server: ${launchResult.combinedOutput || launchResult.stderr}`
+      );
+    }
+    await time(debugOpencode, "poll opencode until ready", async () => {
+      const readyDeadline = Date.now() + SANDBOX_OPENCODE_READY_TIMEOUT_MS;
+      let attempt = 0;
+      while (Date.now() < readyDeadline) {
+        attempt++;
+        const probe = await sandbox.run(
+          `curl -fsS http://127.0.0.1:${port}/global/health >/dev/null 2>&1`,
+          { cwd: options.cwd, timeoutMs: 5e3 }
+        );
+        if (probe.exitCode === 0) {
+          debugOpencode("ready after %d probe attempt(s)", attempt);
+          return;
+        }
+        await sleep(500);
+      }
+      await target.cleanup().catch(() => void 0);
+      throw new Error(
+        `OpenCode server did not become ready within ${SANDBOX_OPENCODE_READY_TIMEOUT_MS}ms.`
+      );
+    });
+  });
+}
+async function ensureLocalOpenCodeServer(request) {
+  const options = request.options;
+  try {
+    await waitForHttpReady(
+      `http://127.0.0.1:${LOCAL_OPENCODE_PORT}/global/health`,
+      { timeoutMs: 1e3 }
+    );
+    debugOpencode("local opencode server already running \u2014 reusing");
+    return;
+  } catch {
+    debugOpencode("local opencode server not running \u2014 cold-spawning");
+  }
+  const plugins = assertHooksSupported(request.provider, options);
+  assertCommandsSupported(request.provider, options.commands);
+  const interactiveApproval = isInteractiveApproval(options);
+  const target = await createSetupTarget(
+    request.provider,
+    "shared-setup",
+    options
+  );
+  const { artifacts: skillArtifacts, installCommands } = await prepareSkillArtifacts(
+    request.provider,
+    options.skills,
+    target.layout
+  );
+  const pluginArtifacts = buildOpenCodePluginArtifacts(
+    plugins,
+    target.layout.opencodeDir
+  );
+  const configPath = path10.join(target.layout.opencodeDir, "agentbox.json");
+  const openCodeConfig = buildOpenCodeConfig(
+    options,
+    request.config.systemPrompt ?? "",
+    interactiveApproval
+  );
+  const commonEnv = {
+    OPENCODE_CONFIG: configPath,
+    OPENCODE_CONFIG_DIR: target.layout.opencodeDir,
+    OPENCODE_DISABLE_DEFAULT_PLUGINS: "true"
+  };
+  await applyDifferentialSetup(
+    target,
+    [
+      ...skillArtifacts,
+      ...pluginArtifacts,
+      {
+        path: configPath,
+        content: JSON.stringify(openCodeConfig, null, 2)
+      }
+    ],
+    installCommands
+  );
+  spawnCommand({
+    command: options.provider?.binary ?? "opencode",
+    args: [
+      "serve",
+      "--hostname",
+      "127.0.0.1",
+      "--port",
+      String(LOCAL_OPENCODE_PORT),
+      ...options.provider?.args ?? []
+    ],
+    cwd: options.cwd,
+    env: {
+      ...process.env,
+      ...options.env ?? {},
+      ...commonEnv
+    }
+  });
+  await waitForHttpReady(
+    `http://127.0.0.1:${LOCAL_OPENCODE_PORT}/global/health`,
+    { timeoutMs: LOCAL_OPENCODE_READY_TIMEOUT_MS }
+  );
+}
+async function setupOpenCode(request) {
+  if (request.options.sandbox) {
+    await ensureSandboxOpenCodeServer(request);
+    return;
+  }
+  await ensureLocalOpenCodeServer(request);
+}
+async function buildOpenCodeRuntime(options) {
+  if (options.sandbox) {
+    const sandbox = options.sandbox;
+    const baseUrl2 = (await sandbox.getPreviewLink(SANDBOX_OPENCODE_PORT)).replace(/\/$/, "");
+    return {
+      baseUrl: baseUrl2,
+      previewHeaders: sandbox.previewHeaders,
+      raw: { baseUrl: baseUrl2, port: SANDBOX_OPENCODE_PORT }
+    };
+  }
+  const baseUrl = `http://127.0.0.1:${LOCAL_OPENCODE_PORT}`;
+  return {
+    baseUrl,
+    previewHeaders: {},
+    raw: { baseUrl, port: LOCAL_OPENCODE_PORT }
+  };
+}
+var OpenCodeAgentAdapter = class {
+  async setup(request) {
+    await setupOpenCode(request);
+  }
+  async execute(request, sink) {
+    const executeStartedAt = Date.now();
+    debugOpencode("execute() start runId=%s", request.runId);
+    const inputParts = await time(
+      debugOpencode,
+      "validateProviderUserInput",
+      () => validateProviderUserInput(request.provider, request.run.input)
+    );
+    let pendingMessages = 0;
+    let finalText = "";
+    let streamedTextFromSse = "";
+    const settledMessageIds = /* @__PURE__ */ new Set();
+    let dispatchError;
+    let firstSseEventLogged = false;
+    let resolveAllDone;
+    const allDone = new Promise((resolve) => {
+      resolveAllDone = resolve;
+    });
+    const checkDone = () => {
+      if (pendingMessages === 0) {
+        resolveAllDone();
+      }
+    };
+    let sendToSession;
+    const queuedParts = [];
+    sink.onMessage(async (content) => {
+      pendingMessages++;
+      try {
+        const parts = await validateProviderUserInput(
+          request.provider,
+          content
+        );
+        const mapped = mapToOpenCodeParts(parts);
+        if (sendToSession) {
+          sendToSession(mapped);
+        } else {
+          queuedParts.push(mapped);
+        }
+      } catch (error) {
+        pendingMessages--;
+        if (!dispatchError) {
+          dispatchError = error;
+        }
+        checkDone();
+        throw error;
+      }
+    });
+    const runtime = await time(
+      debugOpencode,
+      "buildOpenCodeRuntime",
+      () => buildOpenCodeRuntime(request.options)
+    );
+    sink.setRaw(runtime.raw);
+    sink.emitEvent(
+      createNormalizedEvent("run.started", {
+        provider: request.provider,
+        runId: request.runId
+      })
+    );
+    const rawPayloads = [];
+    const sseAbort = new AbortController();
+    let sseTask;
+    const dispatchAbort = new AbortController();
+    let capturedSessionId;
+    sink.setAbort(async () => {
+      const sessionIdAtAbort = capturedSessionId;
+      if (sessionIdAtAbort) {
+        try {
+          await Promise.race([
+            fetchJson(
+              `${runtime.baseUrl}/session/${sessionIdAtAbort}/abort`,
+              {
+                method: "POST",
+                headers: {
+                  "content-type": "application/json",
+                  ...runtime.previewHeaders
+                }
+              }
+            ),
+            new Promise(
+              (_, reject) => setTimeout(
+                () => reject(new Error("opencode POST /session/abort timed out")),
+                3e3
+              )
+            )
+          ]);
+        } catch {
+        }
+      }
+      dispatchAbort.abort();
+    });
+    try {
+      const interactiveApproval = isInteractiveApproval(request.options);
+      const createdSession = request.run.resumeSessionId ? null : await fetchJson(
+        `${runtime.baseUrl}/session`,
+        {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            ...runtime.previewHeaders
+          },
+          body: JSON.stringify({
+            title: `AgentBox ${request.runId}`
+          })
+        }
+      );
+      const sessionId = request.run.resumeSessionId ?? createdSession?.id ?? createdSession?.sessionId;
+      if (!sessionId) {
+        throw new Error("OpenCode did not return a session id.");
+      }
+      const announcedUserMessageIds = /* @__PURE__ */ new Set();
+      const foreignMessageIds = /* @__PURE__ */ new Set();
+      sseTask = (async () => {
+        try {
+          for await (const event of streamSse(`${runtime.baseUrl}/event`, {
+            headers: runtime.previewHeaders,
+            signal: sseAbort.signal
+          })) {
+            if (!firstSseEventLogged) {
+              firstSseEventLogged = true;
+              debugOpencode(
+                "\u2605 first SSE event (%dms since execute start) type=%s",
+                Date.now() - executeStartedAt,
+                event.event
+              );
+            }
+            let payload = event.data;
+            try {
+              payload = JSON.parse(event.data);
+            } catch {
+            }
+            const raw = toRawEvent3(
+              request.runId,
+              payload,
+              `sse:${event.event ?? "message"}`
+            );
+            if (payload && typeof payload === "object" && !Array.isArray(payload)) {
+              rawPayloads.push(payload);
+            }
+            sink.emitRaw(raw);
+            const eventType = typeof payload?.type === "string" ? String(payload.type) : event.event;
+            if (eventType === "message.updated") {
+              const properties = payload.properties;
+              const info = properties?.info;
+              if (info && typeof info.id === "string" && typeof info.sessionID === "string") {
+                if (info.sessionID !== sessionId) {
+                  foreignMessageIds.add(info.id);
+                } else if (info.role === "user" && !announcedUserMessageIds.has(info.id)) {
+                  announcedUserMessageIds.add(info.id);
+                  sink.emitEvent(
+                    createNormalizedEvent(
+                      "message.started",
+                      {
+                        provider: request.provider,
+                        runId: request.runId,
+                        raw
+                      },
+                      { messageId: info.id }
+                    )
+                  );
+                }
+              }
+            }
+            if (eventType === "permission.asked") {
+              const properties = payload.properties;
+              if (properties && typeof properties.sessionID === "string" && properties.sessionID === sessionId) {
+                const permissionEvent = createOpenCodePermissionEvent(
+                  request,
+                  raw,
+                  payload
+                );
+                const response = interactiveApproval ? await sink.requestPermission(permissionEvent) : {
+                  requestId: permissionEvent.requestId,
+                  decision: "allow"
+                };
+                await fetchJson(
+                  `${runtime.baseUrl}/session/${sessionId}/permissions/${permissionEvent.requestId}`,
+                  {
+                    method: "POST",
+                    headers: {
+                      "content-type": "application/json",
+                      ...runtime.previewHeaders
+                    },
+                    body: JSON.stringify({
+                      response: response.decision === "allow" ? response.remember ? "always" : "once" : "reject"
+                    })
+                  }
+                );
+              }
+              continue;
+            }
+            const payloadRecord = payload && typeof payload === "object" && !Array.isArray(payload) ? payload : null;
+            if ((payloadRecord?.type === "session.idle" || payloadRecord?.type === "session.error") && !dispatchAbort.signal.aborted) {
+              const properties = payloadRecord.properties;
+              const eventSessionId = typeof properties?.sessionID === "string" ? properties.sessionID : void 0;
+              if (!eventSessionId || eventSessionId === sessionId) {
+                debugOpencode(
+                  "\u2605 %s for session=%s \u2014 aborting in-flight dispatch",
+                  payloadRecord.type,
+                  sessionId
+                );
+                dispatchAbort.abort();
+              }
+            }
+            if (payloadRecord?.type === "message.part.delta") {
+              const properties = payloadRecord.properties;
+              const eventSessionId = typeof properties?.sessionID === "string" ? properties.sessionID : void 0;
+              const eventMessageId = typeof properties?.messageID === "string" ? properties.messageID : void 0;
+              const isForeignSession = eventSessionId !== void 0 && eventSessionId !== sessionId || eventSessionId === void 0 && eventMessageId !== void 0 && foreignMessageIds.has(eventMessageId);
+              if (isForeignSession) {
+                continue;
+              }
+              if (eventMessageId !== void 0 && settledMessageIds.has(eventMessageId)) {
+                continue;
+              }
+              const delta = typeof properties?.delta === "string" ? properties.delta : "";
+              if (delta && properties?.field === "text") {
+                streamedTextFromSse += delta;
+                sink.emitEvent(
+                  createNormalizedEvent(
+                    "text.delta",
+                    {
+                      provider: request.provider,
+                      runId: request.runId,
+                      raw
+                    },
+                    { delta }
+                  )
+                );
+              } else if (delta && (properties?.field === "reasoning" || properties?.field === "thinking")) {
+                sink.emitEvent(
+                  createNormalizedEvent(
+                    "reasoning.delta",
+                    {
+                      provider: request.provider,
+                      runId: request.runId,
+                      raw
+                    },
+                    { delta }
+                  )
+                );
+              }
+            } else {
+              for (const normalized of normalizeRawAgentEvent(raw)) {
+                sink.emitEvent(normalized);
+              }
+            }
+          }
+        } catch {
+        }
+      })();
+      capturedSessionId = sessionId;
+      sink.setSessionId(sessionId);
+      sink.emitRaw(
+        toRawEvent3(
+          request.runId,
+          createdSession ?? { sessionId },
+          request.run.resumeSessionId ? "session.resumed" : "session.created"
+        )
+      );
+      if (createdSession) {
+        rawPayloads.push(createdSession);
+      }
+      sink.emitEvent(
+        createNormalizedEvent("message.started", {
+          provider: request.provider,
+          runId: request.runId
+        })
+      );
+      const agentSlug = openCodeAgentSlug(request.run.reasoning);
+      const dispatchMessage = async (parts) => {
+        const sseTextLengthBeforeDispatch = streamedTextFromSse.length;
+        try {
+          const response = await fetchJson(
+            `${runtime.baseUrl}/session/${sessionId}/message`,
+            {
+              method: "POST",
+              signal: dispatchAbort.signal,
+              headers: {
+                "content-type": "application/json",
+                ...runtime.previewHeaders
+              },
+              body: JSON.stringify({
+                ...request.run.model ? { model: toOpenCodeModel(request.run.model) } : {},
+                agent: agentSlug,
+                parts
+              })
+            }
+          );
+          const rawResponse = toRawEvent3(
+            request.runId,
+            response,
+            "message.response"
+          );
+          if (response && typeof response === "object" && !Array.isArray(response)) {
+            rawPayloads.push(response);
+          }
+          sink.emitRaw(rawResponse);
+          for (const event of normalizeRawAgentEvent(rawResponse)) {
+            sink.emitEvent(event);
+          }
+          const reasoning = extractReasoning(response);
+          if (reasoning) {
+            sink.emitEvent(
+              createNormalizedEvent(
+                "reasoning.delta",
+                {
+                  provider: request.provider,
+                  runId: request.runId,
+                  raw: rawResponse
+                },
+                { delta: reasoning }
+              )
+            );
+          }
+          const text = extractText(response);
+          if (text) {
+            finalText = text;
+            const sseTextForThisDispatch = streamedTextFromSse.slice(
+              sseTextLengthBeforeDispatch
+            );
+            let missing;
+            if (text.startsWith(sseTextForThisDispatch)) {
+              missing = text.slice(sseTextForThisDispatch.length);
+            } else if (sseTextForThisDispatch.length === 0) {
+              missing = text;
+            } else {
+              missing = "";
+            }
+            if (missing.length > 0) {
+              streamedTextFromSse += missing;
+              sink.emitEvent(
+                createNormalizedEvent(
+                  "text.delta",
+                  {
+                    provider: request.provider,
+                    runId: request.runId
+                  },
+                  { delta: missing }
+                )
+              );
+            }
+            const assistantMessageId = extractAssistantMessageId(response);
+            if (assistantMessageId) {
+              settledMessageIds.add(assistantMessageId);
+            }
+          }
+        } catch (error) {
+          if (!dispatchError) {
+            dispatchError = error;
+          }
+        } finally {
+          pendingMessages--;
+          checkDone();
+        }
+      };
+      sendToSession = (parts) => {
+        void dispatchMessage(parts);
+      };
+      for (const queued of queuedParts.splice(0)) {
+        sendToSession(queued);
+      }
+      pendingMessages++;
+      void dispatchMessage(mapToOpenCodeParts(inputParts));
+      await allDone;
+      if (dispatchError && !dispatchAbort.signal.aborted) {
+        throw dispatchError;
+      }
+      debugOpencode(
+        "\u2605 run.completed (%dms since execute start) chars=%d",
+        Date.now() - executeStartedAt,
+        finalText.length
+      );
+      sink.emitEvent(
+        createNormalizedEvent(
+          "run.completed",
+          {
+            provider: request.provider,
+            runId: request.runId
+          },
+          { text: finalText }
+        )
+      );
+      sseAbort.abort();
+      await sseTask;
+      sink.complete({
+        text: finalText,
+        costData: extractOpenCodeCostData(rawPayloads)
+      });
+    } finally {
+      sseAbort.abort();
+      if (sseTask) {
+        await sseTask.catch(() => void 0);
+      }
+    }
+    return async () => void 0;
+  }
+  /**
+   * Stateless abort. Resolve the in-sandbox base URL via
+   * `sandbox.getPreviewLink` and POST to `/session/:id/abort`. Best-effort:
+   * a 3s timeout protects against an unresponsive server, and any error
+   * is swallowed since the originating run will tear itself down once
+   * the server-side abort takes effect.
+   */
+  async attachAbort(request) {
+    if (!request.sessionId) {
+      throw new Error(
+        `Cannot attachAbort to opencode run ${request.runId}: sessionId is required.`
+      );
+    }
+    const baseUrl = (await request.sandbox.getPreviewLink(SANDBOX_OPENCODE_PORT)).replace(/\/$/, "");
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 3e3);
+    try {
+      await fetch(`${baseUrl}/session/${request.sessionId}/abort`, {
+        method: "POST",
+        signal: controller.signal,
+        headers: {
+          "content-type": "application/json",
+          ...request.sandbox.previewHeaders
+        }
+      }).catch((error) => {
+        debugOpencode(
+          "attachAbort runId=%s POST /abort failed: %o",
+          request.runId,
+          error
+        );
+      });
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  /**
+   * Stateless message injection. POST a fresh user message to
+   * `/session/:id/message` with `agent` defaulting to the build agent
+   * — opencode appends it to the running session and the originating
+   * instance picks up the new turn through its existing SSE stream.
+   */
+  async attachSendMessage(request, content) {
+    if (!request.sessionId) {
+      throw new Error(
+        `Cannot attachSendMessage to opencode run ${request.runId}: sessionId is required.`
+      );
+    }
+    const baseUrl = (await request.sandbox.getPreviewLink(SANDBOX_OPENCODE_PORT)).replace(/\/$/, "");
+    const inputParts = await validateProviderUserInput(
+      AgentProvider.OpenCode,
+      content
+    );
+    const parts = mapToOpenCodeParts(inputParts);
+    await fetchJson(
+      `${baseUrl}/session/${request.sessionId}/message`,
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          ...request.sandbox.previewHeaders
+        },
+        body: JSON.stringify({
+          agent: openCodeAgentSlug(void 0),
+          parts
+        })
+      }
+    );
+  }
+};
+
+// src/agents/Agent.ts
+function buildAgentOptionsSystemAppendix(options) {
+  const sections = [];
+  if (options.mcps?.length) {
+    sections.push(
+      [
+        "Configured MCP servers are available for this run:",
+        ...options.mcps.map((mcp) => `- ${mcp.name}`)
+      ].join("\n")
+    );
+  }
+  if (options.skills?.length) {
+    sections.push(
+      [
+        "Configured skills are available for this run:",
+        ...options.skills.map((skill) => `- ${skill.name}`)
+      ].join("\n")
+    );
+  }
+  if (options.subAgents?.length) {
+    sections.push(
+      [
+        "Configured sub-agents are available for delegation:",
+        ...options.subAgents.map(
+          (subAgent) => `- ${subAgent.name}: ${subAgent.description}`
+        )
+      ].join("\n")
+    );
+  }
+  if (options.commands?.length) {
+    sections.push(
+      [
+        "Custom commands are installed for this environment:",
+        ...options.commands.map(
+          (command) => `- /${command.name}${command.description ? `: ${command.description}` : ""}`
+        )
+      ].join("\n")
+    );
+  }
+  return sections.length > 0 ? sections.join("\n\n") : void 0;
+}
+function buildRunConfig(options, runConfig) {
+  const appendix = buildAgentOptionsSystemAppendix(options);
+  const systemPrompt = [runConfig.systemPrompt, appendix].filter(Boolean).join("\n\n");
+  return {
+    ...runConfig,
+    ...systemPrompt ? { systemPrompt } : {}
+  };
+}
+function createAdapter(provider) {
+  switch (provider) {
+    case AgentProvider.Codex:
+      return new CodexAgentAdapter();
+    case AgentProvider.OpenCode:
+      return new OpenCodeAgentAdapter();
+    case AgentProvider.ClaudeCode:
+      return new ClaudeCodeAgentAdapter();
+    default:
+      throw new UnsupportedProviderError("agent", provider);
+  }
+}
+function prepareAgentOptions(_provider, options) {
+  return options;
+}
+var AgentRunController = class {
+  id;
+  provider;
+  sessionId;
+  raw;
+  sessionIdReady;
+  abortHandler = async () => void 0;
+  abortRequested = false;
+  eventQueue = new AsyncQueue();
+  rawQueue = new AsyncQueue();
+  events = [];
+  rawEventsList = [];
+  pendingPermissions = /* @__PURE__ */ new Map();
+  messageHandler;
+  text = "";
+  costData = null;
+  settled = false;
+  finished;
+  resolveSessionIdReady;
+  rejectSessionIdReady;
+  resolveFinished;
+  rejectFinished;
+  constructor(provider, id) {
+    this.provider = provider;
+    this.id = id;
+    let resolveFinished;
+    let rejectFinished;
+    let resolveSessionIdReady;
+    let rejectSessionIdReady;
+    this.finished = new Promise((resolve, reject) => {
+      resolveFinished = resolve;
+      rejectFinished = reject;
+    });
+    this.sessionIdReady = new Promise((resolve, reject) => {
+      resolveSessionIdReady = resolve;
+      rejectSessionIdReady = reject;
+    });
+    void this.sessionIdReady.catch(() => void 0);
+    this.resolveFinished = resolveFinished;
+    this.rejectFinished = rejectFinished;
+    this.resolveSessionIdReady = resolveSessionIdReady;
+    this.rejectSessionIdReady = rejectSessionIdReady;
+  }
+  setRaw(raw) {
+    this.raw = raw;
+  }
+  setAbort(abort) {
+    this.abortHandler = abort;
+    if (this.abortRequested) {
+      void abort();
+    }
+  }
+  setSessionId(sessionId) {
+    if (this.sessionId) {
+      return;
+    }
+    this.sessionId = sessionId;
+    this.resolveSessionIdReady(sessionId);
+  }
+  emitRaw(event) {
+    this.rawEventsList.push(event);
+    this.rawQueue.push(event);
+  }
+  pushEvent(event) {
+    this.events.push(event);
+    if (event.type === "text.delta") {
+      this.text += event.delta;
+    } else if ((event.type === "message.completed" || event.type === "run.completed") && event.text) {
+      this.text = event.text;
+    }
+    this.eventQueue.push(event);
+  }
+  emitEvent(event) {
+    this.pushEvent(event);
+  }
+  requestPermission(event) {
+    if (this.settled) {
+      throw new Error("Cannot request permission on a settled agent run.");
+    }
+    if (this.pendingPermissions.has(event.requestId)) {
+      throw new Error(
+        `Permission request ${event.requestId} is already pending for this run.`
+      );
+    }
+    const response = new Promise((resolve, reject) => {
+      this.pendingPermissions.set(event.requestId, {
+        event,
+        resolve,
+        reject
+      });
+    });
+    this.pushEvent(event);
+    return response;
+  }
+  onMessage(handler) {
+    this.messageHandler = handler;
+  }
+  async sendMessage(content) {
+    if (this.settled) {
+      throw new Error("Cannot send a message on a settled agent run.");
+    }
+    if (!this.messageHandler) {
+      throw new Error(
+        "This provider does not support sending messages during a run."
+      );
+    }
+    const textContent = normalizeUserInput(content).filter((p) => p.type === "text").map((p) => p.text).join("");
+    const handlerResult = await this.messageHandler(content);
+    const messageId = handlerResult?.messageId;
+    this.pushEvent(
+      createNormalizedEvent(
+        "message.injected",
+        { provider: this.provider, runId: this.id },
+        {
+          content: textContent || "(non-text content)",
+          ...messageId ? { messageId } : {}
+        }
+      )
+    );
+  }
+  async respondToPermission(response) {
+    const pending = this.pendingPermissions.get(response.requestId);
+    if (!pending) {
+      throw new Error(
+        `Permission request ${response.requestId} is not pending for this run.`
+      );
+    }
+    this.pendingPermissions.delete(response.requestId);
+    const remember = pending.event.canRemember ? response.remember : void 0;
+    const resolvedResponse = {
+      requestId: response.requestId,
+      decision: response.decision,
+      ...remember !== void 0 ? { remember } : {}
+    };
+    this.pushEvent(
+      createNormalizedEvent(
+        "permission.resolved",
+        {
+          provider: this.provider,
+          runId: this.id
+        },
+        {
+          requestId: response.requestId,
+          decision: response.decision,
+          ...remember !== void 0 ? { remember } : {}
+        }
+      )
+    );
+    pending.resolve(resolvedResponse);
+  }
+  clearPendingPermissions(error) {
+    for (const pending of this.pendingPermissions.values()) {
+      pending.reject(error);
+    }
+    this.pendingPermissions.clear();
+  }
+  complete(result) {
+    if (this.settled) {
+      return;
+    }
+    this.settled = true;
+    this.clearPendingPermissions(
+      new Error(
+        "Agent run completed before pending permission requests resolved."
+      )
+    );
+    if (result?.text) {
+      this.text = result.text;
+    }
+    if (result && "costData" in result) {
+      this.costData = result.costData ?? null;
+    }
+    this.eventQueue.finish();
+    this.rawQueue.finish();
+    if (!this.sessionId) {
+      const error = new Error(
+        "Agent run completed before a provider session id was set."
+      );
+      this.rejectSessionIdReady(error);
+      this.rejectFinished(error);
+      return;
+    }
+    this.resolveFinished({
+      id: this.id,
+      provider: this.provider,
+      sessionId: this.sessionId,
+      text: this.text,
+      rawEvents: [...this.rawEventsList],
+      events: [...this.events],
+      costData: this.costData
+    });
+  }
+  fail(error) {
+    if (this.settled) {
+      return;
+    }
+    const normalizedError = asError(error);
+    this.clearPendingPermissions(normalizedError);
+    this.emitEvent(
+      createNormalizedEvent(
+        "run.error",
+        {
+          provider: this.provider,
+          runId: this.id
+        },
+        {
+          error: normalizedError.message
+        }
+      )
+    );
+    this.settled = true;
+    this.eventQueue.finish();
+    this.rawQueue.finish();
+    if (!this.sessionId) {
+      this.rejectSessionIdReady(normalizedError);
+    }
+    this.rejectFinished(normalizedError);
+  }
+  async abort() {
+    this.abortRequested = true;
+    await this.abortHandler();
+  }
+  rawEvents() {
+    return this.rawQueue;
+  }
+  toAISDKEvents() {
+    return toAISDKStream(this);
+  }
+  [Symbol.asyncIterator]() {
+    return this.eventQueue[Symbol.asyncIterator]();
+  }
+};
+var Agent = class {
+  adapter;
+  provider;
+  options;
+  setupPromise;
+  constructor(provider, options) {
+    this.provider = provider;
+    this.options = prepareAgentOptions(provider, options);
+    this.adapter = createAdapter(provider);
+  }
+  /**
+   * The sandbox the agent will run inside, if any was passed via
+   * `options.sandbox`. Returns `undefined` for host-mode runs (no sandbox).
+   */
+  get sandbox() {
+    return this.options.sandbox;
+  }
+  /**
+   * Prepare provider-specific runtime state on the configured sandbox
+   * (skill artifacts, MCP/hook/sub-agent config, app-server / relay boot, …).
+   *
+   * `setup()` is REQUIRED before {@link Agent.stream} or {@link Agent.run}
+   * for any sandbox-backed run. `stream` and the underlying
+   * `adapter.execute` deliberately do not trigger setup themselves so
+   * callers can run sandbox-side preparation in parallel with other
+   * long-running work (e.g. `git clone`).
+   *
+   * `execute` does not consume any setup output and does not re-do
+   * setup work. It assumes the relay/server boot performed here is
+   * already up. Skipping `setup()` against a remote sandbox is a
+   * programmer error and surfaces as a connect-retry timeout inside
+   * `execute`, not a silent fallback.
+   *
+   * Idempotent across repeated invocations: subsequent calls return the
+   * promise from the first call. The differential setup cache and the
+   * relay/server probes also make this cheap on warm sandboxes — the
+   * second `setup()` against the same sandbox does ~one round-trip of
+   * work.
+   */
+  async setup(config = {}) {
+    if (this.setupPromise) {
+      await this.setupPromise;
+      return;
+    }
+    debugAgent("setup() provider=%s", this.provider);
+    const startedAt = Date.now();
+    this.setupPromise = (async () => {
+      await this.adapter.setup({
+        provider: this.provider,
+        options: this.options,
+        config
+      });
+      debugAgent(
+        "setup() returned provider=%s after %dms",
+        this.provider,
+        Date.now() - startedAt
+      );
+    })();
+    try {
+      await this.setupPromise;
+    } catch (error) {
+      this.setupPromise = void 0;
+      throw error;
+    }
+  }
+  stream(runConfig) {
+    const runId = runConfig.runId ?? randomUUID2();
+    const streamCalledAt = Date.now();
+    debugAgent("stream() provider=%s runId=%s", this.provider, runId);
+    const run = new AgentRunController(this.provider, runId);
+    const setupPromise = this.setupPromise;
+    const provider = this.provider;
+    const options = this.options;
+    const adapter = this.adapter;
+    void (async () => {
+      try {
+        if (setupPromise) {
+          await setupPromise;
+        }
+        const request = {
+          runId,
+          provider,
+          options,
+          run: buildRunConfig(options, runConfig)
+        };
+        const cleanup = await adapter.execute(request, run);
+        debugAgent(
+          "adapter.execute() returned for runId=%s after %dms",
+          runId,
+          Date.now() - streamCalledAt
+        );
+        run.setAbort(async () => {
+          await cleanup();
+        });
+      } catch (error) {
+        run.fail(error);
+      }
+    })();
+    return run;
+  }
+  async run(runConfig) {
+    return this.stream(runConfig).finished;
+  }
+  rawEvents(runConfig) {
+    return this.stream(runConfig).rawEvents();
+  }
+  /**
+   * Stateless control plane for an in-flight run.
+   *
+   * Returns an {@link AttachedRun} whose `abort()` / `sendMessage()` methods
+   * dial the in-sandbox provider server directly (codex app-server, opencode
+   * HTTP server, claude-code relay control endpoint) — there is no shared
+   * in-memory registry or Redis broker. Any process with the right `sandbox`
+   * + `runId` (+ optional provider-native `sessionId`) can issue commands
+   * against a run started on a different process.
+   *
+   * The originating process keeps owning the event stream that
+   * `agent.stream()` returned; commands attached here cause the in-sandbox
+   * server to emit the natural follow-up events (`turn/aborted`, message
+   * events, etc.), which the originating process ingests through its
+   * existing transport.
+   *
+   * The handle is short-lived: each method call opens a fresh connection,
+   * performs the operation with a timeout, and tears the connection down.
+   */
+  static async attach(request) {
+    const adapter = createAdapter(request.provider);
+    return {
+      abort: () => adapter.attachAbort(request),
+      sendMessage: (content) => adapter.attachSendMessage(request, content)
+    };
+  }
+};
+
+export {
+  Agent
+};