@agentstep/agent-sdk 0.1.0

package/src/backends/gemini/index.ts

@@ -0,0 +1,53 @@
+/**
+ * Gemini backend: drives Google's `gemini -p` on sprites.dev containers.
+ *
+ * Gemini CLI uses `-p` for prompt mode (like claude) and accepts the prompt
+ * on stdin. The wrapper script reads env vars then pipes remaining stdin to
+ * gemini.
+ *
+ * Custom tool re-entry is NOT supported by gemini — gemini 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 { buildGeminiArgs } from "./args";
+import { buildGeminiAuthEnv, validateGeminiRuntime } from "./auth";
+import { createGeminiTranslator } from "./translator";
+import { GEMINI_WRAPPER_PATH } from "./wrapper-script";
+import { prepareGeminiOnSprite } from "./setup";
+
+function buildTurn(input: BuildTurnInput): BuildTurnResult {
+  const { agent, backendSessionId, promptText, toolResults } = input;
+  if (toolResults.length > 0) {
+    throw new ApiError(
+      400,
+      "invalid_request_error",
+      "gemini backend does not support user.custom_tool_result re-entry in v1",
+    );
+  }
+  const argv = buildGeminiArgs({ agent, backendSessionId });
+  const env = buildGeminiAuthEnv();
+  const wrappedPrompt = wrapPromptWithSystem(promptText, agent.system);
+  return { argv, env, stdin: wrappedPrompt };
+}
+
+export const geminiBackend: Backend = {
+  name: "gemini" as Backend["name"],
+  wrapperPath: GEMINI_WRAPPER_PATH,
+  buildTurn,
+  createTranslator: (opts: TranslatorOptions) => createGeminiTranslator(opts),
+  prepareOnSprite: (name, provider) => prepareGeminiOnSprite(name, provider),
+
+  validateRuntime: validateGeminiRuntime,
+};
+
+export {
+  buildGeminiArgs,
+  buildGeminiAuthEnv,
+  createGeminiTranslator,
+  prepareGeminiOnSprite,
+  GEMINI_WRAPPER_PATH,
+};

package/src/backends/gemini/setup.ts

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

package/src/backends/gemini/translator.ts

@@ -0,0 +1,139 @@
+/**
+ * Stateful translator: Gemini CLI stream-json NDJSON -> Managed Agents events.
+ *
+ * Gemini CLI event model (emitted by `gemini -p --output-format stream-json`):
+ *   - `init`         — session init with `session_id` and `model`
+ *   - `message`      — assistant text message (role: "assistant", content: string)
+ *   - `tool_use`     — tool invocation (tool_name, tool_id, parameters)
+ *   - `tool_result`  — tool output (tool_id, output, is_error?)
+ *   - `result`       — end of turn with status and usage stats
+ *
+ * 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 createGeminiTranslator(opts: TranslatorOptions): Translator {
+  const toolClass = new Map<string, ToolClass>();
+  let sessionId: string | null = null;
+  let lastText = "";
+  let sawCustom = false;
+
+  // Usage from the result event
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let costUsd = 0;
+  let numTurns = 0;
+  let sawResult = 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 === "init") {
+      if (typeof raw.session_id === "string") sessionId = raw.session_id;
+      return out;
+    }
+
+    if (type === "message" && raw.role === "assistant") {
+      const content = typeof raw.content === "string" ? raw.content : "";
+      if (content) {
+        lastText = content;
+        out.push({
+          type: "agent.message",
+          payload: { content: [{ type: "text", text: content }] },
+        });
+      }
+      return out;
+    }
+
+    if (type === "tool_use") {
+      const toolName = String(raw.tool_name ?? "unknown");
+      const toolId = String(raw.tool_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;
+    }
+
+    if (type === "tool_result") {
+      const toolId = String(raw.tool_id ?? "");
+      const output = typeof raw.output === "string" ? raw.output : JSON.stringify(raw.output ?? "");
+      const isError = raw.is_error === true;
+      const cls = toolClass.get(toolId);
+
+      // Only emit tool_result for builtin tools — custom tools are handled
+      // by the client via user.custom_tool_result
+      if (cls !== "custom") {
+        out.push({
+          type: "agent.tool_result",
+          payload: {
+            tool_use_id: toolId,
+            content: output,
+            is_error: isError,
+          },
+        });
+      }
+      return out;
+    }
+
+    if (type === "result") {
+      sawResult = true;
+      const stats = (raw.stats ?? {}) as Record<string, unknown>;
+      if (typeof stats.input_tokens === "number") inputTokens = stats.input_tokens;
+      if (typeof stats.output_tokens === "number") outputTokens = stats.output_tokens;
+      if (typeof stats.cost_usd === "number") costUsd = stats.cost_usd;
+      if (typeof stats.num_turns === "number") numTurns = stats.num_turns;
+      return out;
+    }
+
+    // Unknown event type — drop silently, translator is forward-compatible.
+    return out;
+  }
+
+  function getTurnResult(): TurnResult | null {
+    if (!sawResult && !lastText) return null;
+    return {
+      stopReason: sawCustom ? "custom_tool_call" : "end_turn",
+      usage: {
+        input_tokens: inputTokens,
+        output_tokens: outputTokens,
+        cache_read_input_tokens: 0,
+        cache_creation_input_tokens: 0,
+        cost_usd: costUsd,
+      },
+      num_turns: numTurns || 1,
+    };
+  }
+
+  return {
+    translate,
+    getBackendSessionId: () => sessionId,
+    getTurnResult,
+    sawCustomToolUse: () => sawCustom,
+  };
+}

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

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

package/src/backends/opencode/args.ts

@@ -0,0 +1,53 @@
+/**
+ * Build the `opencode run` argv for one turn.
+ *
+ * Ported from
+ * 
+ *
+ * Opencode-specific constraints:
+ * - No --max-turns (opencode has no equivalent; silently ignored)
+ * - No --allowed-tools / --disallowed-tools (tools are configured via
+ *   ~/.opencode.json permissions, not per-agent CLI flags — agents with
+ *   a non-empty `tools` field are rejected at create time)
+ * - No --permission-mode (opencode `run` is non-interactive by design)
+ * - No --system-prompt flag — system prompt is wrapped into the user
+ *   prompt text via `wrapOpencodePrompt`
+ * - No --mcp-config flag — MCP config is delivered via the
+ *   OPENCODE_CONFIG_CONTENT env var (see mcp.ts)
+ */
+import type { Agent } from "../../types";
+
+export interface BuildOpencodeArgsInput {
+  agent: Agent;
+  /** Prior turn's opencode sessionID, if any, for --session resume */
+  backendSessionId: string | null;
+}
+
+export function buildOpencodeArgs(input: BuildOpencodeArgsInput): string[] {
+  const args = ["run", "--format", "json"];
+  if (input.backendSessionId) {
+    args.push("--session", input.backendSessionId);
+  }
+  if (input.agent.model) {
+    args.push("--model", input.agent.model);
+  }
+  return args;
+}
+
+/**
+ * Wrap the user prompt with an optional system prompt prefix.
+ *
+ * Opencode's `run` subcommand has no `--system-prompt` flag, so
+ *  prepends the system prompt to the user message with a
+ * separator, exactly as ported here.
+ *
+ * Verbatim from
+ * 
+ */
+export function wrapOpencodePrompt(
+  prompt: string,
+  systemPrompt: string | null | undefined,
+): string {
+  if (!systemPrompt) return prompt;
+  return `Instructions: ${systemPrompt}\n\n---\n\n${prompt}`;
+}

