@agentstep/agent-sdk 0.1.0

package/src/handlers/vaults.ts

@@ -0,0 +1,99 @@
+import { z } from "zod";
+import { routeWrap, jsonOk } from "../http";
+import { createVault, getVault, deleteVault, listVaults, listEntries, getEntry, setEntry, deleteEntry } from "../db/vaults";
+import { getAgent } from "../db/agents";
+import { badRequest, notFound } from "../errors";
+
+const CreateVaultSchema = z.object({
+  agent_id: z.string().min(1),
+  name: z.string().min(1),
+});
+
+const PutEntrySchema = z.object({
+  value: z.string(),
+});
+
+export function handleCreateVault(request: Request): Promise<Response> {
+  return routeWrap(request, async () => {
+    const body = await request.json();
+    const parsed = CreateVaultSchema.safeParse(body);
+    if (!parsed.success) throw badRequest(parsed.error.message);
+
+    const agent = getAgent(parsed.data.agent_id);
+    if (!agent) throw notFound(`agent not found: ${parsed.data.agent_id}`);
+
+    const vault = createVault({
+      agent_id: parsed.data.agent_id,
+      name: parsed.data.name,
+    });
+    return jsonOk(vault, 201);
+  });
+}
+
+export function handleListVaults(request: Request): Promise<Response> {
+  return routeWrap(request, async ({ request: req }) => {
+    const url = new URL(req.url);
+    const agentId = url.searchParams.get("agent_id") ?? undefined;
+    const data = listVaults({ agent_id: agentId });
+    return jsonOk({ data });
+  });
+}
+
+export function handleGetVault(request: Request, id: string): Promise<Response> {
+  return routeWrap(request, async () => {
+    const vault = getVault(id);
+    if (!vault) throw notFound(`vault not found: ${id}`);
+    return jsonOk(vault);
+  });
+}
+
+export function handleDeleteVault(request: Request, id: string): Promise<Response> {
+  return routeWrap(request, async () => {
+    const deleted = deleteVault(id);
+    if (!deleted) throw notFound(`vault not found: ${id}`);
+    return jsonOk({ id, type: "vault_deleted" });
+  });
+}
+
+export function handleListEntries(request: Request, vaultId: string): Promise<Response> {
+  return routeWrap(request, async () => {
+    const vault = getVault(vaultId);
+    if (!vault) throw notFound(`vault not found: ${vaultId}`);
+    const data = listEntries(vaultId);
+    return jsonOk({ data });
+  });
+}
+
+export function handleGetEntry(request: Request, vaultId: string, key: string): Promise<Response> {
+  return routeWrap(request, async () => {
+    const vault = getVault(vaultId);
+    if (!vault) throw notFound(`vault not found: ${vaultId}`);
+    const entry = getEntry(vaultId, key);
+    if (!entry) throw notFound(`entry not found: ${key}`);
+    return jsonOk(entry);
+  });
+}
+
+export function handlePutEntry(request: Request, vaultId: string, key: string): Promise<Response> {
+  return routeWrap(request, async () => {
+    const vault = getVault(vaultId);
+    if (!vault) throw notFound(`vault not found: ${vaultId}`);
+
+    const body = await request.json();
+    const parsed = PutEntrySchema.safeParse(body);
+    if (!parsed.success) throw badRequest(parsed.error.message);
+
+    setEntry(vaultId, key, parsed.data.value);
+    return jsonOk({ key, value: parsed.data.value });
+  });
+}
+
+export function handleDeleteEntry(request: Request, vaultId: string, key: string): Promise<Response> {
+  return routeWrap(request, async () => {
+    const vault = getVault(vaultId);
+    if (!vault) throw notFound(`vault not found: ${vaultId}`);
+    const deleted = deleteEntry(vaultId, key);
+    if (!deleted) throw notFound(`entry not found: ${key}`);
+    return jsonOk({ key, type: "entry_deleted" });
+  });
+}

package/src/http.ts

