@agentstep/agent-sdk 0.1.0

package/src/backends/opencode/translator.ts

@@ -0,0 +1,168 @@
+/**
+ * Stateful translator: opencode NDJSON → Managed Agents events.
+ *
+ * Ported from
+ * 
+ *
+ * Opencode's event model (emitted by `opencode run --format json`):
+ *   - `step_start` — an agent step is starting. Carries `sessionID` on the
+ *     root event object. First occurrence marks the first turn.
+ *   - `text` — assistant text content, in `part.text`
+ *   - `tool_use` — assistant is calling a tool, in `part.tool`,
+ *     `part.callID`, `part.state.input`
+ *   - `step_finish` — end of a step. Carries `part.cost`, `part.tokens`,
+ *     `part.reason`. `reason === "stop"` signals turn end.
+ *
+ * Note: opencode does NOT emit tool_result events in its NDJSON stream —
+ * tool execution is handled by opencode's own plugins/built-ins, and the
+ * results are folded into subsequent assistant content. This translator
+ * does not need a tool_result case.
+ *
+ * The Managed Agents side (our taxonomy) this maps to:
+ *   - system.init (internal state only — driver emits session.status_running)
+ *   - agent.message for text
+ *   - agent.tool_use / agent.custom_tool_use based on customToolNames
+ *   - result → TurnResult with stop_reason "end_turn" + usage aggregation
+ */
+import type {
+  ToolClass,
+  TranslatedEvent,
+  Translator,
+  TranslatorOptions,
+  TurnResult,
+  TurnUsage,
+} from "../shared/translator-types";
+
+interface OpencodePart {
+  text?: string;
+  tool?: string;
+  callID?: string;
+  id?: string;
+  state?: { input?: unknown };
+  cost?: number;
+  tokens?: { input?: number; output?: number };
+  reason?: string;
+}
+
+export function createOpencodeTranslator(opts: TranslatorOptions): Translator {
+  const toolClass = new Map<string, ToolClass>();
+  let sessionId: string | null = null;
+  let seenFirstStep = false;
+  let sawCustom = false;
+  let totalCostUsd = 0;
+  let totalInputTokens = 0;
+  let totalOutputTokens = 0;
+  let stepCount = 0;
+  let turnResult: TurnResult | null = null;
+
+  function classify(name: string): ToolClass {
+    if (opts.customToolNames.has(name)) return "custom";
+    // Opencode tools don't use the `mcp__` prefix convention; treat
+    // everything else as a built-in tool for now. (Future: if opencode
+    // exposes MCP tools with a distinct prefix, classify them here.)
+    return "builtin";
+  }
+
+  function translate(raw: Record<string, unknown>): TranslatedEvent[] {
+    const out: TranslatedEvent[] = [];
+    if (!raw || typeof raw !== "object") return out;
+
+    // Opencode puts sessionID on the root of every event that has session
+    // context (step_start, text, tool_use, step_finish). We track it in
+    // state and expose via getBackendSessionId.
+    if (typeof raw.sessionID === "string" && raw.sessionID) {
+      sessionId = raw.sessionID;
+    }
+
+    const type = String(raw.type ?? "");
+
+    switch (type) {
+      case "step_start": {
+        stepCount++;
+        if (!seenFirstStep) {
+          seenFirstStep = true;
+          // session.status_running is emitted by the driver, not the translator.
+          // We only track state here.
+        }
+        return out;
+      }
+
+      case "text": {
+        const part = (raw.part as OpencodePart | undefined) ?? {};
+        const text = part.text ?? "";
+        if (text) {
+          out.push({
+            type: "agent.message",
+            payload: {
+              content: [{ type: "text", text }],
+            },
+          });
+        }
+        return out;
+      }
+
+      case "tool_use": {
+        const part = (raw.part as OpencodePart | undefined) ?? {};
+        const toolUseId = part.callID ?? part.id ?? "";
+        const name = part.tool ?? "unknown";
+        const input = part.state?.input ?? {};
+        if (!toolUseId) return out;
+
+        const cls = classify(name);
+        toolClass.set(toolUseId, cls);
+        if (cls === "custom") {
+          sawCustom = true;
+          out.push({
+            type: "agent.custom_tool_use",
+            payload: { tool_use_id: toolUseId, name, input },
+          });
+        } else {
+          out.push({
+            type: "agent.tool_use",
+            payload: { tool_use_id: toolUseId, name, input },
+          });
+        }
+        return out;
+      }
+
+      case "step_finish": {
+        const part = (raw.part as OpencodePart | undefined) ?? {};
+        totalCostUsd += part.cost ?? 0;
+        if (part.tokens) {
+          totalInputTokens += part.tokens.input ?? 0;
+          totalOutputTokens += part.tokens.output ?? 0;
+        }
+        if (part.reason === "stop") {
+          const usage: TurnUsage = {
+            input_tokens: totalInputTokens,
+            output_tokens: totalOutputTokens,
+            cache_read_input_tokens: 0,
+            cache_creation_input_tokens: 0,
+            cost_usd: totalCostUsd,
+          };
+          const stopReason: TurnResult["stopReason"] = sawCustom
+            ? "custom_tool_call"
+            : "end_turn";
+          turnResult = {
+            stopReason,
+            usage,
+            num_turns: stepCount,
+          };
+        }
+        // Non-"stop" step_finish: just accumulate, no turn result yet
+        return out;
+      }
+
+      default:
+        // Unrecognized — drop silently, translator is forward-compatible.
+        return out;
+    }
+  }
+
+  return {
+    translate,
+    getBackendSessionId: () => sessionId,
+    getTurnResult: () => turnResult,
+    sawCustomToolUse: () => sawCustom,
+  };
+}

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