package/src/backends/opencode/auth.ts

@@ -0,0 +1,53 @@
+/**
+ * Auth env + create-time validation for the opencode backend.
+ *
+ * Opencode is multi-provider: it reads `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
+ * and other provider-specific env vars at startup and routes model calls
+ * based on the `provider/model` prefix in the `--model` flag. We forward
+ * every provider key we know about; opencode picks the right one based on
+ * the agent's model.
+ *
+ * Opencode refuses `sk-ant-oat*` OAuth tokens per Anthropic ToS. See
+ * 
+ * — opencode provider only forwards `ANTHROPIC_API_KEY`
+ * and warns on OAuth tokens. We enforce the "at least one provider key"
+ * invariant at agent create time (and belt-and-braces at first turn) so
+ * the user doesn't discover the mismatch inside an opaque opencode error
+ * stream.
+ *
+ * Spike (2026-04-10) verified on a real sprite that opencode picks
+ * up `OPENAI_API_KEY` as an env var without any config file.
+ */
+import { getConfig } from "../../config";
+
+export function buildOpencodeAuthEnv(): Record<string, string> {
+  const cfg = getConfig();
+  const env: Record<string, string> = {};
+  if (cfg.anthropicApiKey) {
+    env.ANTHROPIC_API_KEY = cfg.anthropicApiKey;
+  }
+  if (cfg.openAiApiKey) {
+    env.OPENAI_API_KEY = cfg.openAiApiKey;
+  }
+  if (cfg.claudeToken && !cfg.anthropicApiKey) {
+    console.warn(
+      "[opencode] CLAUDE_CODE_OAUTH_TOKEN cannot drive opencode — set ANTHROPIC_API_KEY",
+    );
+  }
+  return env;
+}
+
+/**
+ * Returns null if opencode can run with the current config, or an error
+ * message if it can't. Used both at agent create time (`validateAgentCreation`
+ * hook) and at first-turn time (`validateRuntime` hook).
+ *
+ * Opencode is multi-provider so we accept either a valid Anthropic key or
+ * an OpenAI key. The agent's `model` field is still `provider/model` shaped
+ * (e.g. `openai/gpt-4o-mini`) and opencode routes based on the prefix.
+ */
+export function validateOpencodeRuntime(): string | null {
+  const cfg = getConfig();
+  if (cfg.anthropicApiKey || cfg.openAiApiKey) return null;
+  return "opencode backend requires at least one provider key: ANTHROPIC_API_KEY or OPENAI_API_KEY (opencode does not accept sk-ant-oat OAuth tokens per Anthropic ToS)";
+}