@@ -0,0 +1,35 @@
+/**
+ * Route helpers: common boilerplate for every /v1 handler.
+ *
+ * - `ensureInitialized()` runs on first request
+ * - `authenticate(request)` extracts + validates the API key
+ * - wraps errors into the Managed Agents envelope
+ *
+ * Framework-agnostic — uses Web Standard Response only.
+ */
+import { ensureInitialized } from "./init";
+import { authenticate } from "./auth/middleware";
+import { toResponse } from "./errors";
+import type { AuthContext } from "./types";
+
+export interface RouteContext {
+  auth: AuthContext;
+  request: Request;
+}
+
+export async function routeWrap(
+  request: Request,
+  handler: (ctx: RouteContext) => Promise<Response>,
+): Promise<Response> {
+  try {
+    await ensureInitialized();
+    const auth = await authenticate(request);
+    return await handler({ auth, request });
+  } catch (err) {
+    return toResponse(err);
+  }
+}
+
+export function jsonOk<T>(body: T, status = 200): Response {
+  return Response.json(body, { status });
+}

package/src/index.ts

@@ -0,0 +1,104 @@
+/**
+ * @agentstep/agent-sdk — framework-agnostic Managed Agents engine.
+ *
+ * This is the public API surface. Adapters (Next.js, Hono, etc.) import
+ * from here or from subpath exports like `@agentstep/agent-sdk/db/agents`.
+ */
+
+// HTTP helpers
+export { routeWrap, jsonOk, type RouteContext } from "./http";
+
+// Errors
+export {
+  ApiError,
+  envelope,
+  toResponse,
+  badRequest,
+  unauthorized,
+  forbidden,
+  notFound,
+  conflict,
+  tooManyRequests,
+  serverBusy,
+  type ErrorType,
+} from "./errors";
+
+// Init + shutdown
+export { ensureInitialized } from "./init";
+export { installShutdownHandlers } from "./shutdown";
+
+// Auth
+export { authenticate } from "./auth/middleware";
+
+// Types
+export type {
+  Agent,
+  AuthContext,
+  EventRow,
+  ManagedEvent,
+  McpServerConfig,
+  SessionStatus,
+} from "./types";
+
+// State
+export { pushPendingUserInput, type TurnInput } from "./state";
+
+// DB
+export { getDb } from "./db/client";
+export { createAgent, getAgent, updateAgent, archiveAgent, listAgents } from "./db/agents";
+export {
+  createSession,
+  getSession,
+  getSessionRow,
+  listSessions,
+  updateSessionMutable,
+  archiveSession,
+  setOutcomeCriteria,
+} from "./db/sessions";
+export {
+  createEnvironment,
+  getEnvironment,
+  listEnvironments,
+  archiveEnvironment,
+  deleteEnvironment,
+  hasSessionsAttached,
+} from "./db/environments";
+export { appendEventsBatch, listEvents, rowToManagedEvent } from "./db/events";
+export { createVault, getVault, deleteVault, listVaults, listEntries, getEntry, setEntry, deleteEntry } from "./db/vaults";
+export {
+  createMemoryStore, getMemoryStore, listMemoryStores, deleteMemoryStore,
+  createOrUpsertMemory, getMemory, getMemoryByPath, listMemories, updateMemory, deleteMemory,
+} from "./db/memory";
+export { executeBatch, BatchError } from "./db/batch";
+export { isProxied, markProxied, unmarkProxied } from "./db/proxy";
+
+// Sessions
+export { appendEvent, subscribe, dropEmitter } from "./sessions/bus";
+export { getActor, dropActor } from "./sessions/actor";
+export { interruptSession } from "./sessions/interrupt";
+export { runTurn, writePermissionResponse } from "./sessions/driver";
+
+// Queue
+export { enqueueTurn } from "./queue";
+
+// Backends
+export { resolveBackend } from "./backends/registry";
+
+// Providers
+export { resolveContainerProvider } from "./providers/registry";
+
+// Proxy
+export { forwardToAnthropic, validateAnthropicProxy } from "./proxy/forward";
+
+// Sprite/lifecycle
+export { releaseSession } from "./sprite/lifecycle";
+export { kickoffEnvironmentSetup } from "./sprite/setup";
+
+// OpenAPI
+export { buildOpenApiDocument } from "./openapi/spec";
+
+// Config
+export { getConfig } from "./config";
+
+// Utils
+export { nowMs } from "./util/clock";

package/src/init.ts