@@ -0,0 +1,46 @@
+/**
+ * Sprite wrapper script for opencode.
+ *
+ * Opencode (unlike claude) does NOT accept the prompt on stdin — it takes
+ * the prompt as a positional argv. But the prompt is too large/unsafe to
+ * transport via sprites.dev's `?cmd=...` HTTP query params. So the wrapper:
+ *
+ *   1. Reads env vars from stdin until a blank line (same protocol as
+ *      claude's wrapper — KEY=value per line, blank line terminator)
+ *   2. Captures the remaining stdin into a `$PROMPT` shell variable
+ *   3. Execs `opencode <argv> "$PROMPT"` — injecting the prompt as a
+ *      trailing positional argv entry
+ *
+ * This keeps the prompt on the HTTP request body (not the URL) and still
+ * lets opencode receive it in the argv shape it expects.
+ *
+ * NOTE: `buildOpencodeArgs` must never end argv with a flag that expects
+ * its own value (e.g. a dangling `--model` without the model name) —
+ * otherwise `"$PROMPT"` would bind to the wrong flag. All current
+ * `buildOpencodeArgs` output is safe (flag + value pairs, no trailing
+ * dangling flag).
+ *
+ * NOTE 2: `PROMPT=$(cat)` strips trailing newlines from the captured body.
+ * For normal prompts this is a harmless quirk; very prompt-sensitive
+ * consumers should be aware.
+ */
+import type { ContainerProvider } from "../../providers/types";
+
+export const OPENCODE_WRAPPER_PATH = "/tmp/.opencode-wrapper";
+
+const SPRITE_WRAPPER_SCRIPT = [
+  "#!/bin/bash",
+  "set -e",
+  'while IFS= read -r line; do [ -z "$line" ] && break; export "$line"; done',
+  "PROMPT=$(cat)",
+  'exec opencode "$@" "$PROMPT"',
+].join("\n");
+
+export async function installOpencodeWrapper(spriteName: string, provider: ContainerProvider): Promise<void> {
+  const escaped = SPRITE_WRAPPER_SCRIPT.replace(/'/g, "'\\''");
+  await provider.exec(spriteName, [
+    "bash",
+    "-c",
+    `printf '%s' '${escaped}' > ${OPENCODE_WRAPPER_PATH} && chmod +x ${OPENCODE_WRAPPER_PATH}`,
+  ]);
+}

package/src/backends/registry.ts

@@ -0,0 +1,38 @@
+/**
+ * Backend registry: maps a backend name to its concrete implementation.
+ *
+ * Kept in its own file so types.ts and the concrete backends can import the
+ * type definitions without circular dependencies. The driver imports only
+ * from here.
+ */
+import type { Backend, BackendName } from "./types";
+import { claudeBackend } from "./claude";
+import { opencodeBackend } from "./opencode";
+import { codexBackend } from "./codex";
+import { geminiBackend } from "./gemini";
+import { factoryBackend } from "./factory";
+
+const BACKENDS: Record<BackendName, Backend> = {
+  claude: claudeBackend,
+  opencode: opencodeBackend,
+  codex: codexBackend,
+  gemini: geminiBackend,
+  factory: factoryBackend,
+};
+
+/**
+ * Resolve a backend by name, defaulting to claude for undefined input.
+ * Throws if the name is set but unknown.
+ */
+export function resolveBackend(
+  name: BackendName | string | null | undefined,
+): Backend {
+  const key = (name ?? "claude") as BackendName;
+  const b = BACKENDS[key];
+  if (!b) throw new Error(`unknown backend: ${name}`);
+  return b;
+}
+
+export function listBackends(): BackendName[] {
+  return Object.keys(BACKENDS) as BackendName[];
+}

package/src/backends/shared/ndjson.ts

@@ -0,0 +1,29 @@
+/**
+ * NDJSON line parser for streaming CLI output (backend-agnostic).
+ *
+ * Returns the incomplete trailing portion so the caller can keep buffering.
+ * Lifted in spirit from
+ * 
+ *
+ * Note: the driver strips sprites.dev HTTP exec framing bytes (0x00-0x1F)
+ * from the raw stream BEFORE calling this parser — this parser does not
+ * mangle bytes itself.
+ */
+export function parseNDJSONLines(
+  buffer: string,
+  onLine: (parsed: Record<string, unknown>) => void,
+): string {
+  const lines = buffer.split("\n");
+  const remainder = lines.pop() ?? "";
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const parsed = JSON.parse(trimmed) as Record<string, unknown>;
+      onLine(parsed);
+    } catch {
+      // Skip non-JSON lines (progress noise, stray log output)
+    }
+  }
+  return remainder;
+}

