@agentstep/agent-sdk 0.1.0

package/src/backends/claude/tool-bridge.ts

@@ -0,0 +1,211 @@
+/**
+ * Custom tool bridge: generates a synthetic MCP stdio server that exposes
+ * Managed Agents custom tools to claude inside the container.
+ *
+ * Architecture:
+ *   - A Node.js script that implements the MCP stdio protocol (JSON-RPC on
+ *     stdin/stdout)
+ *   - Reads tool definitions from /tmp/tool-bridge/tools.json
+ *   - On tool call: checks for pre-existing response.json (replay after
+ *     --resume) and returns immediately. Otherwise writes request.json +
+ *     creates pending sentinel, then watches for response.json via
+ *     fs.watchFile and returns the result.
+ *
+ * The driver detects custom_tool_use via the translator's sawCustomToolUse()
+ * flag and stop_reason:"custom_tool_call". On user.custom_tool_result
+ * re-entry, the driver writes response.json and removes the pending sentinel
+ * before calling --resume.
+ */
+
+import type { CustomTool } from "../../types";
+
+export const TOOL_BRIDGE_DIR = "/tmp/tool-bridge";
+export const TOOL_BRIDGE_SCRIPT_PATH = `${TOOL_BRIDGE_DIR}/bridge.mjs`;
+export const TOOL_BRIDGE_TOOLS_PATH = `${TOOL_BRIDGE_DIR}/tools.json`;
+export const TOOL_BRIDGE_REQUEST_PATH = `${TOOL_BRIDGE_DIR}/request.json`;
+export const TOOL_BRIDGE_RESPONSE_PATH = `${TOOL_BRIDGE_DIR}/response.json`;
+export const TOOL_BRIDGE_PENDING_PATH = `${TOOL_BRIDGE_DIR}/pending`;
+
+/**
+ * Generate the MCP stdio server script as a string.
+ * This script is written to the container and run by claude's --mcp-config.
+ */
+export function generateBridgeScript(): string {
+  return `#!/usr/bin/env node
+// Auto-generated MCP stdio server for custom tool bridge.
+// Reads tool definitions from ${TOOL_BRIDGE_TOOLS_PATH}
+import { readFileSync, writeFileSync, unlinkSync, existsSync, watch, watchFile, unwatchFile } from 'node:fs';
+import { createInterface } from 'node:readline';
+
+const TOOLS_PATH = ${JSON.stringify(TOOL_BRIDGE_TOOLS_PATH)};
+const REQUEST_PATH = ${JSON.stringify(TOOL_BRIDGE_REQUEST_PATH)};
+const RESPONSE_PATH = ${JSON.stringify(TOOL_BRIDGE_RESPONSE_PATH)};
+const PENDING_PATH = ${JSON.stringify(TOOL_BRIDGE_PENDING_PATH)};
+
+let tools = [];
+try { tools = JSON.parse(readFileSync(TOOLS_PATH, 'utf8')); } catch {}
+
+function sendResponse(id, result) {
+  const msg = JSON.stringify({ jsonrpc: '2.0', id, result });
+  const buf = Buffer.from(msg, 'utf8');
+  process.stdout.write('Content-Length: ' + buf.length + '\\r\\n\\r\\n');
+  process.stdout.write(buf);
+}
+
+function sendError(id, code, message) {
+  const msg = JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } });
+  const buf = Buffer.from(msg, 'utf8');
+  process.stdout.write('Content-Length: ' + buf.length + '\\r\\n\\r\\n');
+  process.stdout.write(buf);
+}
+
+function handleRequest(req) {
+  if (req.method === 'initialize') {
+    sendResponse(req.id, {
+      protocolVersion: '2024-11-05',
+      capabilities: { tools: { listChanged: false } },
+      serverInfo: { name: 'tool-bridge', version: '1.0.0' },
+    });
+    return;
+  }
+  if (req.method === 'notifications/initialized') return;
+  if (req.method === 'tools/list') {
+    sendResponse(req.id, {
+      tools: tools.map(t => ({
+        name: t.name,
+        description: t.description || '',
+        inputSchema: t.input_schema || { type: 'object', properties: {} },
+      })),
+    });
+    return;
+  }
+  if (req.method === 'tools/call') {
+    const toolName = req.params?.name;
+    const toolInput = req.params?.arguments || {};
+
+    // Replay case: if response.json already exists (from a --resume re-entry),
+    // return it immediately without creating a pending sentinel.
+    if (existsSync(RESPONSE_PATH)) {
+      try {
+        const resp = JSON.parse(readFileSync(RESPONSE_PATH, 'utf8'));
+        sendResponse(req.id, {
+          content: [{ type: 'text', text: JSON.stringify(resp.content ?? resp) }],
+          isError: false,
+        });
+        try { unlinkSync(RESPONSE_PATH); } catch {}
+        return;
+      } catch (e) {
+        console.error('[tool-bridge] replay failed:', e);
+        process.exit(1);
+      }
+    }
+
+    // Write the request and create pending sentinel
+    writeFileSync(REQUEST_PATH, JSON.stringify({
+      tool_use_id: req.id,
+      name: toolName,
+      input: toolInput,
+    }));
+    writeFileSync(PENDING_PATH, '');
+
+    // Watch for response.json — prefer fs.watch (inotify/kqueue) over
+    // fs.watchFile (stat polling). Fall back to watchFile if watch fails.
+    let resolved = false;
+    const onResponse = () => {
+      if (resolved) return;
+      if (!existsSync(RESPONSE_PATH)) return;
+      resolved = true;
+      // Clean up whichever watcher is active
+      if (watcher) { try { watcher.close(); } catch {} }
+      try { unwatchFile(RESPONSE_PATH, pollFallback); } catch {}
+      try {
+        const resp = JSON.parse(readFileSync(RESPONSE_PATH, 'utf8'));
+        try { unlinkSync(RESPONSE_PATH); } catch {}
+        try { unlinkSync(PENDING_PATH); } catch {}
+        sendResponse(req.id, {
+          content: [{ type: 'text', text: JSON.stringify(resp.content ?? resp) }],
+          isError: false,
+        });
+      } catch (e) {
+        sendError(req.id, -32603, 'Failed to read response: ' + e.message);
+      }
+    };
+    const pollFallback = () => onResponse();
+    let watcher = null;
+    // Check immediately in case it was written between our existsSync check
+    onResponse();
+    if (resolved) return;
+    try {
+      watcher = watch(RESPONSE_PATH, () => onResponse());
+      watcher.on('error', () => {
+        // fs.watch failed mid-watch — fall back to polling
+        try { watcher.close(); } catch {}
+        watcher = null;
+        watchFile(RESPONSE_PATH, { interval: 200 }, pollFallback);
+      });
+    } catch {
+      // fs.watch not available — fall back to stat polling
+      watchFile(RESPONSE_PATH, { interval: 200 }, pollFallback);
+    }
+    return;
+  }
+  // Unknown method
+  if (req.id != null) {
+    sendError(req.id, -32601, 'Method not found: ' + req.method);
+  }
+}
+
+// Read MCP stdio protocol: Content-Length headers + JSON body
+let buffer = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => {
+  buffer += chunk;
+  while (true) {
+    const headerEnd = buffer.indexOf('\\r\\n\\r\\n');
+    if (headerEnd === -1) break;
+    const header = buffer.slice(0, headerEnd);
+    const match = header.match(/Content-Length:\\s*(\\d+)/i);
+    if (!match) { buffer = buffer.slice(headerEnd + 4); continue; }
+    const len = parseInt(match[1], 10);
+    const bodyStart = headerEnd + 4;
+    if (buffer.length < bodyStart + len) break;
+    const body = buffer.slice(bodyStart, bodyStart + len);
+    buffer = buffer.slice(bodyStart + len);
+    try {
+      handleRequest(JSON.parse(body));
+    } catch {}
+  }
+});
+process.stdin.on('end', () => process.exit(0));
+`;
+}
+
+/**
+ * Build the --mcp-config JSON snippet that adds the tool bridge server
+ * alongside any existing MCP servers.
+ */
+export function buildBridgeMcpConfig(
+  existingServers: Record<string, unknown>,
+): Record<string, unknown> {
+  return {
+    ...existingServers,
+    "tool-bridge": {
+      type: "stdio",
+      command: "node",
+      args: [TOOL_BRIDGE_SCRIPT_PATH],
+    },
+  };
+}
+
+/**
+ * Convert CustomTool definitions to the tool bridge's tools.json format.
+ */
+export function toolsToJson(tools: CustomTool[]): string {
+  return JSON.stringify(
+    tools.map((t) => ({
+      name: t.name,
+      description: t.description,
+      input_schema: t.input_schema,
+    })),
+  );
+}

