@agentstep/agent-sdk 0.1.0

package/src/backends/codex/translator.ts

@@ -0,0 +1,223 @@
+/**
+ * Stateful translator: codex NDJSON → Managed Agents events.
+ *
+ * Ported from
+ * 
+ *
+ * Codex's event model (emitted by `codex exec --json`):
+ *   - `thread.started` — session init with `thread_id`
+ *   - `item.completed` — work item finished; `item.type` determines the shape:
+ *     - `agent_message` → text response → `agent.message`
+ *     - `command_execution` → shell command + output → [tool_use, tool_result]
+ *     - `mcp_tool_call` → MCP tool call + result → [tool_use, tool_result]
+ *     - `file_change` → file edit/add/delete → tool_use
+ *   - `turn.completed` — end of an internal reasoning turn; accumulates usage
+ *   - `error` — stream-level error
+ *
+ * Key differences from opencode:
+ *   - translate() can return ARRAYS of events (for command_execution and
+ *     mcp_tool_call where we split the codex "completed item" into both a
+ *     tool_use and a tool_result in our Managed Agents timeline)
+ *   - No inline "result" event from codex — usage is accumulated across
+ *     turn.completed events and the final TurnResult is synthesized by
+ *     getTurnResult() when the stream ends. The driver calls this after the
+ *     stream loop exits, which is equivalent to finalize()
+ *     hook without requiring a new interface method.
+ */
+import type {
+  ToolClass,
+  TranslatedEvent,
+  Translator,
+  TranslatorOptions,
+  TurnResult,
+  TurnUsage,
+} from "../shared/translator-types";
+
+interface CodexItem {
+  type?: string;
+  id?: string;
+  text?: string;
+  command?: string;
+  output?: string;
+  result?: string;
+  name?: string;
+  input?: unknown;
+  path?: string;
+  action?: string;
+}
+
+export function createCodexTranslator(opts: TranslatorOptions): Translator {
+  const toolClass = new Map<string, ToolClass>();
+  let sessionId: string | null = null;
+  let turnCount = 0;
+  let lastText = "";
+  let totalInputTokens = 0;
+  let totalOutputTokens = 0;
+  let totalCostUsd = 0;
+  let sawCustom = false;
+
+  function classify(name: string): ToolClass {
+    if (opts.customToolNames.has(name)) return "custom";
+    return "builtin";
+  }
+
+  function translate(raw: Record<string, unknown>): TranslatedEvent[] {
+    const out: TranslatedEvent[] = [];
+    if (!raw || typeof raw !== "object") return out;
+    const type = String(raw.type ?? "");
+
+    if (type === "thread.started") {
+      if (typeof raw.thread_id === "string") sessionId = raw.thread_id;
+      // Driver emits session.status_running; translator just tracks state.
+      return out;
+    }
+
+    if (type === "item.completed" && raw.item && typeof raw.item === "object") {
+      const item = raw.item as CodexItem;
+
+      if (item.type === "reasoning" && typeof item.text === "string") {
+        out.push({
+          type: "agent.thinking",
+          payload: { content: [{ type: "thinking", thinking: item.text }] },
+        });
+        return out;
+      }
+
+      if (item.type === "agent_message" && typeof item.text === "string") {
+        lastText = item.text;
+        out.push({
+          type: "agent.message",
+          payload: { content: [{ type: "text", text: item.text }] },
+        });
+        return out;
+      }
+
+      if (item.type === "command_execution" && typeof item.id === "string") {
+        const name = "command";
+        const cls = classify(name);
+        toolClass.set(item.id, cls);
+        if (cls === "custom") sawCustom = true;
+        const useType = cls === "custom" ? "agent.custom_tool_use" : "agent.tool_use";
+
+        out.push({
+          type: useType,
+          payload: {
+            tool_use_id: item.id,
+            name,
+            input: { command: item.command ?? "" },
+          },
+        });
+        if (cls !== "custom") {
+          out.push({
+            type: "agent.tool_result",
+            payload: {
+              tool_use_id: item.id,
+              content: item.output ?? item.result ?? "",
+              is_error: false,
+            },
+          });
+        }
+        return out;
+      }
+
+      if (item.type === "mcp_tool_call" && typeof item.id === "string") {
+        const name = item.name ?? "mcp_tool";
+        const cls = classify(name);
+        toolClass.set(item.id, cls);
+        if (cls === "custom") sawCustom = true;
+        const useType = cls === "custom" ? "agent.custom_tool_use" : "agent.tool_use";
+
+        out.push({
+          type: useType,
+          payload: {
+            tool_use_id: item.id,
+            name,
+            input: item.input ?? {},
+          },
+        });
+        if (cls !== "custom") {
+          out.push({
+            type: "agent.tool_result",
+            payload: {
+              tool_use_id: item.id,
+              content: item.output ?? "",
+              is_error: false,
+            },
+          });
+        }
+        return out;
+      }
+
+      if (item.type === "file_change" && typeof item.id === "string") {
+        const name = "file_edit";
+        const cls = classify(name);
+        toolClass.set(item.id, cls);
+        if (cls === "custom") sawCustom = true;
+        const useType = cls === "custom" ? "agent.custom_tool_use" : "agent.tool_use";
+        out.push({
+          type: useType,
+          payload: {
+            tool_use_id: item.id,
+            name,
+            input: { path: item.path ?? "", action: item.action ?? "edit" },
+          },
+        });
+        return out;
+      }
+    }
+
+    if (type === "turn.completed") {
+      turnCount++;
+      const usage = raw.usage as Record<string, unknown> | undefined;
+      if (usage) {
+        if (typeof usage.input_tokens === "number") {
+          totalInputTokens += usage.input_tokens;
+        }
+        if (typeof usage.output_tokens === "number") {
+          totalOutputTokens += usage.output_tokens;
+        }
+        if (typeof usage.cost_usd === "number") {
+          totalCostUsd += usage.cost_usd;
+        }
+        // Defensive:  treats usage as Record<string, number>
+        // and sums all keys generically. We extract the specific fields we
+        // care about. Unknown keys are silently dropped.
+      }
+      return out;
+    }
+
+    if (type === "error") {
+      // Stream-level error — driver will catch + surface via session.error.
+      return out;
+    }
+
+    // Unknown event type — drop silently, translator is forward-compatible.
+    return out;
+  }
+
+  function getTurnResult(): TurnResult | null {
+    // Codex doesn't emit a sentinel "finished" event — turn.completed
+    // accumulates and the stream just closes. The driver calls this after
+    // the stream loop exits, which is the equivalent of '
+    // finalize() hook.
+    if (turnCount === 0 && !lastText) return null;
+    return {
+      stopReason: sawCustom ? "custom_tool_call" : "end_turn",
+      usage: {
+        input_tokens: totalInputTokens,
+        output_tokens: totalOutputTokens,
+        cache_read_input_tokens: 0,
+        cache_creation_input_tokens: 0,
+        cost_usd: totalCostUsd,
+      },
+      num_turns: turnCount || 1,
+    };
+  }
+
+  return {
+    translate,
+    getBackendSessionId: () => sessionId,
+    getTurnResult,
+    sawCustomToolUse: () => sawCustom,
+  };
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Sprite wrapper script for codex.
+ *
+ * Identical structure to the claude wrapper because codex has
+ * promptViaStdin: true — the wrapper reads env vars from stdin until a
+ * blank line, then execs codex with the remaining stdin piped through as
+ * the prompt. The trailing `-` in argv tells codex to read from stdin.
+ */
+import type { ContainerProvider } from "../../providers/types";
+
+export const CODEX_WRAPPER_PATH = "/tmp/.codex-wrapper";
+
+const SPRITE_WRAPPER_SCRIPT = [
+  "#!/bin/bash",
+  'while IFS= read -r line; do [ -z "$line" ] && break; export "$line"; done',
+  'exec codex "$@"',
+].join("\n");
+
+export async function installCodexWrapper(spriteName: string, provider: ContainerProvider): Promise<void> {
+  const escaped = SPRITE_WRAPPER_SCRIPT.replace(/'/g, "'\\''");
+  await provider.exec(spriteName, [
+    "bash",
+    "-c",
+    `printf '%s' '${escaped}' > ${CODEX_WRAPPER_PATH} && chmod +x ${CODEX_WRAPPER_PATH}`,
+  ]);
+}

package/src/backends/factory/args.ts

@@ -0,0 +1,45 @@
+/**
+ * Build the `droid exec` argv for one turn.
+ *
+ * Factory CLI constraints:
+ * - Uses `exec` subcommand (not `-p`)
+ * - `--output-format stream-json` for NDJSON streaming
+ * - `--auto high` for headless non-interactive execution
+ * - `--session-id <session_id>` on turn >= 2
+ * - `--model <model>` if specified on the agent
+ * - No --system-prompt flag — system prompt is wrapped into the user
+ *   prompt text via the shared wrapPromptWithSystem utility
+ * - The prompt is positional (last arg), NOT a flag. The wrapper script
+ *   captures it from stdin and passes it as `"$PROMPT"` at the end.
+ */
+import type { Agent } from "../../types";
+
+export interface BuildFactoryArgsInput {
+  agent: Agent;
+  /** Prior turn's factory session ID, if any, for --session-id resume */
+  backendSessionId: string | null;
+}
+
+export function buildFactoryArgs(input: BuildFactoryArgsInput): string[] {
+  const args: string[] = [
+    "exec",
+    "--output-format",
+    "stream-json",
+    "--auto",
+    "high",
+  ];
+
+  if (input.backendSessionId) {
+    args.push("--session-id", input.backendSessionId);
+  }
+
+  if (input.agent.model) {
+    args.push("--model", input.agent.model);
+  }
+
+  // NOTE: No trailing `-` or positional prompt here. The factory wrapper
+  // script captures the prompt from stdin via PROMPT=$(cat) and appends it
+  // as the last positional arg to `droid exec "$@" "$PROMPT"`.
+
+  return args;
+}

package/src/backends/factory/auth.ts

@@ -0,0 +1,30 @@
+/**
+ * Auth env + create-time validation for the factory backend.
+ *
+ * Factory CLI reads FACTORY_API_KEY from the environment. We forward it
+ * from config.factoryApiKey (which cascades from process.env.FACTORY_API_KEY
+ * or the settings table).
+ */
+import { getConfig } from "../../config";
+
+export function buildFactoryAuthEnv(): Record<string, string> {
+  const cfg = getConfig();
+  const env: Record<string, string> = {};
+  if (cfg.factoryApiKey) {
+    env.FACTORY_API_KEY = cfg.factoryApiKey;
+  }
+  return env;
+}
+
+/**
+ * Returns null if factory can run, or an error message if it can't. Used at
+ * agent create time (validateAgentCreation) and first-turn time
+ * (validateRuntime).
+ */
+export function validateFactoryRuntime(): string | null {
+  const cfg = getConfig();
+  if (!cfg.factoryApiKey) {
+    return "factory backend requires FACTORY_API_KEY to be set";
+  }
+  return null;
+}

package/src/backends/factory/index.ts

@@ -0,0 +1,56 @@
+/**
+ * Factory backend: drives Factory's `droid exec` on sprites.dev containers.
+ *
+ * Factory CLI uses `exec` subcommand with the prompt as a positional arg
+ * (like opencode). The wrapper script captures stdin and re-passes it as
+ * the trailing positional argv.
+ *
+ * Custom tool re-entry is NOT supported by factory — droid 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 { buildFactoryArgs } from "./args";
+import { buildFactoryAuthEnv, validateFactoryRuntime } from "./auth";
+import { createFactoryTranslator } from "./translator";
+import { FACTORY_WRAPPER_PATH } from "./wrapper-script";
+import { prepareFactoryOnSprite } from "./setup";
+
+function buildTurn(input: BuildTurnInput): BuildTurnResult {
+  const { agent, backendSessionId, promptText, toolResults } = input;
+  if (toolResults.length > 0) {
+    throw new ApiError(
+      400,
+      "invalid_request_error",
+      "factory backend does not support user.custom_tool_result re-entry in v1",
+    );
+  }
+  const argv = buildFactoryArgs({ agent, backendSessionId });
+  const env = buildFactoryAuthEnv();
+  const wrappedPrompt = wrapPromptWithSystem(promptText, agent.system);
+  // stdin is the raw wrapped prompt — the driver prepends the env block.
+  // The factory wrapper script captures this via PROMPT=$(cat) and
+  // re-passes it to `droid exec` as a trailing positional argv.
+  return { argv, env, stdin: wrappedPrompt };
+}
+
+export const factoryBackend: Backend = {
+  name: "factory" as Backend["name"],
+  wrapperPath: FACTORY_WRAPPER_PATH,
+  buildTurn,
+  createTranslator: (opts: TranslatorOptions) => createFactoryTranslator(opts),
+  prepareOnSprite: (name, provider) => prepareFactoryOnSprite(name, provider),
+
+  validateRuntime: validateFactoryRuntime,
+};
+
+export {
+  buildFactoryArgs,
+  buildFactoryAuthEnv,
+  createFactoryTranslator,
+  prepareFactoryOnSprite,
+  FACTORY_WRAPPER_PATH,
+};

package/src/backends/factory/setup.ts

@@ -0,0 +1,34 @@
+/**
+ * Install factory (droid) CLI on a freshly-created sprite.
+ *
+ * Mirrors codex/setup.ts with the same sentinel + symlink pattern.
+ * Factory CLI is installed via npm from the @factory/cli package.
+ */
+import type { ContainerProvider } from "../../providers/types";
+import { installFactoryWrapper } from "./wrapper-script";
+
+const SENTINEL_NAME = ".claude-agents-factory-installed";
+
+export async function prepareFactoryOnSprite(spriteName: string, provider: ContainerProvider): Promise<void> {
+  await installFactoryWrapper(spriteName, provider);
+
+  const script = [
+    "set -euo pipefail",
+    `SENTINEL="$HOME/${SENTINEL_NAME}"`,
+    'if [ -f "$SENTINEL" ]; then exit 0; fi',
+    "npm install -g @factory/cli",
+    "PREFIX=$(npm config get prefix)",
+    'if [ "$PREFIX" != "/usr/local" ]; then ln -sf "$PREFIX/bin/droid" /usr/local/bin/droid; fi',
+    '/usr/local/bin/droid --version || $PREFIX/bin/droid --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(
+      `factory install failed (${result.exit_code}): ${result.stderr.slice(0, 500)}`,
+    );
+  }
+}

package/src/backends/factory/translator.ts

@@ -0,0 +1,139 @@
+/**
+ * Stateful translator: Factory CLI stream-json NDJSON -> Managed Agents events.
+ *
+ * Factory CLI event model (emitted by `droid exec --output-format stream-json`):
+ *   - `system` (subtype: "init") — session init with `session_id` and `model`
+ *   - `message`    — assistant text (role: "assistant", text: string) NOTE: `text` not `content`
+ *   - `tool_call`  — tool invocation (toolName, id, parameters)
+ *   - `tool_result` — tool output (id, value, isError)
+ *   - `completion`  — end of turn (finalText, numTurns, durationMs)
+ *
+ * Maps to Managed Agents events using the same Translator interface as other
+ * backends.
+ */
+import type {
+  ToolClass,
+  TranslatedEvent,
+  Translator,
+  TranslatorOptions,
+  TurnResult,
+} from "../shared/translator-types";
+
+export function createFactoryTranslator(opts: TranslatorOptions): Translator {
+  const toolClass = new Map<string, ToolClass>();
+  let sessionId: string | null = null;
+  let lastText = "";
+  let sawCustom = false;
+  let sawCompletion = false;
+  let numTurns = 0;
+  let durationMs = 0;
+
+  function classify(name: string): ToolClass {
+    if (opts.customToolNames.has(name)) return "custom";
+    return "builtin";
+  }
+
+  function translate(raw: Record<string, unknown>): TranslatedEvent[] {
+    const out: TranslatedEvent[] = [];
+    if (!raw || typeof raw !== "object") return out;
+    const type = String(raw.type ?? "");
+
+    // system init event
+    if (type === "system" && raw.subtype === "init") {
+      if (typeof raw.session_id === "string") sessionId = raw.session_id;
+      return out;
+    }
+
+    // assistant message — note: Factory uses `text` not `content`
+    if (type === "message" && raw.role === "assistant") {
+      const text = typeof raw.text === "string" ? raw.text : "";
+      if (text) {
+        lastText = text;
+        out.push({
+          type: "agent.message",
+          payload: { content: [{ type: "text", text }] },
+        });
+      }
+      return out;
+    }
+
+    // tool call — note: Factory uses `toolName` not `tool_name`
+    if (type === "tool_call") {
+      const toolName = String(raw.toolName ?? "unknown");
+      const toolId = String(raw.id ?? "");
+      const parameters = (raw.parameters ?? {}) as Record<string, unknown>;
+
+      const cls = classify(toolName);
+      toolClass.set(toolId, cls);
+      if (cls === "custom") sawCustom = true;
+
+      const useType = cls === "custom" ? "agent.custom_tool_use" : "agent.tool_use";
+      out.push({
+        type: useType,
+        payload: {
+          tool_use_id: toolId,
+          name: toolName,
+          input: parameters,
+        },
+      });
+      return out;
+    }
+
+    // tool result — note: Factory uses `value` not `output`
+    if (type === "tool_result") {
+      const toolId = String(raw.id ?? "");
+      const value = typeof raw.value === "string" ? raw.value : JSON.stringify(raw.value ?? "");
+      const isError = raw.isError === true;
+      const cls = toolClass.get(toolId);
+
+      // Only emit tool_result for builtin tools
+      if (cls !== "custom") {
+        out.push({
+          type: "agent.tool_result",
+          payload: {
+            tool_use_id: toolId,
+            content: value,
+            is_error: isError,
+          },
+        });
+      }
+      return out;
+    }
+
+    // completion — end of turn
+    if (type === "completion") {
+      sawCompletion = true;
+      if (typeof raw.finalText === "string") lastText = raw.finalText;
+      if (typeof raw.numTurns === "number") numTurns = raw.numTurns;
+      if (typeof raw.durationMs === "number") durationMs = raw.durationMs;
+      return out;
+    }
+
+    // Unknown event type — drop silently, translator is forward-compatible.
+    return out;
+  }
+
+  function getTurnResult(): TurnResult | null {
+    if (!sawCompletion && !lastText) return null;
+    // Factory's completion event does not include token usage or cost.
+    // We report zeros — usage tracking is best-effort for this backend.
+    return {
+      stopReason: sawCustom ? "custom_tool_call" : "end_turn",
+      usage: {
+        input_tokens: 0,
+        output_tokens: 0,
+        cache_read_input_tokens: 0,
+        cache_creation_input_tokens: 0,
+        cost_usd: 0,
+      },
+      num_turns: numTurns || 1,
+    };
+  }
+
+  return {
+    translate,
+    getBackendSessionId: () => sessionId,
+    getTurnResult,
+    sawCustomToolUse: () => sawCustom,
+  };
+}

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

@@ -0,0 +1,33 @@
+/**
+ * Sprite wrapper script for factory (droid).
+ *
+ * Factory's `droid exec` takes the prompt as a positional argument (like
+ * opencode), NOT from stdin. The wrapper:
+ *
+ *   1. Reads env vars from stdin until a blank line
+ *   2. Captures the remaining stdin into $PROMPT
+ *   3. Execs `droid exec "$@" "$PROMPT"` — the prompt becomes the last
+ *      positional arg after any flags from argv
+ *
+ * This mirrors the opencode wrapper pattern exactly.
+ */
+import type { ContainerProvider } from "../../providers/types";
+
+export const FACTORY_WRAPPER_PATH = "/tmp/.factory-wrapper";
+
+const SPRITE_WRAPPER_SCRIPT = [
+  "#!/bin/bash",
+  "set -e",
+  'while IFS= read -r line; do [ -z "$line" ] && break; export "$line"; done',
+  "PROMPT=$(cat)",
+  'exec droid "$@" "$PROMPT"',
+].join("\n");
+
+export async function installFactoryWrapper(spriteName: string, provider: ContainerProvider): Promise<void> {
+  const escaped = SPRITE_WRAPPER_SCRIPT.replace(/'/g, "'\\''");
+  await provider.exec(spriteName, [
+    "bash",
+    "-c",
+    `printf '%s' '${escaped}' > ${FACTORY_WRAPPER_PATH} && chmod +x ${FACTORY_WRAPPER_PATH}`,
+  ]);
+}

package/src/backends/gemini/args.ts

@@ -0,0 +1,44 @@
+/**
+ * Build the `gemini -p` argv for one turn.
+ *
+ * Gemini CLI constraints:
+ * - `-p` flag for prompt mode (reads prompt from stdin)
+ * - `--output-format stream-json` for NDJSON streaming
+ * - `--yolo` to bypass permission prompts in headless mode
+ * - `--max-turns <N>` to cap reasoning turns
+ * - `--resume <session_id>` on turn >= 2
+ * - `--model <model>` if specified on the agent
+ * - No --system-prompt flag — system prompt is wrapped into the user
+ *   prompt text via the shared wrapPromptWithSystem utility
+ */
+import { getConfig } from "../../config";
+import type { Agent } from "../../types";
+
+export interface BuildGeminiArgsInput {
+  agent: Agent;
+  /** Prior turn's gemini session ID, if any, for --resume */
+  backendSessionId: string | null;
+  maxTurns?: number;
+}
+
+export function buildGeminiArgs(input: BuildGeminiArgsInput): string[] {
+  const cfg = getConfig();
+  const args: string[] = [
+    "-p",
+    "--output-format",
+    "stream-json",
+    "--yolo",
+    "--max-turns",
+    String(input.maxTurns ?? cfg.agentMaxTurns),
+  ];
+
+  if (input.backendSessionId) {
+    args.push("--resume", input.backendSessionId);
+  }
+
+  if (input.agent.model) {
+    args.push("--model", input.agent.model);
+  }
+
+  return args;
+}

package/src/backends/gemini/auth.ts

@@ -0,0 +1,30 @@
+/**
+ * Auth env + create-time validation for the gemini backend.
+ *
+ * Gemini CLI reads GEMINI_API_KEY from the environment. We forward it
+ * from config.geminiApiKey (which cascades from process.env.GEMINI_API_KEY
+ * or the settings table).
+ */
+import { getConfig } from "../../config";
+
+export function buildGeminiAuthEnv(): Record<string, string> {
+  const cfg = getConfig();
+  const env: Record<string, string> = {};
+  if (cfg.geminiApiKey) {
+    env.GEMINI_API_KEY = cfg.geminiApiKey;
+  }
+  return env;
+}
+
+/**
+ * Returns null if gemini can run, or an error message if it can't. Used at
+ * agent create time (validateAgentCreation) and first-turn time
+ * (validateRuntime).
+ */
+export function validateGeminiRuntime(): string | null {
+  const cfg = getConfig();
+  if (!cfg.geminiApiKey) {
+    return "gemini backend requires GEMINI_API_KEY to be set";
+  }
+  return null;
+}