package/src/backends/shared/translator-types.ts

@@ -0,0 +1,69 @@
+/**
+ * Shared translator contract — implemented by every backend's translator
+ * (claude, opencode, ...). Decoupled from any particular CLI event shape.
+ *
+ * A Translator consumes raw NDJSON events from a backend CLI and produces
+ * Managed Agents event payloads (unwrapped — the bus adds id/seq/etc).
+ *
+ * Implementations are stateful per-turn: they track the backend session id
+ * so the driver can persist it and use it on the next `--resume`/`--session`
+ * turn, and they track whether any custom tool was emitted so the driver can
+ * flip the turn's `stop_reason` to "custom_tool_call".
+ */
+
+export type ToolClass = "builtin" | "mcp" | "custom";
+
+export interface TranslatedEvent {
+  type: string;
+  payload: Record<string, unknown>;
+}
+
+export interface TurnUsage {
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_input_tokens: number;
+  cache_creation_input_tokens: number;
+  cost_usd: number;
+}
+
+export interface TurnResult {
+  stopReason: "end_turn" | "max_turns" | "error" | "custom_tool_call";
+  usage: TurnUsage;
+  num_turns: number;
+}
+
+export interface Translator {
+  /**
+   * Consume a single raw CLI NDJSON event and return zero or more Managed
+   * Agents event payloads. These are appended to the session via
+   * `bus.appendEventsBatch` by the driver.
+   */
+  translate(raw: Record<string, unknown>): TranslatedEvent[];
+
+  /**
+   * Latest backend session id observed so far (claude `system.init.session_id`
+   * or opencode `sessionID`). Exposed so the driver can persist it and use
+   * it on the next turn's resume flag.
+   */
+  getBackendSessionId(): string | null;
+
+  /** Summarize the turn from the most recent `result` event for the driver */
+  getTurnResult(): TurnResult | null;
+
+  /** True if any custom tool was emitted during this turn */
+  sawCustomToolUse(): boolean;
+}
+
+export interface TranslatorOptions {
+  /**
+   * Names of custom tools defined on the agent. Used to classify tool_use
+   * events the translator doesn't otherwise recognize.
+   */
+  customToolNames: Set<string>;
+
+  /**
+   * True if this is the first turn of the session. Controls whether
+   * `system.init`-equivalent events trigger status_running (first turn only).
+   */
+  isFirstTurn: boolean;
+}

