@agentstep/agent-sdk 0.1.0

package/src/sprite/lifecycle.ts

@@ -0,0 +1,339 @@
+/**
+ * Session-scoped sprite lifecycle.
+ *
+ * - Sprites are reserved **lazily** on the first user.message, not at
+ *   `POST /v1/sessions` time. This keeps session creation fast and decoupled
+ *   from sprite provisioning latency.
+ * - Each session is pinned 1:1 to a sprite for its lifetime. No rebalancing.
+ * - Park/restore as originally planned is infeasible: spike S2 proved
+ *   sprites.dev checkpoints are per-sprite only (no cross-sprite restore)
+ *   and there is no stopSprite/suspendSprite API. The correct M5 model is
+ *   idle eviction — see `lib/sessions/sweeper.ts`.
+ * - Orphan reconciliation runs on startup and periodically from the sweeper.
+ */
+import { createSprite, deleteSprite, listSprites } from "./client";
+import * as pool from "./pool";
+import { installClaudeWrapper } from "../backends/claude/wrapper-script";
+import { resolveBackend } from "../backends/registry";
+import { getAgent } from "../db/agents";
+import { getEnvironment, getEnvironmentRow } from "../db/environments";
+import {
+  getSession,
+  getSessionRow,
+  setSessionSprite,
+} from "../db/sessions";
+import { appendEvent } from "../sessions/bus";
+import { getConfig } from "../config";
+import { ApiError } from "../errors";
+import { nowMs } from "../util/clock";
+import { resolveContainerProvider } from "../providers/registry";
+import { dockerProvider } from "../providers/docker";
+import { getVault, listEntries } from "../db/vaults";
+import type { SessionResource } from "../types";
+
+const SPRITE_NAME_PREFIX = "ca-sess-";
+
+function deriveSpriteName(sessionId: string): string {
+  // Stable prefix + ULID tail, lowercased (sprites.dev requires lowercase names).
+  return `${SPRITE_NAME_PREFIX}${sessionId.replace(/^sess_/, "").toLowerCase()}`;
+}
+
+/**
+ * Acquire a sprite for the session if one is not already bound. Called
+ * from the driver on the first turn (not from the session create route).
+ *
+ * Runs the agent's backend-specific `prepareOnSprite` hook after the sprite
+ * is created. For claude this is a sub-second wrapper install; for opencode
+ * it's a ~10-second npm install + symlink.
+ *
+ * For backends with non-trivial prep time, emits
+ * `span.environment_setup_{start,end}` events so streaming clients can see
+ * the delay isn't a hang. Claude's prep is fast enough that we skip the
+ * spans to avoid noise.
+ */
+export async function acquireForFirstTurn(sessionId: string): Promise<string> {
+  const row = getSessionRow(sessionId);
+  if (!row) throw new ApiError(404, "not_found_error", `session not found: ${sessionId}`);
+  if (row.sprite_name) return row.sprite_name;
+
+  const env = getEnvironmentRow(row.environment_id);
+  if (!env) throw new ApiError(404, "not_found_error", "environment not found");
+  if (env.state !== "ready") {
+    throw new ApiError(
+      400,
+      "invalid_request_error",
+      `environment is not ready (state=${env.state})`,
+    );
+  }
+
+  if (pool.countInEnv(env.id) >= getConfig().maxSpritesPerEnv) {
+    throw new ApiError(503, "server_busy", "env sprite pool exhausted");
+  }
+
+  const agent = getAgent(row.agent_id, row.agent_version);
+  if (!agent) {
+    throw new ApiError(404, "not_found_error", "agent not found for session");
+  }
+  const backend = resolveBackend(agent.backend);
+
+  // Resolve the container provider from the environment config.
+  // Defaults to "sprites" for backward compatibility.
+  const envObj = getEnvironment(row.environment_id);
+  const provider = await resolveContainerProvider(envObj?.config?.provider);
+
+  // Pre-flight: re-check provider availability (may have changed since env creation)
+  if (provider.checkAvailability) {
+    const result = await provider.checkAvailability();
+    if (!result.available) {
+      throw new Error(`provider ${provider.name} is not available: ${result.message}`);
+    }
+  }
+
+  const name = deriveSpriteName(sessionId);
+  await provider.create({ name });
+
+  // Backends with slow prep (e.g. opencode's npm install) bracket the work
+  // with span events so the client sees something on the event stream
+  // rather than a minute of silence. Non-spec event type — clients that
+  // don't recognize it should drop it silently.
+  const needsSlowPrep = backend.name !== "claude";
+  if (needsSlowPrep) {
+    appendEvent(sessionId, {
+      type: "span.environment_setup_start",
+      payload: { backend: backend.name },
+      origin: "server",
+      processedAt: nowMs(),
+    });
+  }
+
+  try {
+    await backend.prepareOnSprite(name, provider);
+
+    // Install custom tool bridge if the agent has custom tools or threads_enabled (claude backend only)
+    if (agent.backend === "claude") {
+      const customTools = agent.tools.filter(
+        (t): t is import("../types").CustomTool => t.type === "custom",
+      );
+      // If threads are enabled, add spawn_agent as a synthetic custom tool
+      const allBridgeTools = [...customTools];
+      if (agent.threads_enabled) {
+        allBridgeTools.push({
+          type: "custom",
+          name: "spawn_agent",
+          description: "Spawn a sub-agent to handle a task. Returns the sub-agent's response.",
+          input_schema: {
+            type: "object",
+            properties: {
+              agent_id: { type: "string", description: "ID of the agent to spawn" },
+              prompt: { type: "string", description: "Task for the sub-agent" },
+            },
+            required: ["agent_id", "prompt"],
+          },
+        });
+      }
+      if (allBridgeTools.length > 0) {
+        const { installToolBridge } = await import("../backends/claude/index");
+        await installToolBridge(name, allBridgeTools, provider);
+      }
+
+      // Install permission hook if confirmation_mode is enabled
+      if (agent.confirmation_mode) {
+        const { installPermissionHook } = await import("../backends/claude/index");
+        await installPermissionHook(name, provider);
+      }
+    }
+  } catch (err) {
+    await provider.delete(name).catch(() => {});
+    throw err;
+  }
+
+  if (needsSlowPrep) {
+    appendEvent(sessionId, {
+      type: "span.environment_setup_end",
+      payload: { backend: backend.name },
+      origin: "server",
+      processedAt: nowMs(),
+    });
+  }
+
+  // Provision resources into the container if the session has any
+  const session = getSession(sessionId);
+  if (session?.resources && session.resources.length > 0) {
+    await provisionResources(name, session.resources, provider);
+  }
+
+  // Provision vault data into the container if the session has vault_ids
+  if (session?.vault_ids && session.vault_ids.length > 0) {
+    await provisionVaults(name, session.vault_ids, provider);
+  }
+
+  pool.register({
+    spriteName: name,
+    envId: env.id,
+    sessionId,
+    createdAt: nowMs(),
+  });
+  setSessionSprite(sessionId, name);
+  return name;
+}
+
+/**
+ * Download/write resources into /tmp/resources/ in the container.
+ * URIs are fetched via global fetch; text resources are written directly.
+ */
+async function provisionResources(
+  spriteName: string,
+  resources: SessionResource[],
+  provider: import("../providers/types").ContainerProvider,
+): Promise<void> {
+  await provider.exec(spriteName, ["mkdir", "-p", "/tmp/resources"]);
+
+  for (let i = 0; i < resources.length; i++) {
+    const r = resources[i];
+    const filename = `/tmp/resources/resource_${i}`;
+
+    if (r.type === "uri" && r.uri) {
+      const MAX_RESOURCE_BYTES = 50 * 1024 * 1024; // 50 MB
+      try {
+        const resp = await fetch(r.uri, { signal: AbortSignal.timeout(30000) });
+        if (!resp.ok) {
+          console.warn(`[lifecycle] failed to fetch resource ${r.uri}: ${resp.status}`);
+          continue;
+        }
+        const contentLength = resp.headers.get("Content-Length");
+        if (contentLength && parseInt(contentLength, 10) > MAX_RESOURCE_BYTES) {
+          console.warn(`[lifecycle] skipping resource ${r.uri}: Content-Length ${contentLength} exceeds 50 MB limit`);
+          continue;
+        }
+        const content = await resp.text();
+        if (Buffer.byteLength(content, "utf8") > MAX_RESOURCE_BYTES) {
+          console.warn(`[lifecycle] skipping resource ${r.uri}: body size exceeds 50 MB limit`);
+          continue;
+        }
+        await provider.exec(spriteName, ["bash", "-c", `cat > ${filename}`], { stdin: content });
+      } catch (err) {
+        console.warn(`[lifecycle] failed to provision URI resource ${r.uri}:`, err);
+      }
+    } else if (r.type === "text" && r.content) {
+      try {
+        await provider.exec(spriteName, ["bash", "-c", `cat > ${filename}`], { stdin: r.content });
+      } catch (err) {
+        console.warn(`[lifecycle] failed to provision text resource:`, err);
+      }
+    }
+  }
+}
+
+/**
+ * Export vault entries as JSON files into /tmp/vaults/{vault_id}.json in the
+ * container. Each file contains `{entries: [{key, value}, ...]}`.
+ */
+async function provisionVaults(
+  spriteName: string,
+  vaultIds: string[],
+  provider: import("../providers/types").ContainerProvider,
+): Promise<void> {
+  await provider.exec(spriteName, ["mkdir", "-p", "/tmp/vaults"]);
+
+  for (const vaultId of vaultIds) {
+    const vault = getVault(vaultId);
+    if (!vault) {
+      console.warn(`[lifecycle] vault not found: ${vaultId}, skipping`);
+      continue;
+    }
+    const entries = listEntries(vaultId);
+    const json = JSON.stringify({ vault_id: vaultId, name: vault.name, entries });
+    try {
+      await provider.exec(
+        spriteName,
+        ["bash", "-c", `cat > /tmp/vaults/${vaultId}.json`],
+        { stdin: json },
+      );
+    } catch (err) {
+      console.warn(`[lifecycle] failed to provision vault ${vaultId}:`, err);
+    }
+  }
+}
+
+// Re-export for test seeds and env setup that still use the claude wrapper path
+export { installClaudeWrapper };
+
+/**
+ * Release and delete the sprite bound to this session. Best-effort — logs
+ * failures but does not throw.
+ */
+export async function releaseSession(sessionId: string): Promise<void> {
+  const entry = pool.unregister(sessionId);
+  const row = getSessionRow(sessionId);
+  const name = entry?.spriteName ?? row?.sprite_name ?? null;
+  if (name) {
+    // Resolve the provider from the session's environment config
+    const envObj = row ? getEnvironment(row.environment_id) : null;
+    const provider = await resolveContainerProvider(envObj?.config?.provider);
+    await provider.delete(name).catch((err: unknown) => {
+      console.warn(`releaseSession: failed to delete container ${name}:`, err);
+    });
+  }
+  if (row?.sprite_name) setSessionSprite(sessionId, null);
+}
+
+/**
+ * Reconcile orphaned sprites. Compares sprites.dev's fleet against our
+ * sessions table and deletes anything with our prefix that has no active
+ * session. Run on startup and on a 1h interval.
+ */
+export async function reconcileOrphans(): Promise<{ deleted: number; kept: number }> {
+  let deleted = 0;
+  let kept = 0;
+
+  const liveNames = new Set(
+    pool.allSessionSprites().map((e) => e.spriteName).filter(Boolean),
+  );
+
+  let token: string | undefined;
+  for (;;) {
+    const res = await listSprites({
+      prefix: SPRITE_NAME_PREFIX,
+      max_results: 100,
+      continuation_token: token,
+    });
+    for (const s of res.sprites) {
+      if (liveNames.has(s.name)) {
+        kept++;
+      } else {
+        await deleteSprite(s.name).catch(() => {});
+        deleted++;
+      }
+    }
+    if (!res.has_more) break;
+    token = res.next_continuation_token ?? undefined;
+    if (!token) break;
+  }
+  return { deleted, kept };
+}
+
+/**
+ * Reconcile orphaned Docker containers. Same logic as reconcileOrphans
+ * but uses the Docker provider's list method (`docker ps --filter`).
+ * Run alongside reconcileOrphans on startup and on a 1h interval.
+ */
+export async function reconcileDockerOrphans(): Promise<{ deleted: number; kept: number }> {
+  let deleted = 0;
+  let kept = 0;
+
+  const liveNames = new Set(
+    pool.allSessionSprites().map((e) => e.spriteName).filter(Boolean),
+  );
+
+  const containers = await dockerProvider.list({ prefix: SPRITE_NAME_PREFIX });
+  for (const c of containers) {
+    if (liveNames.has(c.name)) {
+      kept++;
+    } else {
+      await dockerProvider.delete(c.name).catch(() => {});
+      deleted++;
+    }
+  }
+  return { deleted, kept };
+}
+