@@ -0,0 +1,227 @@
+/**
+ * One-time service initialization.
+ *
+ * Runs on first request (any route calls `await ensureInitialized()`):
+ *   1. Boot the DB (which runs migrations)
+ *   2. Recover stale sessions: any row with status='running' gets a
+ *      `session.error{type:"server_restart"}` event + flipped to idle.
+ *      (We do NOT implement true session.status_rescheduled semantics — see
+ *      plan §I8.)
+ *   3. Sprite orphan reconciler: best-effort pruning of old sprites whose
+ *      sessions no longer exist.
+ *
+ * Pattern from 
+ */
+import { getDb } from "./db/client";
+import { createApiKey, listApiKeys } from "./db/api_keys";
+import { getConfig } from "./config";
+import { appendEvent } from "./sessions/bus";
+import { getLastUnprocessedUserMessage } from "./db/events";
+import { runSweep } from "./sessions/sweeper";
+import { getRuntime } from "./state";
+import { runTurn } from "./sessions/driver";
+import { enqueueTurn } from "./queue";
+import { reconcileOrphans, reconcileDockerOrphans } from "./sprite/lifecycle";
+import { installShutdownHandlers } from "./shutdown";
+import { nowMs } from "./util/clock";
+import { resolveContainerProvider } from "./providers/registry";
+import { getEnvironment } from "./db/environments";
+import { setSessionSprite } from "./db/sessions";
+import * as pool from "./sprite/pool";
+import type { SessionRow } from "./types";
+
+type GlobalInit = typeof globalThis & {
+  __caInitPromise?: Promise<void>;
+  __caSweeperHandle?: NodeJS.Timeout;
+};
+const g = globalThis as GlobalInit;
+
+export async function ensureInitialized(): Promise<void> {
+  if (g.__caInitPromise) return g.__caInitPromise;
+  g.__caInitPromise = doInit();
+  return g.__caInitPromise;
+}
+
+async function doInit(): Promise<void> {
+  // 1. Bootstrap DB + migrations
+  getDb();
+
+  // 1b. Auto-seed a default API key if none exist
+  seedDefaultApiKey();
+
+  // 1c. Shutdown handlers
+  installShutdownHandlers();
+
+  // 2. Stale-session recovery
+  try {
+    await recoverStaleSessions();
+  } catch (err) {
+    console.error("[init] stale session recovery failed:", err);
+  }
+
+  // 3. Sprite orphan reconcile (best-effort, non-blocking)
+  const cfg = getConfig();
+  if (cfg.spriteToken) {
+    reconcileOrphans()
+      .then((r) => {
+        if (r.deleted > 0) {
+          console.log(`[init] reconciled ${r.deleted} orphan sprites, kept ${r.kept}`);
+        }
+      })
+      .catch((err) => {
+        console.warn("[init] orphan reconcile (sprites) failed:", err);
+      });
+  }
+
+  // 3b. Docker orphan reconcile (best-effort, non-blocking)
+  reconcileDockerOrphans()
+    .then((r) => {
+      if (r.deleted > 0) {
+        console.log(`[init] reconciled ${r.deleted} orphan docker containers, kept ${r.kept}`);
+      }
+    })
+    .catch((err) => {
+      console.warn("[init] orphan reconcile (docker) failed:", err);
+    });
+
+  // 4. Install the periodic sweeper (idle eviction + orphan reconcile).
+  // HMR caveat: the globalThis guard prevents duplicate timers across dev
+  // reloads, but when `next dev` hot-reloads the sweeper module the existing
+  // timer keeps firing into the *old* module's closure. Sweeper logic changes
+  // in dev require a full server restart to pick up.
+  if (!g.__caSweeperHandle) {
+    const intervalMs = getConfig().sweeperIntervalMs;
+    g.__caSweeperHandle = setInterval(() => {
+      void runSweep();
+    }, intervalMs);
+  }
+}
+
+function seedDefaultApiKey(): void {
+  try {
+    const keys = listApiKeys();
+    if (keys.length > 0) return;
+
+    // If SEED_API_KEY is set (e.g. via Secret Manager in Cloud Run),
+    // use it instead of generating a random key.
+    const seedKey = process.env.SEED_API_KEY;
+    if (seedKey) {
+      const { id } = createApiKey({ name: "default", permissions: ["*"], rawKey: seedKey });
+      console.log(`[init] created API key from SEED_API_KEY (id: ${id})`);
+      return;
+    }
+
+    const { key, id } = createApiKey({ name: "default", permissions: ["*"] });
+    console.log("[init] created default API key (save this — shown once):");
+    console.log(`  id:  ${id}`);
+    console.log(`  key: ${key}`);
+  } catch (err) {
+    console.error("[init] failed to seed default API key:", err);
+  }
+}
+
+export async function recoverStaleSessions(): Promise<void> {
+  const db = getDb();
+  const rows = db
+    .prepare(
+      `SELECT * FROM sessions WHERE status = 'running' AND archived_at IS NULL`,
+    )
+    .all() as SessionRow[];
+
+  if (rows.length === 0) return;
+  console.log(`[init] recovering ${rows.length} stale running session(s)`);
+
+  const rt = getRuntime();
+  for (const row of rows) {
+    try {
+      // Try to reschedule: find the last unprocessed user.message
+      const lastMsg = getLastUnprocessedUserMessage(row.id);
+      if (lastMsg) {
+        // If the session had a sprite, verify the container still exists
+        if (row.sprite_name) {
+          const envObj = getEnvironment(row.environment_id);
+          const provider = await resolveContainerProvider(envObj?.config?.provider);
+          try {
+            const containers = await provider.list({ prefix: row.sprite_name });
+            const alive = containers.some((c) => c.name === row.sprite_name);
+            if (!alive) {
+              console.warn(`[init] sprite ${row.sprite_name} for session ${row.id} no longer exists, clearing`);
+              setSessionSprite(row.id, null);
+            } else {
+              // Re-register in the in-memory pool so lifecycle/sweeper can see it
+              pool.register({
+                spriteName: row.sprite_name,
+                envId: row.environment_id,
+                sessionId: row.id,
+                createdAt: nowMs(),
+              });
+            }
+          } catch (err) {
+            console.warn(`[init] container health check failed for ${row.sprite_name}, clearing:`, err);
+            setSessionSprite(row.id, null);
+          }
+        }
+
+        // Emit rescheduled event
+        appendEvent(row.id, {
+          type: "session.status_rescheduled",
+          payload: {},
+          origin: "server",
+          processedAt: nowMs(),
+        });
+
+        // Flip status to idle so the turn can restart
+        db.prepare(
+          `UPDATE sessions SET status = 'idle', stop_reason = 'rescheduled', updated_at = ? WHERE id = ?`,
+        ).run(nowMs(), row.id);
+        rt.inFlightRuns.delete(row.id);
+
+        // Extract the text from the user.message payload
+        const payload = JSON.parse(lastMsg.payload_json) as { content?: Array<{ type: string; text?: string }> };
+        const text = (payload.content ?? [])
+          .filter((b) => b.type === "text" && b.text)
+          .map((b) => b.text!)
+          .join("");
+
+        // Fire-and-forget: re-enqueue the turn
+        void enqueueTurn(row.environment_id, () =>
+          runTurn(row.id, [{ kind: "text", eventId: lastMsg.id, text }]),
+        ).catch((err: unknown) => {
+          console.error(`[init] reschedule turn failed for ${row.id}:`, err);
+        });
+
+        console.log(`[init] rescheduled session ${row.id}`);
+        continue;
+      }
+    } catch (err) {
+      console.warn(`[init] reschedule attempt failed for ${row.id}, falling back to error:`, err);
+    }
+
+    // Fallback: emit error + idle
+    try {
+      appendEvent(row.id, {
+        type: "session.error",
+        payload: {
+          error: {
+            type: "server_restart",
+            message: "server restarted while turn was running",
+          },
+        },
+        origin: "server",
+        processedAt: nowMs(),
+      });
+      appendEvent(row.id, {
+        type: "session.status_idle",
+        payload: { stop_reason: "error" },
+        origin: "server",
+        processedAt: nowMs(),
+      });
+      db.prepare(
+        `UPDATE sessions SET status = 'idle', stop_reason = 'error', updated_at = ? WHERE id = ?`,
+      ).run(nowMs(), row.id);
+      rt.inFlightRuns.delete(row.id);
+    } catch (err) {
+      console.error(`[init] failed to recover session ${row.id}:`, err);
+    }
+  }
+}

package/src/openapi/registry.ts

@@ -0,0 +1,8 @@
+/**
+ * Singleton OpenAPIRegistry shared across the schema module and the spec
+ * builder. Kept in its own file so `schemas.ts` and `spec.ts` can both
+ * import it without a circular dependency.
+ */
+import { OpenAPIRegistry } from "@asteasolutions/zod-to-openapi";
+
+export const registry = new OpenAPIRegistry();