package/src/backends/shared/wrap-prompt.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared prompt wrapper for backends that lack a `--system-prompt` CLI flag
+ * (opencode, codex). If a system prompt is set on the agent, prepend it to
+ * the user prompt with a separator. If no system prompt, return the prompt
+ * unchanged.
+ *
+ * Pattern from
+ * 
+ * (opencode) and 253-256 (codex) — both use the identical wrapping format.
+ */
+export function wrapPromptWithSystem(
+  prompt: string,
+  systemPrompt: string | null | undefined,
+): string {
+  if (!systemPrompt) return prompt;
+  return `Instructions: ${systemPrompt}\n\n---\n\n${prompt}`;
+}

package/src/backends/types.ts

@@ -0,0 +1,85 @@
+/**
+ * Backend abstraction: a pluggable CLI engine that powers a session turn.
+ *
+ * Concrete backends (claude, opencode) implement this interface. The driver
+ * resolves a Backend from the agent's `backend` field via the registry and
+ * delegates argv/env/stdin construction and stream translation to it.
+ *
+ * Design notes:
+ * - argv, env, stdin are returned as three separate primitives so the driver
+ *   owns the stdin framing composition (env KEY=value lines + blank line +
+ *   prompt body). This prevents each backend from reinventing the glue and
+ *   silently diverging.
+ * - stdin is the PROMPT BODY, not the full wrapper body. The driver composes
+ *   the final wrapper stdin as `envLines + "\n\n" + stdin`. The prompt rides
+ *   the HTTP request body (not the URL) — URL length caps on sprites.dev's
+ *   `?cmd=...` query params are the reason we can't just put it in argv.
+ *   Claude's wrapper pipes the prompt to stdin of claude; opencode's wrapper
+ *   captures it into $PROMPT and re-passes it as argv to opencode (which
+ *   doesn't accept stdin prompts).
+ */
+import type { Agent } from "../types";
+import type { ContainerProvider } from "../providers/types";
+import type { Translator, TranslatorOptions } from "./shared/translator-types";
+
+/** CLI backends that have a Backend implementation in the registry */
+export type CliBackendName = "claude" | "opencode" | "codex" | "gemini" | "factory";
+/** All backend names including proxy-only backends */
+export type AnyBackendName = CliBackendName | "anthropic";
+
+/** @deprecated Use CliBackendName or AnyBackendName depending on context */
+export type BackendName = CliBackendName;
+
+export interface BuildTurnInput {
+  agent: Agent;
+  /** session id from a prior turn; null on turn 1 */
+  backendSessionId: string | null;
+  /** plain-text prompt text (concatenated from all pending text inputs) */
+  promptText: string;
+  /** tool_result inputs for backends that support mid-turn re-entry */
+  toolResults: Array<{ custom_tool_use_id: string; content: unknown[] }>;
+}
+
+export interface BuildTurnResult {
+  /** argv to append after the wrapper path — does NOT include the prompt text */
+  argv: string[];
+  /** env vars to inject via the wrapper's stdin env-read loop (auth + MCP + etc.) */
+  env: Record<string, string>;
+  /**
+   * prompt body to send on stdin after the env block. For claude this is the
+   * raw prompt OR the stream-json user frame (when toolResults is non-empty).
+   * For opencode this is the wrapped prompt (system prompt prepended if set)
+   * that the opencode wrapper captures via `PROMPT=$(cat)` and re-passes as
+   * argv to opencode.
+   */
+  stdin: string;
+}
+
+export interface Backend {
+  name: BackendName;
+  /** Absolute path to this backend's wrapper script on the sprite */
+  wrapperPath: string;
+  /**
+   * Build argv + env + stdin primitives for one turn of this backend.
+   * The driver composes the final wrapper stdin as `envLines \n\n stdin`.
+   */
+  buildTurn(input: BuildTurnInput): BuildTurnResult;
+  /** Stateful translator, created fresh per turn */
+  createTranslator(opts: TranslatorOptions): Translator;
+  /**
+   * Install / verify the backend binary + wrapper on a freshly-created sprite.
+   * Safe to call multiple times (idempotent via sentinels).
+   */
+  prepareOnSprite(spriteName: string, provider: ContainerProvider): Promise<void>;
+  /**
+   * Agent-create-time validation: return an error message if this backend
+   * cannot run with the current config (e.g. opencode + no API key).
+   */
+  validateAgentCreation?(): string | null;
+  /**
+   * First-turn runtime validation: belt-and-braces check that the backend
+   * can run NOW (config may have changed since agent create). Called from
+   * the driver before acquireForFirstTurn.
+   */
+  validateRuntime?(): string | null;
+}