package/src/backends/opencode/index.ts

@@ -0,0 +1,70 @@
+/**
+ * Opencode backend: drives sst/opencode-ai's `opencode run` on sprites.dev
+ * containers.
+ *
+ * Ported from
+ * 
+ * (the  opencode provider), adapted for our sprite-only
+ * execution model. Opencompletions only ran opencode in its local backend;
+ * this adapter is the first time opencode runs inside a sprites.dev sprite,
+ * so the wrapper script + install flow are new (see wrapper-script.ts and
+ * setup.ts).
+ *
+ * Custom tool re-entry (the stream-json user frame path claude uses) is NOT
+ * supported by opencode — `opencode run` has no equivalent input format.
+ * 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 { buildOpencodeArgs } from "./args";
+import { buildOpencodeAuthEnv, validateOpencodeRuntime } from "./auth";
+import { buildOpencodeMcpEnv } from "./mcp";
+import { createOpencodeTranslator } from "./translator";
+import { OPENCODE_WRAPPER_PATH, installOpencodeWrapper } from "./wrapper-script";
+import { prepareOpencodeOnSprite } from "./setup";
+
+function buildTurn(input: BuildTurnInput): BuildTurnResult {
+  const { agent, backendSessionId, promptText, toolResults } = input;
+
+  if (toolResults.length > 0) {
+    throw new ApiError(
+      400,
+      "invalid_request_error",
+      "opencode backend does not support user.custom_tool_result re-entry in v1",
+    );
+  }
+
+  const argv = buildOpencodeArgs({ agent, backendSessionId });
+  const wrappedPrompt = wrapPromptWithSystem(promptText, agent.system);
+  const env = {
+    ...buildOpencodeAuthEnv(),
+    ...buildOpencodeMcpEnv(agent),
+  };
+  // stdin is the raw wrapped prompt — the driver prepends the env block.
+  // The opencode wrapper script captures this via PROMPT=$(cat) and
+  // re-passes it to `opencode` as a trailing positional argv.
+  return { argv, env, stdin: wrappedPrompt };
+}
+
+export const opencodeBackend: Backend = {
+  name: "opencode",
+  wrapperPath: OPENCODE_WRAPPER_PATH,
+  buildTurn,
+  createTranslator: (opts: TranslatorOptions) => createOpencodeTranslator(opts),
+  prepareOnSprite: (name, provider) => prepareOpencodeOnSprite(name, provider),
+
+  validateRuntime: validateOpencodeRuntime,
+};
+
+// Re-exports for tests and other modules
+export {
+  buildOpencodeArgs,
+  buildOpencodeAuthEnv,
+  buildOpencodeMcpEnv,
+  createOpencodeTranslator,
+  installOpencodeWrapper,
+  prepareOpencodeOnSprite,
+  OPENCODE_WRAPPER_PATH,
+};

package/src/backends/opencode/mcp.ts

@@ -0,0 +1,67 @@
+/**
+ * MCP config translation for opencode.
+ *
+ * Opencode loads its MCP config from the `OPENCODE_CONFIG_CONTENT` env var
+ * (not from a `--mcp-config` CLI flag). The JSON shape is slightly
+ * different from claude's:
+ *
+ *   Claude:                 Opencode:
+ *   type: "stdio"     --->  type: "local", command: [cmd, ...args]
+ *   type: "http"      --->  type: "remote"
+ *   type: "sse"       --->  type: "remote"
+ *
+ * Ported verbatim from
+ * 
+ */
+import type { Agent, McpServerConfig } from "../../types";
+
+/** Opencode's MCP server config shape (distinct from claude's). */
+export interface OpencodeMcpServer {
+  type?: "local" | "remote";
+  url?: string;
+  command?: string | string[];
+  headers?: Record<string, string>;
+  env?: Record<string, string>;
+}
+
+export function mcpConfigToOpencode(
+  mcpConfig: Record<string, McpServerConfig>,
+): Record<string, OpencodeMcpServer> {
+  const mcp: Record<string, OpencodeMcpServer> = {};
+
+  for (const [name, server] of Object.entries(mcpConfig)) {
+    const entry: OpencodeMcpServer = {
+      url: server.url,
+      headers: server.headers,
+      env: server.env,
+    };
+
+    if (server.type === "stdio") {
+      entry.type = "local";
+      // stdio uses command:string + args:array; opencode wants command:array
+      if (typeof server.command === "string") {
+        entry.command = [server.command, ...(server.args || [])];
+      } else if (Array.isArray(server.command)) {
+        entry.command = [...server.command, ...(server.args || [])];
+      }
+    } else if (server.type === "http" || server.type === "sse") {
+      entry.type = "remote";
+    }
+
+    mcp[name] = entry;
+  }
+
+  return mcp;
+}
+
+/**
+ * Return env vars that carry the agent's MCP config to opencode.
+ * Returns an empty map if the agent has no MCP servers.
+ */
+export function buildOpencodeMcpEnv(agent: Agent): Record<string, string> {
+  if (!agent.mcp_servers || Object.keys(agent.mcp_servers).length === 0) {
+    return {};
+  }
+  const opencodeMcp = mcpConfigToOpencode(agent.mcp_servers);
+  return { OPENCODE_CONFIG_CONTENT: JSON.stringify({ mcp: opencodeMcp }) };
+}