package/src/backends/claude/translator.ts

@@ -0,0 +1,209 @@
+/**
+ * Stateful translator: claude -p stream-json NDJSON → Managed Agents events.
+ *
+ * The translator is the single source of truth for the Managed Agents event
+ * taxonomy. It consumes raw NDJSON objects and returns an array of partially-
+ * shaped Managed Agents event payloads for each line. The driver is
+ * responsible for wrapping them with `{id, seq, session_id, processed_at}`
+ * via `lib/sessions/bus.ts`.
+ *
+ * Tracked state:
+ *   - latest `claude_session_id` (from `system.init`) — re-captured every
+ *     turn, exposed via `getBackendSessionId()`
+ *   - tool_use_id → classification cache (builtin / mcp / custom) so
+ *     matching tool_result events route to the right MA type
+ *   - cumulative usage deltas to apply on `span.model_request_end`
+ *   - whether this turn involved a custom tool so `stop_reason` becomes
+ *     `custom_tool_call`
+ *
+ * Span events are synthesized once per turn by the driver (one start after
+ * `session.status_running`, one end before `session.status_idle`). The
+ * translator supplies the `model_usage` fields to attach to the end event.
+ */
+import { BUILT_IN_TOOL_NAMES } from "../../types";
+import type {
+  ToolClass,
+  TranslatedEvent,
+  Translator,
+  TranslatorOptions,
+  TurnResult,
+  TurnUsage,
+} from "../shared/translator-types";
+
+interface ClaudeContentBlock {
+  type: string;
+  id?: string;
+  text?: string;
+  thinking?: string;
+  name?: string;
+  input?: unknown;
+  tool_use_id?: string;
+  content?: unknown;
+  is_error?: boolean;
+}
+
+interface ClaudeMessage {
+  content?: ClaudeContentBlock[];
+  usage?: Partial<TurnUsage> & {
+    input_tokens?: number;
+    output_tokens?: number;
+    cache_read_input_tokens?: number;
+    cache_creation_input_tokens?: number;
+  };
+}
+
+const BUILT_IN_SET = new Set<string>(BUILT_IN_TOOL_NAMES);
+
+export function createClaudeTranslator(opts: TranslatorOptions): Translator {
+  const toolClass = new Map<string, ToolClass>();
+  let claudeSessionId: string | null = null;
+  let sawInit = false;
+  let sawCustom = false;
+  let turnResult: TurnResult | null = null;
+
+  function classify(name: string): ToolClass {
+    if (BUILT_IN_SET.has(name)) return "builtin";
+    if (name.startsWith("mcp__")) return "mcp";
+    if (opts.customToolNames.has(name)) return "custom";
+    // Unknown — treat as builtin (safer default for forward-compat)
+    return "builtin";
+  }
+
+  function translate(raw: Record<string, unknown>): TranslatedEvent[] {
+    const out: TranslatedEvent[] = [];
+    const type = String(raw.type ?? "");
+
+    if (type === "system") {
+      const subtype = raw.subtype as string | undefined;
+      if (subtype === "init") {
+        if (typeof raw.session_id === "string") {
+          claudeSessionId = raw.session_id;
+        }
+        // Only emit status_running on the first turn of the session — later
+        // turns driven by --resume reuse the existing running status that
+        // the driver already emitted before spawning exec.
+        if (!sawInit && opts.isFirstTurn) {
+          sawInit = true;
+          // status_running is emitted by the driver, not the translator.
+        }
+        sawInit = true;
+      }
+      return out;
+    }
+
+    if (type === "assistant") {
+      const msg = (raw.message as ClaudeMessage | undefined) ?? {};
+      const blocks = msg.content ?? [];
+      for (const block of blocks) {
+        if (block.type === "text" && typeof block.text === "string") {
+          out.push({
+            type: "agent.message",
+            payload: {
+              content: [{ type: "text", text: block.text }],
+            },
+          });
+        } else if (block.type === "thinking" && typeof block.thinking === "string") {
+          out.push({
+            type: "agent.thinking",
+            payload: {
+              content: [{ type: "thinking", thinking: block.thinking }],
+            },
+          });
+        } else if (block.type === "tool_use" && block.id && block.name) {
+          const cls = classify(block.name);
+          toolClass.set(block.id, cls);
+          if (cls === "custom") {
+            sawCustom = true;
+            out.push({
+              type: "agent.custom_tool_use",
+              payload: {
+                tool_use_id: block.id,
+                name: block.name,
+                input: block.input ?? {},
+              },
+            });
+          } else if (cls === "mcp") {
+            // name format: mcp__server__tool
+            const parts = block.name.split("__");
+            const serverName = parts[1] ?? "unknown";
+            const toolName = parts.slice(2).join("__") || block.name;
+            out.push({
+              type: "agent.mcp_tool_use",
+              payload: {
+                tool_use_id: block.id,
+                server_name: serverName,
+                tool_name: toolName,
+                input: block.input ?? {},
+              },
+            });
+          } else {
+            out.push({
+              type: "agent.tool_use",
+              payload: {
+                tool_use_id: block.id,
+                name: block.name,
+                input: block.input ?? {},
+              },
+            });
+          }
+        }
+      }
+      return out;
+    }
+
+    if (type === "user") {
+      const msg = (raw.message as ClaudeMessage | undefined) ?? {};
+      const blocks = msg.content ?? [];
+      for (const block of blocks) {
+        if (block.type === "tool_result" && block.tool_use_id) {
+          const cls = toolClass.get(block.tool_use_id);
+          if (cls === "custom") continue; // custom tool results come from the client
+          const eventType = cls === "mcp" ? "agent.mcp_tool_result" : "agent.tool_result";
+          out.push({
+            type: eventType,
+            payload: {
+              tool_use_id: block.tool_use_id,
+              content: block.content ?? null,
+              is_error: block.is_error ?? false,
+            },
+          });
+        }
+      }
+      return out;
+    }
+
+    if (type === "result") {
+      const subtype = String(raw.subtype ?? "success");
+      const usageRaw = (raw.usage as ClaudeMessage["usage"] | undefined) ?? {};
+      const usage: TurnUsage = {
+        input_tokens: usageRaw.input_tokens ?? 0,
+        output_tokens: usageRaw.output_tokens ?? 0,
+        cache_read_input_tokens: usageRaw.cache_read_input_tokens ?? 0,
+        cache_creation_input_tokens: usageRaw.cache_creation_input_tokens ?? 0,
+        cost_usd: (raw.total_cost_usd as number | undefined) ?? 0,
+      };
+      let stopReason: TurnResult["stopReason"];
+      if (sawCustom) stopReason = "custom_tool_call";
+      else if (subtype === "error_max_turns") stopReason = "max_turns";
+      else if (subtype === "error_during_execution") stopReason = "error";
+      else stopReason = "end_turn";
+
+      turnResult = {
+        stopReason,
+        usage,
+        num_turns: (raw.num_turns as number | undefined) ?? 1,
+      };
+      return out;
+    }
+
+    // Unrecognized — drop silently, translator is forward-compatible.
+    return out;
+  }
+
+  return {
+    translate,
+    getBackendSessionId: () => claudeSessionId,
+    getTurnResult: () => turnResult,
+    sawCustomToolUse: () => sawCustom,
+  };
+}

