@agent-compose/sdk 0.2.1 → 0.2.2

package/src/runtimes/claude.ts

@@ -0,0 +1,305 @@
+/**
+ * Claude CLI runtime — drives agents via the Claude CLI inside a sandbox.
+ *
+ * Works with any SandboxProvider (E2B, Vercel, etc.) — the provider is
+ * selected via SANDBOX_PROVIDER env var, not the runtime definition.
+ *
+ * Usage:
+ *   import { createClaudeRuntime } from "@agent-compose/sdk";
+ *   export default createClaudeRuntime({ claudeMdContent: "..." }); // optional global instructions
+ */
+
+import type { SandboxProvider, AgentMessage, ModelExecutionContract, RuntimeOptions } from "../index.js";
+import { defineRuntime } from "../types/runtime.js";
+import { DEFAULT_CLAUDE_MODEL } from "../agent/agent-loop.js";
+import { formatError } from "../utils/errors.js";
+
+const NO_TIMEOUT = 0; // claude exits on its own via --max-turns
+
+
+function translateEvent(event: Record<string, unknown>): AgentMessage[] {
+  const msgs: AgentMessage[] = [];
+  const ts = new Date().toISOString();
+
+  if (event.type === "system" && event.subtype === "init") {
+    msgs.push({ type: "init", sessionId: String(event.session_id ?? ""), timestamp: ts });
+    return msgs;
+  }
+
+  if (event.type === "assistant") {
+    const message = event.message as { content?: unknown[] } | undefined;
+    for (const block of message?.content ?? []) {
+      const b = block as Record<string, unknown>;
+      if (b.type === "text")     msgs.push({ type: "text", text: String(b.text ?? ""), timestamp: ts });
+      if (b.type === "thinking") msgs.push({ type: "thinking", text: String(b.thinking ?? ""), timestamp: ts });
+      if (b.type === "tool_use") msgs.push({ type: "tool_use", toolName: String(b.name ?? ""), toolInput: (b.input ?? {}) as Record<string, unknown>, toolUseId: String(b.id ?? ""), timestamp: ts });
+    }
+    return msgs;
+  }
+
+  if (event.type === "user") {
+    const message = event.message as { content?: unknown[] } | undefined;
+    for (const block of message?.content ?? []) {
+      const b = block as Record<string, unknown>;
+      if (b.type === "tool_result") {
+        const raw = b.content;
+        msgs.push({ type: "tool_result", toolUseId: String(b.tool_use_id ?? ""), output: typeof raw === "string" ? raw : JSON.stringify(raw ?? ""), isError: Boolean(b.is_error), timestamp: ts });
+      }
+    }
+    return msgs;
+  }
+
+  if (event.type === "result") {
+    const usage = event.usage as Record<string, number> | undefined;
+    if (usage) {
+      msgs.push({ type: "usage", inputTokens: usage.input_tokens ?? 0, outputTokens: usage.output_tokens ?? 0, cacheReadTokens: usage.cache_read_input_tokens ?? 0, cacheCreationTokens: usage.cache_creation_input_tokens ?? 0, durationMs: Number(event.duration_ms ?? 0), numTurns: Number(event.num_turns ?? 0), timestamp: ts });
+    }
+    if (event.is_error || event.subtype === "error_during_execution") {
+      const raw = event.error ?? event.result ?? event.message;
+      msgs.push({ type: "error", text: raw == null ? "Unknown error" : typeof raw === "object" ? JSON.stringify(raw) : String(raw), timestamp: ts });
+    } else {
+      msgs.push({ type: "done", sessionId: String(event.session_id ?? ""), timestamp: ts });
+    }
+    return msgs;
+  }
+
+  return msgs;
+}
+
+export class ClaudeRunner implements ModelExecutionContract {
+  private claudeMdWritten = false;
+  private homeDir: string | null = null;
+  private label: string;
+
+  constructor(
+    private sandbox: SandboxProvider,
+    private options: RuntimeOptions = {},
+    private claudeMdContent: string = "",
+    private configEnv: Record<string, string> = {},
+    private configModel?: string,
+    private configMcpServers?: Record<string, { command: string; args?: string[]; env?: Record<string, string> }>,
+  ) {
+    this.label = options.label ?? "[Agent]";
+  }
+
+  private async getHomeDir(): Promise<string> {
+    if (!this.homeDir) {
+      const { stdout } = await this.sandbox.commands.run("echo $HOME", { timeoutMs: 30_000 });
+      this.homeDir = stdout.trim() || "/home/user";
+    }
+    return this.homeDir;
+  }
+
+  private async deployGlobalConfig(): Promise<void> {
+    if (this.claudeMdWritten) return;
+    const home = await this.getHomeDir();
+
+    await this.sandbox.commands.run(`mkdir -p "${home}/.claude" && find "${home}/.claude" -name "*.json" -not -name "CLAUDE.md" -delete 2>/dev/null || true`, { timeoutMs: 5000 });
+    await this.sandbox.files.write(`${home}/.claude/CLAUDE.md`, this.claudeMdContent);
+    // Write env overrides to settings.json so the CLI picks them up at startup.
+    // This is how the CLI reads ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, etc.
+    if (Object.keys(this.configEnv).length) {
+      const settings = JSON.stringify({ env: this.configEnv });
+      const b64 = Buffer.from(settings).toString("base64");
+      await this.sandbox.commands.run(`echo "${b64}" | base64 -d > "${home}/.claude/settings.json"`, { timeoutMs: 5_000 });
+    }
+    // MCP servers: config-level (from createClaudeRuntime) as base, opts-level (from agent definition) overrides.
+    const mcpServers = this.configMcpServers;
+    if (mcpServers && Object.keys(mcpServers).length) {
+      // MCP servers live in ~/.claude.json per Claude Code docs (not ~/.claude/settings.json).
+      // Use a shell command rather than files.write — Vercel's writeFiles API defaults paths to
+      // /vercel/sandbox, so absolute paths in the home directory may not resolve correctly.
+      const b64 = Buffer.from(JSON.stringify({ mcpServers })).toString("base64");
+      await this.sandbox.commands.run(`echo "${b64}" | base64 -d > "${home}/.claude.json"`, { timeoutMs: 5_000 });
+      process.stderr.write(`${this.label}[mcp] wrote ${Object.keys(mcpServers).join(",")} to ~/.claude.json\n`);
+    }
+    // Configure git in one shot: disable credential prompts, clear credential helper,
+    // and set a placeholder Authorization header for github.com HTTPS requests.
+    // The sandbox provider's network policy firewall replaces this header with the
+    // real token before forwarding — the token is never readable inside the VM.
+    // (api.github.com is the REST API, not git; git only uses github.com URLs.)
+    const placeholderB64 = Buffer.from("x-access-token:placeholder").toString("base64");
+    await this.sandbox.commands.run(
+      [
+        `git config --global core.askPass ""`,
+        `git config --global credential.interactive false`,
+        `git config --global credential.helper ""`,
+        `git config --global "http.https://github.com/.extraHeader" "Authorization: Basic ${placeholderB64}"`,
+      ].join(" && "),
+      { timeoutMs: 5_000 },
+    ).catch((e: unknown) => console.warn(`${this.label}[init] git config failed (non-fatal): ${formatError(e)}`));
+
+    try {
+      await this.sandbox.commands.run("rtk init --global --hook-only --auto-patch", { timeoutMs: 10_000 });
+    } catch {
+      console.warn("[Transport] rtk init failed (non-fatal) — token compression disabled");
+    }
+    this.claudeMdWritten = true;
+  }
+
+  /** Stream one CLI invocation, yielding AgentMessages. Resolves when the process exits. */
+  private async *_runCli(cmd: string, label: string, signal?: AbortSignal): AsyncGenerator<AgentMessage> {
+    type QueueItem = AgentMessage | { sentinel: "error"; text: string } | null;
+    const queue: QueueItem[] = [];
+    let notify: (() => void) | null = null;
+
+    function enqueue(items: AgentMessage[]): void { queue.push(...items); notify?.(); notify = null; }
+
+    let lineBuffer = "";
+    let stderrBuffer = "";
+
+    const maxTurns = this.options.maxTurns ?? 40;
+
+    function handleStdout(data: string): void {
+      lineBuffer += data;
+      const lines = lineBuffer.split("\n");
+      lineBuffer = lines.pop() ?? "";
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        try {
+          const event = JSON.parse(trimmed) as Record<string, unknown>;
+          if (event.type === "assistant") {
+            const content = (event.message as { content?: unknown[] })?.content ?? [];
+            for (const block of content) {
+              const b = block as Record<string, unknown>;
+              if (b.type === "text")     process.stdout.write(".");
+              if (b.type === "tool_use") process.stderr.write(`\n${label} ${b.name}(${JSON.stringify(b.input).slice(0, 80)})`);
+            }
+          } else if (event.type === "result") {
+            process.stderr.write(`\n${label}[result:${event.num_turns}/${maxTurns}/${event.subtype}]\n`);
+          } else if (event.type === "system") {
+            const ev = event as Record<string,unknown>;
+            const mcpSrvs = (ev.mcp_servers as {name:string;status:string}[] | undefined) ?? [];
+            const mcpStr = mcpSrvs.length ? ` mcp=[${mcpSrvs.map(s=>`${s.name}:${s.status}`).join(",")}]` : " mcp=[]";
+            process.stderr.write(`\n${label}[init:${ev.session_id}]${mcpStr}\n`);
+          }
+          enqueue(translateEvent(event));
+        } catch { /* non-JSON line */ }
+      }
+    }
+
+    process.stderr.write(`${label}[cwd:${this.options.cwd ?? "(none)"}]\n`);
+    const runPromise = this.sandbox.commands.run(cmd, {
+      cwd: this.options.cwd,
+      timeoutMs: NO_TIMEOUT,
+      onStdout: handleStdout,
+      onStderr: (data: string) => { stderrBuffer += data; process.stderr.write(`${label}[stderr] ${data.trimEnd()}\n`); },
+    });
+
+    runPromise
+      .catch((err: unknown) => {
+        const e = err as Record<string, unknown>;
+        if (e && typeof e === "object" && "exitCode" in e) process.stderr.write(`${label}[transport] command failed — exitCode=${e.exitCode} error=${JSON.stringify(e.error)} stdout_tail=${String(e.stdout ?? "").slice(-200)} stderr_tail=${String(e.stderr ?? "").slice(-200)}\n`);
+        queue.push({ sentinel: "error", text: stderrBuffer.trim() ? `Agent process failed: ${formatError(err)}\n\n${stderrBuffer.trim()}` : `Agent process failed: ${formatError(err)}` });
+      })
+      .finally(() => {
+        if (lineBuffer.trim()) { try { enqueue(translateEvent(JSON.parse(lineBuffer.trim()) as Record<string, unknown>)); } catch { /* ignore */ } }
+        queue.push(null);
+        notify?.(); notify = null;
+      });
+
+    while (true) {
+      while (queue.length > 0) {
+        const item = queue.shift()!;
+        if (item === null) return;
+        if ("sentinel" in item) { yield { type: "error", text: item.text, timestamp: new Date().toISOString() }; return; }
+        if (signal?.aborted) return;
+        const msg = item as AgentMessage;
+        yield (msg.type === "error" && stderrBuffer.trim() && !msg.text.includes(stderrBuffer.trim()))
+          ? { ...msg, text: `${msg.text}\n\n${stderrBuffer.trim()}` }
+          : msg;
+      }
+      await new Promise<void>(r => { notify = r; });
+    }
+  }
+
+  async *sendMessage(opts: { prompt: string; sessionId?: string; signal?: AbortSignal }): AsyncGenerator<AgentMessage> {
+    await this.deployGlobalConfig();
+
+    if (opts.sessionId) {
+      await this.sandbox.commands.run(`pkill -x claude 2>/dev/null || true`, { timeoutMs: 10_000 });
+    }
+
+    const maxTurns = this.options.maxTurns ?? 40;
+    const model    = this.configModel ?? this.options.model ?? DEFAULT_CLAUDE_MODEL;
+    const label    = this.label;
+
+    const promptFile = `/tmp/agent-prompt-${Date.now()}.txt`;
+    await this.sandbox.files.write(promptFile, opts.prompt);
+
+    // Don't restrict tools when MCP servers are configured — --allowedTools also
+    // blocks MCP tools, which would prevent the agent from using them.
+    const hasMcp = this.configMcpServers && Object.keys(this.configMcpServers).length > 0;
+    const allowedToolsFlag = (!hasMcp && this.options.allowedTools?.length)
+      ? ["--allowedTools", this.options.allowedTools.join(",")]
+      : [];
+
+    const buildCmd = (sessionId?: string) => [
+      "claude", "--dangerously-skip-permissions", "--verbose",
+      "--output-format", "stream-json",
+      "--max-turns", String(maxTurns),
+      "--model", model,
+      ...allowedToolsFlag,
+      ...(sessionId ? ["--resume", sessionId] : []),
+      "-p", `"$(cat ${promptFile})"`,
+    ].join(" ");
+
+    const MAX_529_RETRIES  = 5;
+    const BACKOFF_MS       = [60_000, 120_000, 240_000, 480_000, 600_000];
+    let   resumeSessionId  = opts.sessionId;
+
+    for (let attempt = 0; attempt <= MAX_529_RETRIES; attempt++) {
+      let got529      = false;
+      let newSession  = "";
+
+      for await (const msg of this._runCli(buildCmd(resumeSessionId), label, opts.signal)) {
+        if (msg.type === "init") newSession = msg.sessionId;
+        // Intercept 529 — retry instead of propagating
+        if (msg.type === "error" && msg.text.includes("529")) { got529 = true; break; }
+        yield msg;
+        if (msg.type === "done" || msg.type === "error") return;
+      }
+
+      if (!got529) return;
+      if (attempt === MAX_529_RETRIES) {
+        yield { type: "error", text: "Agent process failed: Repeated 529 Overloaded errors — all retries exhausted", timestamp: new Date().toISOString() };
+        return;
+      }
+
+      if (newSession) resumeSessionId = newSession;
+      const wait = BACKOFF_MS[attempt];
+      process.stderr.write(`\n${label}[529] Overloaded — resuming in ${wait / 1000}s (attempt ${attempt + 1}/${MAX_529_RETRIES})${resumeSessionId ? " with session resume" : ""}\n`);
+      await new Promise(r => setTimeout(r, wait));
+    }
+  }
+}
+
+export interface ClaudeRuntimeConfig {
+  /** Global instructions written to ~/.claude/CLAUDE.md in every sandbox. */
+  claudeMdContent?: string;
+  /**
+   * Environment variables set before each CLI invocation.
+   * Use to configure API provider routing (e.g. OpenRouter):
+   *   env: { ANTHROPIC_BASE_URL: "https://openrouter.ai/api", ANTHROPIC_AUTH_TOKEN: "$OPENROUTER_API_KEY", ANTHROPIC_API_KEY: "" }
+   */
+  env?: Record<string, string>;
+  /** Model to use (e.g. "claude-opus-4-6", "anthropic/claude-sonnet-4-6"). */
+  model?: string;
+  /** MCP servers to configure in the sandbox. Written to ~/.claude.json before the first iteration. */
+  mcpServers?: Record<string, { command: string; args?: string[]; env?: Record<string, string> }>;
+}
+
+/**
+ * Create a Claude CLI runtime.
+ *
+ * Encapsulates everything about how the Claude CLI runs in a sandbox:
+ * API provider routing, MCP server configuration, and global instructions.
+ */
+export function createClaudeRuntime(config: ClaudeRuntimeConfig = {}) {
+  return defineRuntime({
+    create: (sandbox, opts) => new ClaudeRunner(sandbox, opts, config.claudeMdContent ?? "", config.env ?? {}, config.model, config.mcpServers),
+  });
+}
+
+export default createClaudeRuntime();