package/src/sprite/pool.ts

@@ -0,0 +1,65 @@
+/**
+ * Per-environment sprite pool + session-to-sprite affinity.
+ *
+ * Sessions are pinned 1:1 to a sprite for their entire lifetime. The pool
+ * tracks which sprites are attached to which sessions so we can enforce
+ * `max_sprites_per_env` and clean up on session delete.
+ *
+ * Pattern inspired by
+ * 
+ */
+export interface SpriteEntry {
+  spriteName: string;
+  envId: string;
+  sessionId: string;
+  createdAt: number;
+}
+
+type PoolState = {
+  byEnv: Map<string, SpriteEntry[]>;
+  bySession: Map<string, SpriteEntry>;
+};
+
+type GlobalPool = typeof globalThis & { __caPool?: PoolState };
+const g = globalThis as GlobalPool;
+
+function state(): PoolState {
+  if (!g.__caPool) {
+    g.__caPool = { byEnv: new Map(), bySession: new Map() };
+  }
+  return g.__caPool;
+}
+
+export function register(entry: SpriteEntry): void {
+  const s = state();
+  const list = s.byEnv.get(entry.envId) ?? [];
+  list.push(entry);
+  s.byEnv.set(entry.envId, list);
+  s.bySession.set(entry.sessionId, entry);
+}
+
+export function getBySession(sessionId: string): SpriteEntry | null {
+  return state().bySession.get(sessionId) ?? null;
+}
+
+export function countInEnv(envId: string): number {
+  return state().byEnv.get(envId)?.length ?? 0;
+}
+
+export function unregister(sessionId: string): SpriteEntry | null {
+  const s = state();
+  const entry = s.bySession.get(sessionId);
+  if (!entry) return null;
+  s.bySession.delete(sessionId);
+  const list = s.byEnv.get(entry.envId);
+  if (list) {
+    const idx = list.findIndex((e) => e.sessionId === sessionId);
+    if (idx >= 0) list.splice(idx, 1);
+    if (list.length === 0) s.byEnv.delete(entry.envId);
+  }
+  return entry;
+}
+
+export function allSessionSprites(): SpriteEntry[] {
+  return Array.from(state().bySession.values());
+}