package/src/config/index.ts

@@ -0,0 +1,95 @@
+/**
+ * Config cascade: env → settings table → defaults, 30s cache.
+ *
+ * Inspired by 
+ */
+import { getDb } from "../db/client";
+import { nowMs } from "../util/clock";
+
+export interface Config {
+  spriteToken: string | undefined;
+  spriteApi: string;
+  anthropicApiKey: string | undefined;
+  claudeToken: string | undefined;
+  openAiApiKey: string | undefined;
+  geminiApiKey: string | undefined;
+  factoryApiKey: string | undefined;
+  defaultModel: string;
+  agentMaxTurns: number;
+  agentTimeoutMs: number;
+  spriteTimeoutMs: number;
+  concurrency: number;
+  maxSpritesPerEnv: number;
+  sessionMaxAgeMs: number;
+  sweeperIntervalMs: number;
+}
+
+type GlobalCache = typeof globalThis & {
+  __caConfigCache?: { at: number; value: Config };
+};
+const g = globalThis as GlobalCache;
+
+const CACHE_MS = 30_000;
+
+function readSetting(key: string): string | undefined {
+  try {
+    const db = getDb();
+    const row = db
+      .prepare(
+        `SELECT value FROM settings WHERE key = ?`,
+      )
+      .get(key) as { value: string | null } | undefined;
+    return row?.value ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function num(env: string | undefined, fallback: number): number {
+  if (env == null) return fallback;
+  const n = Number(env);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+function loadConfig(): Config {
+  return {
+    spriteToken: process.env.SPRITE_TOKEN || readSetting("sprite_token"),
+    spriteApi:
+      process.env.SPRITE_API || readSetting("sprite_api") || "https://api.sprites.dev",
+    anthropicApiKey:
+      process.env.ANTHROPIC_API_KEY || readSetting("anthropic_api_key"),
+    claudeToken:
+      process.env.CLAUDE_CODE_OAUTH_TOKEN || readSetting("claude_token"),
+    openAiApiKey:
+      process.env.OPENAI_API_KEY || readSetting("openai_api_key"),
+    geminiApiKey:
+      process.env.GEMINI_API_KEY || readSetting("gemini_api_key") || undefined,
+    factoryApiKey:
+      process.env.FACTORY_API_KEY || readSetting("factory_api_key") || undefined,
+    defaultModel:
+      process.env.DEFAULT_MODEL ||
+      readSetting("default_model") ||
+      "claude-sonnet-4-6",
+    agentMaxTurns: num(process.env.AGENT_MAX_TURNS, 10),
+    agentTimeoutMs: num(process.env.AGENT_TIMEOUT_MS, 600_000),
+    spriteTimeoutMs: num(process.env.SPRITE_TIMEOUT_MS, 30_000),
+    concurrency: num(process.env.CONCURRENCY, 4),
+    maxSpritesPerEnv: num(process.env.MAX_SPRITES_PER_ENV, 8),
+    sessionMaxAgeMs: num(process.env.SESSION_MAX_AGE_MS, 7 * 24 * 3600 * 1000),
+    sweeperIntervalMs: num(process.env.SWEEPER_INTERVAL_MS, 60_000),
+  };
+}
+
+export function getConfig(): Config {
+  const now = nowMs();
+  if (g.__caConfigCache && now - g.__caConfigCache.at < CACHE_MS) {
+    return g.__caConfigCache.value;
+  }
+  const value = loadConfig();
+  g.__caConfigCache = { at: now, value };
+  return value;
+}
+
+export function invalidateConfigCache(): void {
+  g.__caConfigCache = undefined;
+}