package/src/backends/claude/wrapper-script.ts

@@ -0,0 +1,45 @@
+/**
+ * Sprite wrapper script for claude.
+ *
+ * Reads env vars from stdin (one per line) until a blank line, then execs
+ * the real `claude` binary with the remaining stdin piped into claude as
+ * the prompt. Credentials never hit URLs or disk.
+ *
+ * Lifted verbatim from
+ * 
+ */
+import type { ContainerProvider } from "../../providers/types";
+
+// Use /tmp/ for wrapper scripts — it exists on all container runtimes
+// (sprites.dev, Docker, Apple Containers). /home/sprite/ is sprites-specific.
+export const CLAUDE_WRAPPER_PATH = "/tmp/.claude-wrapper";
+
+const SPRITE_WRAPPER_SCRIPT = [
+  "#!/bin/bash",
+  '# Install claude CLI if not present',
+  'if ! command -v claude &>/dev/null; then npm install -g @anthropic-ai/claude-code 2>/dev/null; fi',
+  '# Read env vars from stdin until blank line',
+  'while IFS= read -r line; do [ -z "$line" ] && break; export "$line"; done',
+  '# If root, drop to non-root user (bypassPermissions requires non-root)',
+  'if [ "$(id -u)" = "0" ]; then',
+  '  id agent &>/dev/null || useradd -m -s /bin/bash agent 2>/dev/null',
+  '  chown -R agent /tmp/ 2>/dev/null',
+  '  exec runuser -u agent -- env PATH="$PATH" HOME="/home/agent" \\',
+  '    ${ANTHROPIC_API_KEY:+ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY"} \\',
+  '    ${CLAUDE_CODE_OAUTH_TOKEN:+CLAUDE_CODE_OAUTH_TOKEN="$CLAUDE_CODE_OAUTH_TOKEN"} \\',
+  '    ${OPENAI_API_KEY:+OPENAI_API_KEY="$OPENAI_API_KEY"} \\',
+  '    ${VAULT_DIR:+VAULT_DIR="$VAULT_DIR"} \\',
+  '    claude "$@"',
+  'fi',
+  'exec claude "$@"',
+].join("\n");
+
+export async function installClaudeWrapper(spriteName: string, provider: ContainerProvider): Promise<void> {
+  // Quote-escape for embedding inside a single-quoted shell string.
+  const escaped = SPRITE_WRAPPER_SCRIPT.replace(/'/g, "'\\''");
+  await provider.exec(spriteName, [
+    "bash",
+    "-c",
+    `printf '%s' '${escaped}' > ${CLAUDE_WRAPPER_PATH} && chmod +x ${CLAUDE_WRAPPER_PATH}`,
+  ]);
+}

package/src/backends/codex/args.ts

@@ -0,0 +1,69 @@
+/**
+ * Build the `codex exec` argv for one turn.
+ *
+ * Ported from
+ * 
+ *
+ * Codex-specific constraints:
+ * - No --max-turns (codex has no equivalent; silently ignored like opencode)
+ * - No --system-prompt flag — system prompt is wrapped into the user prompt
+ *   text via the shared wrapPromptWithSystem utility
+ * - MCP is passed via -c config flags (not env var like opencode)
+ * - Trailing `-` reads prompt from stdin (promptViaStdin: true — like claude)
+ * - --full-auto + --ask-for-approval never + --dangerously-bypass-approvals-
+ *   and-sandbox to prevent headless hangs
+ */
+import type { Agent } from "../../types";
+
+export interface BuildCodexArgsInput {
+  agent: Agent;
+}
+
+export function buildCodexArgs(input: BuildCodexArgsInput): string[] {
+  // --full-auto alone is sufficient for
+  // non-interactive headless execution on v0.118.0. Flags like
+  // --ask-for-approval and --dangerously-bypass-approvals-and-sandbox
+  // do NOT exist in the current codex Rust CLI.
+  const args = [
+    "exec",
+    "--json",
+    "--full-auto",
+    "--skip-git-repo-check",
+  ];
+
+  if (input.agent.model) {
+    // Codex expects bare model names (gpt-5.4, gpt-5.4-mini) — NOT the
+    // openai/gpt-5.4 format opencode uses.
+    args.push("--model", input.agent.model);
+  }
+
+  // MCP config via -c flags (/lib/oc/cli-providers.ts:219-235)
+  if (input.agent.mcp_servers) {
+    for (const [name, server] of Object.entries(input.agent.mcp_servers)) {
+      if (server.type) {
+        args.push("-c", `mcp_servers.${name}.type="${server.type}"`);
+      }
+      if (server.url) {
+        args.push("-c", `mcp_servers.${name}.url="${server.url}"`);
+      }
+      if (typeof server.command === "string") {
+        args.push("-c", `mcp_servers.${name}.command="${server.command}"`);
+      }
+      if (server.args && server.args.length > 0) {
+        args.push(
+          "-c",
+          `mcp_servers.${name}.args=${JSON.stringify(server.args)}`,
+        );
+      }
+      if (server.headers) {
+        for (const [hk, hv] of Object.entries(server.headers)) {
+          args.push("-c", `mcp_servers.${name}.http_headers.${hk}="${hv}"`);
+        }
+      }
+    }
+  }
+
+  // Trailing `-` signals stdin prompt
+  args.push("-");
+  return args;
+}

package/src/backends/codex/auth.ts

@@ -0,0 +1,35 @@
+/**
+ * Auth env + create-time validation for the codex backend.
+ *
+ * Codex accepts both CODEX_API_KEY and OPENAI_API_KEY. We forward both,
+ * setting them to the same value (our config.openAiApiKey) for belt-and-
+ * braces. Rejects sk-ant-* tokens explicitly
+ * (cli-providers.ts:242-244).
+ *
+ * will verify which env var codex actually prefers on the current
+ * v0.118.0 release.
+ */
+import { getConfig } from "../../config";
+
+export function buildCodexAuthEnv(): Record<string, string> {
+  const cfg = getConfig();
+  const env: Record<string, string> = {};
+  if (cfg.openAiApiKey) {
+    env.OPENAI_API_KEY = cfg.openAiApiKey;
+    env.CODEX_API_KEY = cfg.openAiApiKey;
+  }
+  return env;
+}
+
+/**
+ * Returns null if codex can run, or an error message if it can't. Used at
+ * agent create time (validateAgentCreation) and first-turn time
+ * (validateRuntime).
+ */
+export function validateCodexRuntime(): string | null {
+  const cfg = getConfig();
+  if (!cfg.openAiApiKey) {
+    return "codex backend requires OPENAI_API_KEY to be set";
+  }
+  return null;
+}

package/src/backends/codex/index.ts

@@ -0,0 +1,57 @@
+/**
+ * Codex backend: drives OpenAI's `codex exec` on sprites.dev containers.
+ *
+ * Ported from
+ * 
+ * (the  codex provider), adapted for our sprite-only
+ * execution model. Opencompletions only ran codex in its local backend;
+ * this adapter is the first time codex runs inside a sprites.dev sprite,
+ * so the wrapper script + install flow mirror the opencode adapter's
+ * sprite-side patterns.
+ *
+ * Custom tool re-entry is NOT supported by codex — codex exec has no
+ * equivalent of claude's --input-format stream-json. buildTurn rejects
+ * toolResults.length > 0 with an invalid_request_error.
+ */
+import { ApiError } from "../../errors";
+import type { Backend, BuildTurnInput, BuildTurnResult } from "../types";
+import type { TranslatorOptions } from "../shared/translator-types";
+import { wrapPromptWithSystem } from "../shared/wrap-prompt";
+import { buildCodexArgs } from "./args";
+import { buildCodexAuthEnv, validateCodexRuntime } from "./auth";
+import { createCodexTranslator } from "./translator";
+import { CODEX_WRAPPER_PATH } from "./wrapper-script";
+import { prepareCodexOnSprite } from "./setup";
+
+function buildTurn(input: BuildTurnInput): BuildTurnResult {
+  const { agent, promptText, toolResults } = input;
+  if (toolResults.length > 0) {
+    throw new ApiError(
+      400,
+      "invalid_request_error",
+      "codex backend does not support user.custom_tool_result re-entry in v1",
+    );
+  }
+  const argv = buildCodexArgs({ agent });
+  const env = buildCodexAuthEnv();
+  const wrappedPrompt = wrapPromptWithSystem(promptText, agent.system);
+  return { argv, env, stdin: wrappedPrompt };
+}
+
+export const codexBackend: Backend = {
+  name: "codex",
+  wrapperPath: CODEX_WRAPPER_PATH,
+  buildTurn,
+  createTranslator: (opts: TranslatorOptions) => createCodexTranslator(opts),
+  prepareOnSprite: (name, provider) => prepareCodexOnSprite(name, provider),
+
+  validateRuntime: validateCodexRuntime,
+};
+
+export {
+  buildCodexArgs,
+  buildCodexAuthEnv,
+  createCodexTranslator,
+  prepareCodexOnSprite,
+  CODEX_WRAPPER_PATH,
+};

package/src/backends/codex/setup.ts

@@ -0,0 +1,37 @@
+/**
+ * Install codex on a freshly-created sprite.
+ *
+ * Mirrors lib/backends/opencode/setup.ts with the same sentinel + symlink
+ * fix pattern Codex is installed via npm from the
+ * @openai/codex package.
+ *
+ * 
+ */
+import type { ContainerProvider } from "../../providers/types";
+import { installCodexWrapper } from "./wrapper-script";
+
+const SENTINEL_NAME = ".claude-agents-codex-installed";
+
+export async function prepareCodexOnSprite(spriteName: string, provider: ContainerProvider): Promise<void> {
+  await installCodexWrapper(spriteName, provider);
+
+  const script = [
+    "set -euo pipefail",
+    `SENTINEL="$HOME/${SENTINEL_NAME}"`,
+    'if [ -f "$SENTINEL" ]; then exit 0; fi',
+    "npm install -g @openai/codex",
+    "PREFIX=$(npm config get prefix)",
+    'if [ "$PREFIX" != "/usr/local" ]; then ln -sf "$PREFIX/bin/codex" /usr/local/bin/codex; fi',
+    '/usr/local/bin/codex --version || $PREFIX/bin/codex --version',
+    'touch "$SENTINEL"',
+  ].join(" && ");
+
+  const result = await provider.exec(spriteName, ["bash", "-c", script], {
+    timeoutMs: 5 * 60_000,
+  });
+  if (result.exit_code !== 0) {
+    throw new Error(
+      `codex install failed (${result.exit_code}): ${result.stderr.slice(0, 500)}`,
+    );
+  }
+}