@agentstep/agent-sdk 0.1.0

package/src/providers/podman.ts

@@ -0,0 +1,206 @@
+/**
+ * Podman container provider.
+ *
+ * Nearly identical to docker.ts — uses `podman` CLI instead of `docker`.
+ * Podman is a drop-in replacement for Docker with the same CLI surface,
+ * so the only difference is the binary name in spawn calls.
+ *
+ * Container lifecycle:
+ *   create → podman create --name {name} node:22 sleep infinity + podman start
+ *   exec   → podman exec -i {name} with stdin piped + stdout captured
+ *   delete → podman rm -f {name}
+ */
+import { spawn } from "node:child_process";
+import { Readable } from "node:stream";
+import type { ContainerProvider, ExecOptions, ExecSession } from "./types";
+
+const DEFAULT_IMAGE = process.env.PODMAN_IMAGE ?? "node:22";
+const CLI = "podman";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function podmanRun(
+  args: string[],
+  opts?: { stdin?: string; timeoutMs?: number },
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(CLI, args, { stdio: ["pipe", "pipe", "pipe"] });
+
+    let stdout = "";
+    let stderr = "";
+    proc.stdout?.on("data", (buf: Buffer) => { stdout += buf.toString(); });
+    proc.stderr?.on("data", (buf: Buffer) => { stderr += buf.toString(); });
+
+    if (opts?.stdin) {
+      proc.stdin?.write(opts.stdin);
+    }
+    proc.stdin?.end();
+
+    const timer = opts?.timeoutMs
+      ? setTimeout(() => {
+          proc.kill("SIGKILL");
+          reject(new Error(`${CLI} command timed out after ${opts.timeoutMs}ms`));
+        }, opts.timeoutMs)
+      : null;
+
+    proc.on("close", (code) => {
+      if (timer) clearTimeout(timer);
+      if (code !== 0) {
+        reject(new Error(`${CLI} ${args[0]} failed (${code}): ${stderr.trim()}`));
+      } else {
+        resolve(stdout);
+      }
+    });
+    proc.on("error", (err) => {
+      if (timer) clearTimeout(timer);
+      reject(err);
+    });
+  });
+}
+
+function podmanExecOneShot(
+  containerName: string,
+  argv: string[],
+  stdin?: string,
+  timeoutMs?: number,
+): Promise<{ stdout: string; stderr: string; exit_code: number }> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(CLI, ["exec", "-i", containerName, ...argv], {
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    proc.stdout?.on("data", (buf: Buffer) => { stdout += buf.toString(); });
+    proc.stderr?.on("data", (buf: Buffer) => { stderr += buf.toString(); });
+
+    if (stdin) proc.stdin?.write(stdin);
+    proc.stdin?.end();
+
+    const timer = timeoutMs
+      ? setTimeout(() => {
+          proc.kill("SIGKILL");
+          reject(new Error(`${CLI} exec timed out after ${timeoutMs}ms`));
+        }, timeoutMs)
+      : null;
+
+    proc.on("close", (code) => {
+      if (timer) clearTimeout(timer);
+      resolve({ stdout, stderr, exit_code: code ?? 1 });
+    });
+    proc.on("error", (err) => {
+      if (timer) clearTimeout(timer);
+      reject(err);
+    });
+  });
+}
+
+function podmanExecStreaming(
+  containerName: string,
+  opts: ExecOptions,
+): ExecSession {
+  const proc = spawn(CLI, ["exec", "-i", containerName, ...opts.argv], {
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+
+  if (opts.stdin) proc.stdin?.write(opts.stdin);
+  proc.stdin?.end();
+
+  const stdout = Readable.toWeb(proc.stdout!) as ReadableStream<Uint8Array>;
+
+  let exitResolve: (v: { code: number }) => void;
+  let exitReject: (e: unknown) => void;
+  const exit = new Promise<{ code: number }>((res, rej) => {
+    exitResolve = res;
+    exitReject = rej;
+  });
+
+  proc.on("close", (code) => exitResolve({ code: code ?? 0 }));
+  proc.on("error", (err) => exitReject(err));
+
+  let timer: NodeJS.Timeout | null = null;
+  if (opts.timeoutMs) {
+    timer = setTimeout(() => {
+      proc.kill("SIGKILL");
+      exitReject(new Error(`${CLI} exec timed out after ${opts.timeoutMs}ms`));
+    }, opts.timeoutMs);
+  }
+  exit.finally(() => { if (timer) clearTimeout(timer); });
+
+  if (opts.signal) {
+    if (opts.signal.aborted) {
+      proc.kill("SIGTERM");
+    } else {
+      opts.signal.addEventListener("abort", () => {
+        proc.kill("SIGTERM");
+        setTimeout(() => { if (!proc.killed) proc.kill("SIGKILL"); }, 3000);
+      });
+    }
+  }
+
+  return {
+    stdout,
+    exit,
+    async kill() {
+      proc.kill("SIGTERM");
+      setTimeout(() => { if (!proc.killed) proc.kill("SIGKILL"); }, 3000);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+
+export const podmanProvider: ContainerProvider = {
+  name: "podman",
+  stripControlChars: false,
+
+  async checkAvailability() {
+    try {
+      await podmanRun(["version", "--format", "{{.Server.Version}}"], { timeoutMs: 3000 });
+      return { available: true };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes("ENOENT")) {
+        return { available: false, message: "Podman CLI is not installed. Install it from https://podman.io/docs/installation" };
+      }
+      return { available: false, message: `Podman is not running or not accessible: ${msg}` };
+    }
+  },
+
+  async create({ name }) {
+    await podmanRun(["create", "--name", name, DEFAULT_IMAGE, "sleep", "infinity"]);
+    await podmanRun(["start", name]);
+  },
+
+  async delete(name) {
+    await podmanRun(["rm", "-f", name]).catch(() => {});
+  },
+
+  async list(opts) {
+    try {
+      const out = await podmanRun([
+        "ps",
+        "-a",
+        "--filter",
+        `name=${opts?.prefix ?? "ca-sess-"}`,
+        "--format",
+        "{{.Names}}",
+      ]);
+      return out.trim().split("\n").filter(Boolean).map((name) => ({ name }));
+    } catch {
+      return [];
+    }
+  },
+
+  async exec(name, argv, opts) {
+    return podmanExecOneShot(name, argv, opts?.stdin, opts?.timeoutMs);
+  },
+
+  startExec(name, opts) {
+    return Promise.resolve(podmanExecStreaming(name, opts));
+  },
+};

package/src/providers/registry.ts

@@ -0,0 +1,28 @@
+/**
+ * Container provider registry.
+ *
+ * Resolves a provider by name (from environment config). Defaults to
+ * sprites.dev for backward compatibility. Uses lazy dynamic imports
+ * so optional SDK-based providers (e2b, vercel) only load when selected.
+ */
+import type { ContainerProvider, ProviderName } from "./types";
+
+const PROVIDERS: Record<ProviderName, () => Promise<ContainerProvider>> = {
+  sprites: async () => (await import("./sprites")).spritesProvider,
+  docker: async () => (await import("./docker")).dockerProvider,
+  apple: async () => (await import("./apple")).appleProvider,
+  podman: async () => (await import("./podman")).podmanProvider,
+  e2b: async () => (await import("./e2b")).e2bProvider,
+  vercel: async () => (await import("./vercel")).vercelProvider,
+  daytona: async () => (await import("./daytona")).daytonaProvider,
+  fly: async () => (await import("./fly")).flyProvider,
+  modal: async () => (await import("./modal")).modalProvider,
+};
+
+export async function resolveContainerProvider(
+  providerName?: string | null,
+): Promise<ContainerProvider> {
+  const key = (providerName ?? "sprites") as ProviderName;
+  const loader = PROVIDERS[key];
+  return loader ? loader() : PROVIDERS.sprites();
+}

package/src/providers/shared.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared utilities for container providers.
+ */
+
+/**
+ * Shell-escape a string for safe embedding in a bash command.
+ * Wraps in single quotes and escapes any embedded single quotes.
+ */
+export function shellEscape(s: string): string {
+  return `'${s.replace(/'/g, "'\\''")}'`;
+}

package/src/providers/sprites.ts

@@ -0,0 +1,55 @@
+/**
+ * Sprites.dev container provider.
+ *
+ * Wraps the existing `lib/sprite/client.ts` + `lib/sprite/exec.ts`
+ * functions behind the `ContainerProvider` interface. No logic changes —
+ * just delegation.
+ */
+import type { ContainerProvider } from "./types";
+import {
+  createSprite,
+  deleteSprite,
+  listSprites,
+  httpExec,
+} from "../sprite/client";
+import { startExec } from "../sprite/exec";
+
+export const spritesProvider: ContainerProvider = {
+  name: "sprites",
+  stripControlChars: true, // sprites.dev HTTP exec multiplexes stdout/stderr with control bytes
+
+  async checkAvailability() {
+    const { getConfig } = await import("../config/index");
+    const cfg = getConfig();
+    if (!cfg.spriteToken) {
+      return { available: false, message: "sprites.dev requires SPRITE_TOKEN to be set" };
+    }
+    return { available: true };
+  },
+
+  async create(opts) {
+    await createSprite(opts);
+  },
+
+  async delete(name) {
+    await deleteSprite(name);
+  },
+
+  async list(opts) {
+    const res = await listSprites({
+      prefix: opts?.prefix,
+      max_results: 100,
+    });
+    // Flatten to simple name array — sprites' paginated response is
+    // handled by the sprites-specific reconcileOrphans, not here.
+    return res.sprites.map((s) => ({ name: s.name }));
+  },
+
+  async exec(name, argv, opts) {
+    return httpExec(name, argv, opts);
+  },
+
+  startExec(name, opts) {
+    return startExec(name, opts);
+  },
+};

package/src/providers/types.ts

@@ -0,0 +1,73 @@
+/**
+ * Container provider abstraction.
+ *
+ * Both sprites.dev and Docker implement this interface. The driver,
+ * lifecycle, and backend setup code call these methods instead of
+ * directly using sprites.dev's REST API or Docker's CLI. The provider
+ * is selected per-environment via `EnvironmentConfig.provider`.
+ */
+
+export type ProviderName = "sprites" | "docker" | "apple" | "podman" | "e2b" | "vercel" | "daytona" | "fly" | "modal";
+
+export interface ExecOptions {
+  argv: string[];
+  stdin?: string;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}
+
+export interface ExecResult {
+  code: number;
+}
+
+export interface ExecSession {
+  /** Raw streamed stdout bytes */
+  stdout: ReadableStream<Uint8Array>;
+  /** Resolves when the process exits */
+  exit: Promise<ExecResult>;
+  /** Best-effort kill — aborts the process */
+  kill(): Promise<void>;
+}
+
+export interface AvailabilityResult {
+  available: boolean;
+  message?: string;
+}
+
+export interface ContainerProvider {
+  name: ProviderName;
+
+  /** Pre-flight check: is this provider usable right now?
+   *  Returns { available: true } or { available: false, message: "..." }.
+   *  Optional — providers that don't implement it are assumed available. */
+  checkAvailability?(): Promise<AvailabilityResult>;
+
+  /** Create and start a new container */
+  create(opts: { name: string }): Promise<void>;
+  /** Force-remove a container (best-effort, does not throw on missing) */
+  delete(name: string): Promise<void>;
+  /** List containers matching an optional prefix (flat, no pagination) */
+  list(opts?: { prefix?: string }): Promise<Array<{ name: string }>>;
+
+  /**
+   * One-shot execution: run argv in a container and wait for exit.
+   * Used by backend setup (install wrapper, install CLI, etc.)
+   */
+  exec(
+    name: string,
+    argv: string[],
+    opts?: { stdin?: string; timeoutMs?: number },
+  ): Promise<{ stdout: string; stderr: string; exit_code: number }>;
+
+  /**
+   * Streaming execution: run argv in a container and stream stdout.
+   * Used by the turn driver for CLI output.
+   */
+  startExec(name: string, opts: ExecOptions): Promise<ExecSession>;
+
+  /**
+   * Whether to strip control chars from stdout. True for sprites.dev
+   * (HTTP multiplexing framing bytes), false for Docker.
+   */
+  stripControlChars: boolean;
+}

package/src/providers/vercel.ts

@@ -0,0 +1,208 @@
+/**
+ * Vercel Sandbox provider.
+ *
+ * Uses the `@vercel/sandbox` npm package to create and manage cloud sandboxes.
+ * The SDK is optional — if not installed, a clear error is thrown on first use.
+ *
+ * Container lifecycle:
+ *   create → Sandbox.create({ runtime: 'node24' })
+ *   exec   → Write stdin to file, then sandbox.runCommand('bash', ['-c', ...])
+ *   delete → sandbox.stop()
+ *
+ * Env vars: VERCEL_TOKEN, VERCEL_TEAM_ID, VERCEL_PROJECT_ID
+ */
+import type { ContainerProvider, ExecOptions, ExecSession } from "./types";
+import { shellEscape } from "./shared";
+
+// Lazy-loaded SDK types
+type VercelSandbox = {
+  writeFiles(files: Record<string, string>): Promise<void>;
+  runCommand(
+    cmd: string,
+    args?: string[],
+    opts?: Record<string, unknown>,
+  ): Promise<{ exitCode: number; stdout: string; stderr: string }>;
+  stop(): Promise<void>;
+};
+
+type VercelSandboxClass = {
+  create(opts: {
+    runtime?: string;
+    token?: string;
+    teamId?: string;
+    projectId?: string;
+  }): Promise<VercelSandbox>;
+};
+
+let SandboxClass: VercelSandboxClass | null = null;
+
+async function loadSdk(): Promise<VercelSandboxClass> {
+  if (SandboxClass) return SandboxClass;
+  try {
+    // @ts-ignore — optional dependency, may not be installed
+    const mod = await import("@vercel/sandbox");
+    SandboxClass = (mod.Sandbox ?? mod.default?.Sandbox ?? mod.default) as VercelSandboxClass;
+    if (!SandboxClass?.create) {
+      throw new Error("Sandbox.create not found in @vercel/sandbox exports");
+    }
+    return SandboxClass;
+  } catch (err) {
+    if (
+      err instanceof Error &&
+      (err.message.includes("Cannot find module") ||
+        err.message.includes("MODULE_NOT_FOUND") ||
+        err.message.includes("ERR_MODULE_NOT_FOUND"))
+    ) {
+      throw new Error(
+        "Vercel provider requires the @vercel/sandbox package. Install it with: npm install @vercel/sandbox",
+      );
+    }
+    throw err;
+  }
+}
+
+// HMR-safe sandbox instance map
+type GlobalWithVercel = typeof globalThis & { __caVercelSandboxes?: Map<string, VercelSandbox> };
+const g = globalThis as GlobalWithVercel;
+if (!g.__caVercelSandboxes) g.__caVercelSandboxes = new Map();
+const sandboxes = g.__caVercelSandboxes;
+
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+
+export const vercelProvider: ContainerProvider = {
+  name: "vercel",
+  stripControlChars: false,
+
+  async checkAvailability() {
+    try { await loadSdk(); } catch {
+      return { available: false, message: "Vercel Sandbox requires the @vercel/sandbox package. Install with: npm install @vercel/sandbox" };
+    }
+    if (!process.env.VERCEL_TOKEN) {
+      return { available: false, message: "Vercel Sandbox requires VERCEL_TOKEN to be set" };
+    }
+    return { available: true };
+  },
+
+  async create({ name }) {
+    const Sandbox = await loadSdk();
+    const token = process.env.VERCEL_TOKEN;
+    if (!token) throw new Error("VERCEL_TOKEN environment variable is required");
+
+    const runtime = process.env.VERCEL_SANDBOX_RUNTIME ?? "node24";
+    const sandbox = await Sandbox.create({
+      runtime,
+      token,
+      teamId: process.env.VERCEL_TEAM_ID,
+      projectId: process.env.VERCEL_PROJECT_ID,
+    });
+    sandboxes.set(name, sandbox);
+  },
+
+  async delete(name) {
+    const sandbox = sandboxes.get(name);
+    if (!sandbox) return;
+    try {
+      await sandbox.stop();
+    } catch {
+      // Best-effort — sandbox may already be gone
+    }
+    sandboxes.delete(name);
+  },
+
+  async list(opts) {
+    // NOTE: @vercel/sandbox does not expose a listing API to enumerate running
+    // sandboxes server-side. After a server restart the in-memory map is empty,
+    // so previously-created sandboxes will not appear here. This is an accepted
+    // limitation — callers must handle missing containers gracefully (e.g.
+    // re-create on demand).
+    const prefix = opts?.prefix ?? "ca-sess-";
+    return Array.from(sandboxes.keys())
+      .filter((n) => n.startsWith(prefix))
+      .map((name) => ({ name }));
+  },
+
+  async exec(name, argv, opts) {
+    const sandbox = sandboxes.get(name);
+    if (!sandbox) throw new Error(`Vercel sandbox not found: ${name}`);
+
+    const cmd = argv.map((a) => shellEscape(a)).join(" ");
+
+    // Write stdin to a unique temp file if provided, then run cmd reading from it
+    if (opts?.stdin) {
+      const stdinPath = `/tmp/_stdin_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+      await sandbox.writeFiles({ [stdinPath]: opts.stdin });
+      const result = await sandbox.runCommand("bash", [
+        "-c",
+        `cat ${shellEscape(stdinPath)} | ${cmd} ; rm -f ${shellEscape(stdinPath)}`,
+      ]);
+      return {
+        stdout: result.stdout,
+        stderr: result.stderr,
+        exit_code: result.exitCode,
+      };
+    }
+
+    const result = await sandbox.runCommand("bash", ["-c", cmd]);
+    return {
+      stdout: result.stdout,
+      stderr: result.stderr,
+      exit_code: result.exitCode,
+    };
+  },
+
+  async startExec(name, opts) {
+    const sandbox = sandboxes.get(name);
+    if (!sandbox) throw new Error(`Vercel sandbox not found: ${name}`);
+
+    const cmd = opts.argv.map((a) => shellEscape(a)).join(" ");
+
+    // Write stdin to a unique temp file if provided
+    let stdinPath: string | undefined;
+    if (opts.stdin) {
+      stdinPath = `/tmp/_stdin_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+      await sandbox.writeFiles({ [stdinPath]: opts.stdin });
+    }
+
+    const fullCmd = stdinPath
+      ? `cat ${shellEscape(stdinPath)} | ${cmd} ; rm -f ${shellEscape(stdinPath)}`
+      : cmd;
+
+    const encoder = new TextEncoder();
+    let streamController: ReadableStreamDefaultController<Uint8Array>;
+
+    const stdout = new ReadableStream<Uint8Array>({
+      start(controller) {
+        streamController = controller;
+      },
+    });
+
+    const resultPromise = sandbox.runCommand("bash", ["-c", fullCmd]);
+
+    const exit = resultPromise.then((result) => {
+      try {
+        streamController.enqueue(encoder.encode(result.stdout));
+        streamController.close();
+      } catch {
+        // Already closed
+      }
+      return { code: result.exitCode };
+    }).catch((err) => {
+      try {
+        streamController.error(err);
+      } catch {
+        // Already closed
+      }
+      throw err;
+    });
+
+    return {
+      stdout,
+      exit,
+      async kill() {
+        // Vercel sandbox doesn't support killing individual commands
+      },
+    };
+  },
+};

package/src/proxy/forward.ts

@@ -0,0 +1,111 @@
+/**
+ * Forward a request to Anthropic's hosted Managed Agents API.
+ *
+ * Swaps the caller's local API key for the server's ANTHROPIC_API_KEY,
+ * adds the required `anthropic-beta` header, and pipes the response
+ * (including SSE streams) back to the client. Works for both JSON and
+ * streaming responses.
+ *
+ * This is the core of the "anthropic" proxy backend — no sprite, no CLI,
+ * no translator. Anthropic owns the resource IDs and handles all execution.
+ */
+import { getConfig } from "../config";
+import { ApiError } from "../errors";
+
+const ANTHROPIC_BASE = "https://api.anthropic.com";
+const BETA_HEADER = "managed-agents-2026-04-01";
+
+/**
+ * Forward a request to Anthropic. The caller is responsible for
+ * authenticating the user against the local API key table (via routeWrap)
+ * before calling this.
+ *
+ * @param request  The original incoming Request (used for method, signal,
+ *                 and body reading if opts.body is not provided)
+ * @param path     The MA API path (e.g. "/v1/agents" or "/v1/sessions/sess_123/events")
+ * @param opts.body Pre-read request body string. Required for POST routes
+ *                  that already consumed the body to inspect it (e.g. to
+ *                  check `body.backend`). If not provided and method is
+ *                  not GET, the body is read from `request.text()`.
+ */
+export async function forwardToAnthropic(
+  request: Request,
+  path: string,
+  opts?: { body?: string },
+): Promise<Response> {
+  const cfg = getConfig();
+  if (!cfg.anthropicApiKey) {
+    throw new ApiError(
+      500,
+      "server_error",
+      "ANTHROPIC_API_KEY is required for the anthropic proxy backend",
+    );
+  }
+
+  const url = new URL(path, ANTHROPIC_BASE);
+  // Preserve query string from the original request
+  const origUrl = new URL(request.url);
+  url.search = origUrl.search;
+
+  const headers = new Headers();
+  headers.set("x-api-key", cfg.anthropicApiKey);
+  headers.set("anthropic-beta", BETA_HEADER);
+
+  // Forward select headers from the original request
+  const ct = request.headers.get("content-type");
+  if (ct) headers.set("content-type", ct);
+  const lastId = request.headers.get("last-event-id");
+  if (lastId) headers.set("last-event-id", lastId);
+  const idem =
+    request.headers.get("idempotency-key") ||
+    request.headers.get("Idempotency-Key");
+  if (idem) headers.set("idempotency-key", idem);
+  const accept = request.headers.get("accept");
+  if (accept) headers.set("accept", accept);
+
+  // Determine request body
+  let body: string | undefined;
+  if (request.method !== "GET" && request.method !== "HEAD") {
+    body = opts?.body ?? (await request.text());
+  }
+
+  const res = await fetch(url.toString(), {
+    method: request.method,
+    headers,
+    body,
+    signal: request.signal,
+  });
+
+  // Pipe response back with original status + headers, stripping hop-by-hop
+  const HOP_BY_HOP = new Set([
+    "connection",
+    "keep-alive",
+    "transfer-encoding",
+    "te",
+    "trailer",
+    "upgrade",
+  ]);
+  const responseHeaders = new Headers();
+  for (const [k, v] of res.headers) {
+    if (!HOP_BY_HOP.has(k.toLowerCase())) {
+      responseHeaders.set(k, v);
+    }
+  }
+
+  return new Response(res.body, {
+    status: res.status,
+    headers: responseHeaders,
+  });
+}
+
+/**
+ * Validate that the anthropic proxy can run with the current config.
+ * Used at agent-create time and as a belt-and-braces check in the proxy.
+ */
+export function validateAnthropicProxy(): string | null {
+  const cfg = getConfig();
+  if (!cfg.anthropicApiKey) {
+    return "anthropic proxy backend requires ANTHROPIC_API_KEY to be set";
+  }
+  return null;
+}