package/src/sprite/setup.ts

@@ -0,0 +1,159 @@
+/**
+ * Async environment setup: package install + checkpoint.
+ *
+ * Runs in the background after `POST /v1/environments` returns. Creates a
+ * fresh template sprite, installs packages per `env.config.packages`, writes
+ * an idempotency sentinel, creates a sprites.dev checkpoint, persists the
+ * checkpoint id on the environment row, deletes the template sprite, and
+ * flips `environments.state` to `ready` (or `failed` on error).
+ *
+ * Sentinel idempotency pattern from
+ * 
+ *
+ * NOTE: the sentinel path assumes claude runs as user `sprite` with
+ * `HOME=/home/sprite`. Spike S1 validates this and may change the path.
+ */
+import crypto from "node:crypto";
+import {
+  createSprite,
+  deleteSprite,
+  httpExec,
+  createCheckpoint,
+} from "./client";
+import {
+  CLAUDE_WRAPPER_PATH as WRAPPER_PATH,
+  installClaudeWrapper as installWrapper,
+} from "../backends/claude/wrapper-script";
+import {
+  getEnvironmentRow,
+  updateEnvironmentCheckpoint,
+  updateEnvironmentState,
+} from "../db/environments";
+import type { EnvironmentConfig } from "../types";
+import type { ContainerProvider } from "../providers/types";
+import { resolveContainerProvider } from "../providers/registry";
+import { newId } from "../util/ids";
+
+const SENTINEL_DIR = "/home/sprite";
+
+function hashPackages(packages: EnvironmentConfig["packages"]): string {
+  const canonical = JSON.stringify(packages ?? {}, Object.keys(packages ?? {}).sort());
+  return crypto.createHash("sha256").update(canonical).digest("hex").slice(0, 16);
+}
+
+function buildInstallCommands(packages: EnvironmentConfig["packages"]): string[] {
+  if (!packages) return [];
+  const cmds: string[] = [];
+  // Alphabetical order to match Managed Agents spec behavior.
+  if (packages.apt?.length) {
+    cmds.push(`apt-get update -qq && apt-get install -y -qq ${packages.apt.map(shellEscape).join(" ")}`);
+  }
+  if (packages.cargo?.length) {
+    cmds.push(`cargo install ${packages.cargo.map(shellEscape).join(" ")}`);
+  }
+  if (packages.gem?.length) {
+    cmds.push(`gem install ${packages.gem.map(shellEscape).join(" ")}`);
+  }
+  if (packages.go?.length) {
+    for (const pkg of packages.go) cmds.push(`go install ${shellEscape(pkg)}`);
+  }
+  if (packages.npm?.length) {
+    cmds.push(`npm install -g ${packages.npm.map(shellEscape).join(" ")}`);
+  }
+  if (packages.pip?.length) {
+    cmds.push(`pip install ${packages.pip.map(shellEscape).join(" ")}`);
+  }
+  return cmds;
+}
+
+function shellEscape(s: string): string {
+  return `'${s.replace(/'/g, "'\\''")}'`;
+}
+
+/**
+ * Prepare a freshly-created sprite: install the wrapper script and run
+ * the environment's setup commands. Returns when the sentinel is in place.
+ */
+export async function prepareSprite(
+  spriteName: string,
+  packages: EnvironmentConfig["packages"],
+  provider?: ContainerProvider,
+): Promise<void> {
+  const p = provider ?? await resolveContainerProvider();
+  await installWrapper(spriteName, p);
+
+  const hash = hashPackages(packages);
+  const sentinel = `${SENTINEL_DIR}/.claude-agents-setup-${hash}`;
+  const installCmds = buildInstallCommands(packages);
+  if (installCmds.length === 0) {
+    await p.exec(spriteName, ["bash", "-c", `touch ${sentinel}`]);
+    return;
+  }
+
+  const script = [
+    "set -euo pipefail",
+    `if [ -f ${sentinel} ]; then exit 0; fi`,
+    ...installCmds,
+    `touch ${sentinel}`,
+  ].join(" && ");
+
+  const result = await p.exec(spriteName, ["bash", "-c", script], {
+    timeoutMs: 30 * 60_000,
+  });
+  if (result.exit_code !== 0) {
+    throw new Error(`setup failed (${result.exit_code}): ${result.stderr.slice(0, 500)}`);
+  }
+}
+
+/**
+ * Kick off env setup in the background. Called from `POST /v1/environments`
+ * after the response has been sent.
+ */
+export function kickoffEnvironmentSetup(envId: string): void {
+  // Fire-and-forget. Errors are captured onto the environment row.
+  runEnvironmentSetup(envId).catch((err: unknown) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`[env ${envId}] setup failed:`, msg);
+    try {
+      updateEnvironmentState(envId, "failed", msg);
+    } catch (dbErr) {
+      console.error(`[env ${envId}] failed to record setup failure:`, dbErr);
+    }
+  });
+}
+
+async function runEnvironmentSetup(envId: string): Promise<void> {
+  const row = getEnvironmentRow(envId);
+  if (!row) throw new Error(`environment ${envId} not found`);
+  if (row.state === "ready") return;
+
+  const config = JSON.parse(row.config_json) as EnvironmentConfig;
+  const provider = await resolveContainerProvider(config.provider);
+  const hasPackages = config.packages && Object.values(config.packages).some((v) => v && v.length > 0);
+
+  if (!hasPackages) {
+    // No packages to install — env is ready immediately. Each session sprite
+    // will get the wrapper installed in lifecycle.acquireForFirstTurn().
+    updateEnvironmentState(envId, "ready", null);
+    return;
+  }
+
+  // With packages: create a template container, run installs, then mark ready.
+  // NOTE: sprites.dev checkpoints are per-sprite only, so we can't snapshot
+  // the template and restore onto session sprites. For now, packages are
+  // re-installed per session sprite (slow). M5 will optimize with a sprite
+  // pool or alternative approach.
+  const templateName = `ca-env-tpl-${newId("env").slice(4, 16).toLowerCase()}`;
+  await provider.create({ name: templateName });
+  try {
+    await prepareSprite(templateName, config.packages, provider);
+    // Record that setup succeeded but no checkpoint to share.
+    updateEnvironmentState(envId, "ready", null);
+  } catch (err) {
+    throw err;
+  } finally {
+    await provider.delete(templateName).catch(() => {});
+  }
+}
+
+export { WRAPPER_PATH, SENTINEL_DIR };