package/src/runtimes/openai-desktop.ts

@@ -0,0 +1,151 @@
+/**
+ * OpenAI Desktop Runner — ModelExecutionContract implementation using computer-use-preview.
+ *
+ * Works against DesktopSandboxProvider — no E2B SDK dependency here.
+ * The action→screenshot loop runs until the model emits text, then yields it.
+ */
+
+import OpenAI from "openai";
+import sharp from "sharp";
+import type { DesktopSandboxProvider, AgentMessage, ModelExecutionContract, RuntimeOptions } from "../index.js";
+import { defineRuntime, formatError } from "../index.js";
+
+const DISPLAY_WIDTH  = 1024;
+const DISPLAY_HEIGHT = 720;
+const DESKTOP_WIDTH  = 1280;
+const DESKTOP_HEIGHT = 800;
+const MAX_TURNS = 40;
+
+export interface OpenAIDesktopRunnerOptions extends RuntimeOptions {
+  openaiKey: string;
+}
+
+export class OpenAIDesktopRunner implements ModelExecutionContract {
+  private openai: OpenAI;
+  private label: string;
+
+  constructor(
+    private sandbox: DesktopSandboxProvider,
+    opts: OpenAIDesktopRunnerOptions,
+  ) {
+    this.openai = new OpenAI({ apiKey: opts.openaiKey });
+    this.label = opts.label ?? `[${sandbox.sandboxId.slice(-8)}]`;
+  }
+
+  async *sendMessage(opts: {
+    prompt: string;
+    sessionId?: string;
+  }): AsyncGenerator<AgentMessage> {
+    const { sandbox } = this;
+    const ts = () => new Date().toISOString();
+    const label = this.label;
+
+    yield { type: "init", sessionId: "e2b-desktop", timestamp: ts() };
+
+    const screenshot = await captureScaledScreenshot(sandbox);
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const messages: any[] = [{
+      role: "user",
+      content: [
+        { type: "input_image", image_url: `data:image/png;base64,${screenshot}` },
+        { type: "input_text", text: opts.prompt },
+      ],
+    }];
+
+    let previousResponseId: string | undefined;
+
+    for (let turn = 0; turn < MAX_TURNS; turn++) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const response = await (this.openai as any).responses.create({
+        model: "computer-use-preview",
+        tools: [{ type: "computer_use_preview", name: "computer", display_width: DISPLAY_WIDTH, display_height: DISPLAY_HEIGHT, environment: "linux" }],
+        input: messages,
+        truncation: "auto",
+        ...(previousResponseId ? { previous_response_id: previousResponseId } : {}),
+      });
+      previousResponseId = response.id;
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const computerCalls: any[] = response.output?.filter((b: any) => b.type === "computer_call") ?? [];
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const textBlocks: any[] = response.output?.filter((b: any) => b.type === "text") ?? [];
+
+      if (textBlocks.length > 0) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        yield { type: "text", text: textBlocks.map((b: any) => b.text).join("\n"), timestamp: ts() };
+        break;
+      }
+
+      for (const call of computerCalls) {
+        console.log(`${label}   → ${call.action.type}`);
+        await executeAction(sandbox, call.action).catch(
+          (err: unknown) => console.warn(`${label}   Action failed (non-fatal): ${formatError(err)}`),
+        );
+      }
+
+      if (computerCalls.length === 0) break;
+
+      const next = await captureScaledScreenshot(sandbox);
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      messages.push({ role: "user", content: computerCalls.map((call: any) => ({
+        type: "computer_call_output",
+        call_id: call.call_id,
+        output: { type: "input_image", image_url: `data:image/png;base64,${next}` },
+      })) });
+    }
+
+    yield { type: "done", sessionId: "e2b-desktop", timestamp: ts() };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers — work against DesktopSandboxProvider interface
+// ---------------------------------------------------------------------------
+
+async function captureScaledScreenshot(sandbox: DesktopSandboxProvider): Promise<string> {
+  const raw = await sandbox.screenshot();
+  const scaled = await sharp(raw)
+    .resize(DISPLAY_WIDTH, DISPLAY_HEIGHT, { kernel: "lanczos3", fit: "fill" })
+    .png()
+    .toBuffer();
+  return scaled.toString("base64");
+}
+
+function scaleX(x: number): number { return Math.round(x * DESKTOP_WIDTH / DISPLAY_WIDTH); }
+function scaleY(y: number): number { return Math.round(y * DESKTOP_HEIGHT / DISPLAY_HEIGHT); }
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function executeAction(sandbox: DesktopSandboxProvider, action: Record<string, any>): Promise<void> {
+  const [x, y] = action.coordinate
+    ? [scaleX(action.coordinate[0]), scaleY(action.coordinate[1])]
+    : [0, 0];
+
+  switch (action.type) {
+    case "click":        await sandbox.leftClick(x, y); break;
+    case "double_click": await sandbox.doubleClick(x, y); break;
+    case "right_click":  await sandbox.rightClick(x, y); break;
+    case "middle_click": await sandbox.middleClick(x, y); break;
+    case "move":         await sandbox.moveMouse(x, y); break;
+    case "type":         await sandbox.write(action.text ?? ""); break;
+    case "key":          await sandbox.press(action.key ?? ""); break;
+    case "scroll":       await sandbox.scroll(action.direction === "up" ? "up" : "down", action.ticks ?? 3); break;
+    case "drag":
+      if (action.startCoordinate && action.endCoordinate) {
+        await sandbox.drag(
+          [scaleX(action.startCoordinate[0]), scaleY(action.startCoordinate[1])],
+          [scaleX(action.endCoordinate[0]), scaleY(action.endCoordinate[1])],
+        );
+      }
+      break;
+  }
+  await new Promise(r => setTimeout(r, 200));
+}
+
+export default defineRuntime<DesktopSandboxProvider>({
+  create: (sandbox, opts) => {
+    const openaiKey = process.env.OPENAI_API_KEY;
+    if (!openaiKey) throw new Error("OPENAI_API_KEY environment variable is required for the openai-desktop runtime");
+    return new OpenAIDesktopRunner(sandbox, { ...opts, openaiKey });
+  },
+});