package/src/backends/opencode/setup.ts

@@ -0,0 +1,54 @@
+/**
+ * Install opencode on a freshly-created sprite.
+ *
+ * Idempotent via a sentinel file at OPENCODE_INSTALLED_SENTINEL. First call
+ * takes ~10 seconds on sprites.dev's base image.
+ * Subsequent calls for the same sprite are instant (sentinel short-circuit).
+ *
+ * findings:
+ * - sprites.dev base image has node v22.20.0 pre-installed via nvm at
+ *   `/.sprite/languages/node/nvm/versions/node/v22.20.0/`
+ * - `npm install -g opencode-ai` succeeds in 9s and installs opencode-ai@1.4.1
+ * - npm creates the symlink `<prefix>/bin/opencode` but that dir is NOT on
+ *   the default PATH (only `/.sprite/bin` is)
+ * - Workaround: `ln -sf $(npm config get prefix)/bin/opencode /usr/local/bin/opencode`
+ *   works without sudo and makes `opencode` directly invokable as
+ *   `/usr/local/bin/opencode` (which IS on PATH)
+ */
+import type { ContainerProvider } from "../../providers/types";
+import { installOpencodeWrapper } from "./wrapper-script";
+
+// Use $HOME-relative sentinel so it works on any container runtime
+// (sprites.dev HOME=/home/sprite, Docker/Apple HOME=/root or /home/node)
+const SENTINEL_NAME = ".claude-agents-opencode-installed";
+
+export async function prepareOpencodeOnSprite(spriteName: string, provider: ContainerProvider): Promise<void> {
+  await installOpencodeWrapper(spriteName, provider);
+
+  // Install opencode binary, sentinel-guarded for idempotency.
+  // Uses /usr/local/bin/opencode for verification (not `which`) because
+  // some container exec contexts have a minimal PATH that doesn't include
+  // /usr/local/bin even though the binary is there.
+  const script = [
+    "set -euo pipefail",
+    `SENTINEL="$HOME/${SENTINEL_NAME}"`,
+    'if [ -f "$SENTINEL" ]; then exit 0; fi',
+    "npm install -g opencode-ai",
+    "PREFIX=$(npm config get prefix)",
+    // Only symlink if npm prefix differs from /usr/local — otherwise the
+    // symlink overwrites npm's existing binary with a circular self-reference.
+    // This happens on Docker/Apple containers where PREFIX=/usr/local.
+    'if [ "$PREFIX" != "/usr/local" ]; then ln -sf "$PREFIX/bin/opencode" /usr/local/bin/opencode; fi',
+    '/usr/local/bin/opencode --version || $PREFIX/bin/opencode --version',
+    'touch "$SENTINEL"',
+  ].join(" && ");
+
+  const result = await provider.exec(spriteName, ["bash", "-c", script], {
+    timeoutMs: 5 * 60_000, // 5 minutes — cold install typically <30s but leave headroom
+  });
+  if (result.exit_code !== 0) {
+    throw new Error(
+      `opencode install failed (${result.exit_code}): ${result.stderr.slice(0, 500)}`,
+    );
+  }
+}