package/src/state.ts

@@ -0,0 +1,61 @@
+/**
+ * Global mutable runtime state — HMR-safe via globalThis so Next.js dev
+ * reloads don't duplicate maps.
+ *
+ * Pattern from
+ * 
+ */
+
+export interface InFlightRun {
+  sessionId: string;
+  controller: AbortController;
+  startedAt: number;
+}
+
+export type TurnInput =
+  | { kind: "text"; eventId: string; text: string }
+  | {
+      kind: "tool_result";
+      eventId: string;
+      custom_tool_use_id: string;
+      content: unknown[];
+    };
+
+export interface PendingUserInput {
+  sessionId: string;
+  input: TurnInput;
+}
+
+type RuntimeState = {
+  inFlightRuns: Map<string, InFlightRun>;
+  pendingUserInputs: Map<string, TurnInput[]>;
+};
+
+type GlobalState = typeof globalThis & {
+  __caRuntime?: RuntimeState;
+};
+
+export function getRuntime(): RuntimeState {
+  const g = globalThis as GlobalState;
+  if (!g.__caRuntime) {
+    g.__caRuntime = {
+      inFlightRuns: new Map(),
+      pendingUserInputs: new Map(),
+    };
+  }
+  return g.__caRuntime;
+}
+
+export function pushPendingUserInput(input: PendingUserInput): void {
+  const rt = getRuntime();
+  const list = rt.pendingUserInputs.get(input.sessionId) ?? [];
+  list.push(input.input);
+  rt.pendingUserInputs.set(input.sessionId, list);
+}
+
+export function drainPendingUserInputs(sessionId: string): TurnInput[] {
+  const rt = getRuntime();
+  const list = rt.pendingUserInputs.get(sessionId) ?? [];
+  rt.pendingUserInputs.delete(sessionId);
+  return list;
+}