@agentstep/agent-sdk 0.1.0

package/src/db/agents.ts

@@ -0,0 +1,185 @@
+import { getDb } from "./client";
+import { newId } from "../util/ids";
+import { nowMs, toIso } from "../util/clock";
+import type {
+  Agent,
+  AgentRow,
+  AgentVersionRow,
+  BackendName,
+  McpServerConfig,
+  ToolConfig,
+} from "../types";
+
+function hydrate(row: AgentRow, ver: AgentVersionRow): Agent {
+  return {
+    id: row.id,
+    version: ver.version,
+    name: row.name,
+    model: ver.model,
+    system: ver.system,
+    tools: JSON.parse(ver.tools_json) as ToolConfig[],
+    mcp_servers: JSON.parse(ver.mcp_servers_json) as Record<string, McpServerConfig>,
+    backend: (ver.backend ?? "claude") as BackendName,
+    webhook_url: ver.webhook_url ?? null,
+    webhook_events: ver.webhook_events_json ? (JSON.parse(ver.webhook_events_json) as string[]) : ["session.status_idle", "session.status_running", "session.error"],
+    threads_enabled: Boolean(ver.threads_enabled),
+    confirmation_mode: Boolean(ver.confirmation_mode),
+    callable_agents: ver.callable_agents_json ? JSON.parse(ver.callable_agents_json) : [],
+    created_at: toIso(row.created_at),
+    updated_at: toIso(row.updated_at),
+  };
+}
+
+export function createAgent(input: {
+  name: string;
+  model: string;
+  system?: string | null;
+  tools?: ToolConfig[];
+  mcp_servers?: Record<string, McpServerConfig>;
+  backend?: BackendName;
+  webhook_url?: string | null;
+  webhook_events?: string[];
+  threads_enabled?: boolean;
+  confirmation_mode?: boolean;
+  callable_agents?: Array<{ type: "agent"; id: string; version?: number }>;
+}): Agent {
+  const db = getDb();
+  const id = newId("agent");
+  const now = nowMs();
+
+  const tx = db.transaction(() => {
+    db.prepare(
+      `INSERT INTO agents (id, current_version, name, created_at, updated_at)
+       VALUES (?, 1, ?, ?, ?)`,
+    ).run(id, input.name, now, now);
+
+    db.prepare(
+      `INSERT INTO agent_versions
+         (agent_id, version, model, system, tools_json, mcp_servers_json, backend, webhook_url, webhook_events_json, threads_enabled, confirmation_mode, callable_agents_json, created_at)
+       VALUES (?, 1, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    ).run(
+      id,
+      input.model,
+      input.system ?? null,
+      JSON.stringify(input.tools ?? []),
+      JSON.stringify(input.mcp_servers ?? {}),
+      input.backend ?? "claude",
+      input.webhook_url ?? null,
+      JSON.stringify(input.webhook_events ?? ["session.status_idle", "session.status_running", "session.error"]),
+      input.threads_enabled ? 1 : 0,
+      input.confirmation_mode ? 1 : 0,
+      input.callable_agents?.length ? JSON.stringify(input.callable_agents) : null,
+      now,
+    );
+  });
+  tx();
+
+  return getAgent(id)!;
+}
+
+export function getAgent(id: string, version?: number): Agent | null {
+  const db = getDb();
+  const row = db
+    .prepare(`SELECT * FROM agents WHERE id = ?`)
+    .get(id) as AgentRow | undefined;
+  if (!row) return null;
+
+  const v = version ?? row.current_version;
+  const ver = db
+    .prepare(
+      `SELECT * FROM agent_versions WHERE agent_id = ? AND version = ?`,
+    )
+    .get(id, v) as AgentVersionRow | undefined;
+  if (!ver) return null;
+
+  return hydrate(row, ver);
+}
+
+export function updateAgent(
+  id: string,
+  input: {
+    name?: string;
+    model?: string;
+    system?: string | null;
+    tools?: ToolConfig[];
+    mcp_servers?: Record<string, McpServerConfig>;
+    webhook_url?: string | null;
+    webhook_events?: string[];
+    threads_enabled?: boolean;
+    confirmation_mode?: boolean;
+    callable_agents?: Array<{ type: "agent"; id: string; version?: number }>;
+  },
+): Agent | null {
+  const db = getDb();
+  const existing = getAgent(id);
+  if (!existing) return null;
+
+  const newVersion = existing.version + 1;
+  const now = nowMs();
+
+  const tx = db.transaction(() => {
+    db.prepare(
+      `INSERT INTO agent_versions
+         (agent_id, version, model, system, tools_json, mcp_servers_json, backend, webhook_url, webhook_events_json, threads_enabled, confirmation_mode, callable_agents_json, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    ).run(
+      id,
+      newVersion,
+      input.model ?? existing.model,
+      input.system ?? existing.system,
+      JSON.stringify(input.tools ?? existing.tools),
+      JSON.stringify(input.mcp_servers ?? existing.mcp_servers),
+      existing.backend,
+      input.webhook_url !== undefined ? input.webhook_url : existing.webhook_url,
+      JSON.stringify(input.webhook_events ?? existing.webhook_events),
+      input.threads_enabled !== undefined ? (input.threads_enabled ? 1 : 0) : (existing.threads_enabled ? 1 : 0),
+      input.confirmation_mode !== undefined ? (input.confirmation_mode ? 1 : 0) : (existing.confirmation_mode ? 1 : 0),
+      input.callable_agents !== undefined ? (input.callable_agents.length ? JSON.stringify(input.callable_agents) : null) : (existing.callable_agents.length ? JSON.stringify(existing.callable_agents) : null),
+      now,
+    );
+
+    db.prepare(
+      `UPDATE agents SET current_version = ?, name = ?, updated_at = ? WHERE id = ?`,
+    ).run(newVersion, input.name ?? existing.name, now, id);
+  });
+  tx();
+
+  return getAgent(id);
+}
+
+export function archiveAgent(id: string): boolean {
+  const db = getDb();
+  const res = db
+    .prepare(`UPDATE agents SET archived_at = ? WHERE id = ? AND archived_at IS NULL`)
+    .run(nowMs(), id);
+  return res.changes > 0;
+}
+
+export function listAgents(opts: {
+  limit?: number;
+  order?: "asc" | "desc";
+  includeArchived?: boolean;
+  cursor?: string; // agent id cursor
+}): Agent[] {
+  const db = getDb();
+  const limit = Math.min(Math.max(opts.limit ?? 20, 1), 100);
+  const order = opts.order === "asc" ? "ASC" : "DESC";
+  const includeArchived = opts.includeArchived ?? false;
+
+  const clauses: string[] = [];
+  const params: unknown[] = [];
+  if (!includeArchived) clauses.push("archived_at IS NULL");
+  if (opts.cursor) {
+    clauses.push(order === "DESC" ? "id < ?" : "id > ?");
+    params.push(opts.cursor);
+  }
+  const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+
+  const rows = db
+    .prepare(
+      `SELECT * FROM agents ${where} ORDER BY id ${order} LIMIT ?`,
+    )
+    .all(...params, limit) as AgentRow[];
+
+  return rows.map((r) => getAgent(r.id)!).filter(Boolean);
+}

package/src/db/api_keys.ts

@@ -0,0 +1,78 @@
+import crypto from "node:crypto";
+import { getDb } from "./client";
+import { newId } from "../util/ids";
+import { nowMs } from "../util/clock";
+
+export interface ApiKeyRow {
+  id: string;
+  name: string;
+  hash: string;
+  prefix: string;
+  permissions_json: string;
+  created_at: number;
+  revoked_at: number | null;
+}
+
+function hashKey(raw: string): string {
+  return crypto.createHash("sha256").update(raw).digest("hex");
+}
+
+/**
+ * Create a new API key. Returns the full raw key string ONCE —
+ * it is not stored in plain text and cannot be retrieved later.
+ */
+export function createApiKey(input: {
+  name: string;
+  permissions?: string[];
+  rawKey?: string;
+}): { key: string; id: string } {
+  const db = getDb();
+  const id = newId("key");
+  const raw = input.rawKey || `ck_${crypto.randomBytes(24).toString("base64url")}`;
+  const hash = hashKey(raw);
+  const prefix = raw.slice(0, 8);
+
+  db.prepare(
+    `INSERT INTO api_keys (id, name, hash, prefix, permissions_json, created_at)
+     VALUES (?, ?, ?, ?, ?, ?)`,
+  ).run(
+    id,
+    input.name,
+    hash,
+    prefix,
+    JSON.stringify(input.permissions ?? ["*"]),
+    nowMs(),
+  );
+
+  return { key: raw, id };
+}
+
+export function findByRawKey(raw: string): ApiKeyRow | null {
+  const db = getDb();
+  const hash = hashKey(raw);
+  return (
+    (db
+      .prepare(
+        `SELECT * FROM api_keys WHERE hash = ? AND revoked_at IS NULL`,
+      )
+      .get(hash) as ApiKeyRow | undefined) ?? null
+  );
+}
+
+export function revokeApiKey(id: string): boolean {
+  const db = getDb();
+  const res = db
+    .prepare(`UPDATE api_keys SET revoked_at = ? WHERE id = ? AND revoked_at IS NULL`)
+    .run(nowMs(), id);
+  return res.changes > 0;
+}
+
+export function listApiKeys(): Array<Omit<ApiKeyRow, "hash">> {
+  const db = getDb();
+  const rows = db
+    .prepare(
+      `SELECT * FROM api_keys WHERE revoked_at IS NULL ORDER BY created_at DESC`,
+    )
+    .all() as ApiKeyRow[];
+  return rows.map(({ hash: _hash, ...rest }) => rest);
+}

package/src/db/batch.ts

@@ -0,0 +1,142 @@
+/**
+ * Batch operations: execute multiple resource mutations in a single
+ * SQLite transaction. All operations succeed or all fail.
+ */
+import { getDb } from "./client";
+import { createAgent, archiveAgent } from "./agents";
+import { createEnvironment, deleteEnvironment } from "./environments";
+import { createSession } from "./sessions";
+import { getAgent } from "./agents";
+import { getEnvironment } from "./environments";
+import type { EnvironmentConfig } from "../types";
+
+export interface BatchOp {
+  method: string;
+  path: string;
+  body?: Record<string, unknown>;
+}
+
+export interface BatchResult {
+  status: number;
+  body: unknown;
+}
+
+/**
+ * Execute a batch of operations in a single transaction.
+ * On any error, the transaction rolls back and the error is returned
+ * for the failed operation.
+ */
+export function executeBatch(operations: BatchOp[]): BatchResult[] {
+  const db = getDb();
+
+  return db.transaction(() => {
+    const results: BatchResult[] = [];
+
+    for (const op of operations) {
+      try {
+        const result = executeSingleOp(op);
+        results.push(result);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        // Re-throw to trigger transaction rollback
+        throw new BatchError(results.length, msg, results);
+      }
+    }
+
+    return results;
+  })();
+}
+
+export class BatchError extends Error {
+  constructor(
+    public readonly failedIndex: number,
+    message: string,
+    public readonly partialResults: BatchResult[],
+  ) {
+    super(message);
+    this.name = "BatchError";
+  }
+}
+
+function executeSingleOp(op: BatchOp): BatchResult {
+  const { method, path, body } = op;
+  const upperMethod = method.toUpperCase();
+
+  // POST /v1/agents
+  if (upperMethod === "POST" && path === "/v1/agents") {
+    if (!body?.name || !body?.model) {
+      throw new Error("agent creation requires name and model");
+    }
+    const agent = createAgent({
+      name: body.name as string,
+      model: body.model as string,
+      system: (body.system as string) ?? null,
+      tools: (body.tools as []) ?? [],
+      mcp_servers: (body.mcp_servers as Record<string, never>) ?? {},
+      backend: (body.backend as "claude") ?? "claude",
+      webhook_url: (body.webhook_url as string) ?? null,
+      webhook_events: body.webhook_events as string[] | undefined,
+      threads_enabled: (body.threads_enabled as boolean) ?? false,
+    });
+    return { status: 201, body: agent };
+  }
+
+  // POST /v1/environments
+  if (upperMethod === "POST" && path === "/v1/environments") {
+    if (!body?.name || !body?.config) {
+      throw new Error("environment creation requires name and config");
+    }
+    const env = createEnvironment({
+      name: body.name as string,
+      config: body.config as EnvironmentConfig,
+    });
+    return { status: 201, body: env };
+  }
+
+  // POST /v1/sessions
+  if (upperMethod === "POST" && path === "/v1/sessions") {
+    if (!body?.agent || !body?.environment_id) {
+      throw new Error("session creation requires agent and environment_id");
+    }
+    const agentRef = body.agent as string | { id: string; version: number };
+    const agentId = typeof agentRef === "string" ? agentRef : agentRef.id;
+    const agentVersion = typeof agentRef === "string" ? undefined : agentRef.version;
+
+    const agent = getAgent(agentId, agentVersion);
+    if (!agent) throw new Error(`agent not found: ${agentId}`);
+
+    const env = getEnvironment(body.environment_id as string);
+    if (!env) throw new Error(`environment not found: ${body.environment_id}`);
+
+    const session = createSession({
+      agent_id: agent.id,
+      agent_version: agent.version,
+      environment_id: env.id,
+      title: (body.title as string) ?? null,
+      metadata: (body.metadata as Record<string, unknown>) ?? {},
+      max_budget_usd: (body.max_budget_usd as number) ?? null,
+      vault_ids: (body.vault_ids as string[]) ?? null,
+    });
+    return { status: 201, body: session };
+  }
+
+  // DELETE /v1/agents/{id}
+  const agentDeleteMatch = path.match(/^\/v1\/agents\/([^/]+)$/);
+  if (upperMethod === "DELETE" && agentDeleteMatch) {
+    const id = agentDeleteMatch[1];
+    const archived = archiveAgent(id);
+    if (!archived) throw new Error(`agent not found: ${id}`);
+    return { status: 200, body: { id, type: "agent_deleted" } };
+  }
+
+  // DELETE /v1/environments/{id}
+  const envDeleteMatch = path.match(/^\/v1\/environments\/([^/]+)$/);
+  if (upperMethod === "DELETE" && envDeleteMatch) {
+    const id = envDeleteMatch[1];
+    const deleted = deleteEnvironment(id);
+    if (!deleted) throw new Error(`environment not found: ${id}`);
+    return { status: 200, body: { id, type: "environment_deleted" } };
+  }
+
+  throw new Error(`unsupported batch operation: ${method} ${path}`);
+}

package/src/db/client.ts

@@ -0,0 +1,81 @@
+/**
+ * libsql client with WAL + synchronous=NORMAL.
+ *
+ * Supports two modes:
+ *   1. Local-only (default): DATABASE_PATH=./data/managed-agents.db
+ *   2. Turso embedded replica: TURSO_URL + TURSO_AUTH_TOKEN env vars
+ *      → local file syncs to/from a remote Turso database
+ *
+ * HMR-safe singleton: stores the Database instance on globalThis so Next.js
+ * dev server reloads don't create a new handle per route compile.
+ */
+import Database from "libsql";
+import path from "node:path";
+import fs from "node:fs";
+import { runMigrations } from "./migrations";
+
+type DB = InstanceType<typeof Database>;
+
+type GlobalDB = typeof globalThis & {
+  __caDb?: DB;
+  __caDbPath?: string;
+};
+const g = globalThis as GlobalDB;
+
+function resolveDbPath(): string {
+  const p = process.env.DATABASE_PATH || "./data/managed-agents.db";
+  // turbopackIgnore: runtime-only path resolution — do not trace at build time
+  return path.isAbsolute(p) ? p : path.join(/* turbopackIgnore: true */ process.cwd(), p);
+}
+
+export function getDb(): DB {
+  if (g.__caDb) return g.__caDb;
+
+  const dbPath = resolveDbPath();
+  const dir = path.dirname(dbPath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const tursoUrl = process.env.TURSO_URL;
+  const tursoToken = process.env.TURSO_AUTH_TOKEN;
+
+  const db = tursoUrl
+    ? new Database(dbPath, { syncUrl: tursoUrl, authToken: tursoToken } as Record<string, unknown>)
+    : new Database(dbPath);
+
+  db.pragma("journal_mode = WAL");
+  db.pragma("synchronous = NORMAL");
+  db.pragma("foreign_keys = ON");
+  db.pragma("busy_timeout = 5000");
+
+  runMigrations(db);
+
+  // Initial sync for embedded replicas
+  if (tursoUrl) {
+    try {
+      (db as unknown as { sync(): void }).sync();
+    } catch {
+      // sync may fail on first boot if remote is empty — that's fine
+    }
+  }
+
+  g.__caDb = db;
+  g.__caDbPath = dbPath;
+  return db;
+}
+
+/** Sync embedded replica with remote Turso. No-op if not using Turso. */
+export function syncDb(): void {
+  if (!g.__caDb || !process.env.TURSO_URL) return;
+  try {
+    (g.__caDb as unknown as { sync(): void }).sync();
+  } catch (err) {
+    console.warn("[db] sync failed:", err);
+  }
+}
+
+export function closeDb(): void {
+  if (g.__caDb) {
+    g.__caDb.close();
+    g.__caDb = undefined;
+  }
+}

package/src/db/environments.ts

@@ -0,0 +1,127 @@
+import { getDb } from "./client";
+import { newId } from "../util/ids";
+import { nowMs, toIso } from "../util/clock";
+import type { Environment, EnvironmentConfig, EnvironmentRow, EnvironmentState } from "../types";
+
+function hydrate(row: EnvironmentRow): Environment {
+  return {
+    id: row.id,
+    name: row.name,
+    config: JSON.parse(row.config_json) as EnvironmentConfig,
+    state: row.state,
+    state_message: row.state_message,
+    created_at: toIso(row.created_at),
+    archived_at: row.archived_at ? toIso(row.archived_at) : null,
+  };
+}
+
+export function createEnvironment(input: {
+  name: string;
+  config: EnvironmentConfig;
+}): Environment {
+  const db = getDb();
+  const id = newId("env");
+  const now = nowMs();
+
+  db.prepare(
+    `INSERT INTO environments (id, name, config_json, state, created_at)
+     VALUES (?, ?, ?, 'preparing', ?)`,
+  ).run(id, input.name, JSON.stringify(input.config), now);
+
+  return getEnvironment(id)!;
+}
+
+export function getEnvironment(id: string): Environment | null {
+  const db = getDb();
+  const row = db
+    .prepare(`SELECT * FROM environments WHERE id = ?`)
+    .get(id) as EnvironmentRow | undefined;
+  return row ? hydrate(row) : null;
+}
+
+export function getEnvironmentRow(id: string): EnvironmentRow | null {
+  const db = getDb();
+  return (
+    (db
+      .prepare(`SELECT * FROM environments WHERE id = ?`)
+      .get(id) as EnvironmentRow | undefined) ?? null
+  );
+}
+
+export function updateEnvironmentState(
+  id: string,
+  state: EnvironmentState,
+  message?: string | null,
+): void {
+  const db = getDb();
+  db.prepare(
+    `UPDATE environments SET state = ?, state_message = ? WHERE id = ?`,
+  ).run(state, message ?? null, id);
+}
+
+export function updateEnvironmentCheckpoint(
+  id: string,
+  checkpointId: string,
+  templateSprite: string | null,
+): void {
+  const db = getDb();
+  db.prepare(
+    `UPDATE environments SET checkpoint_id = ?, template_sprite = ? WHERE id = ?`,
+  ).run(checkpointId, templateSprite, id);
+}
+
+export function archiveEnvironment(id: string): boolean {
+  const db = getDb();
+  const res = db
+    .prepare(`UPDATE environments SET archived_at = ? WHERE id = ? AND archived_at IS NULL`)
+    .run(nowMs(), id);
+  return res.changes > 0;
+}
+
+export function deleteEnvironment(id: string): boolean {
+  const db = getDb();
+  // Archive any sessions referencing this environment to avoid FK constraint
+  db.prepare(`UPDATE sessions SET archived_at = ? WHERE environment_id = ? AND archived_at IS NULL`).run(nowMs(), id);
+  const res = db.prepare(`DELETE FROM environments WHERE id = ?`).run(id);
+  return res.changes > 0;
+}
+
+export function listEnvironments(opts: {
+  limit?: number;
+  order?: "asc" | "desc";
+  includeArchived?: boolean;
+  cursor?: string;
+}): Environment[] {
+  const db = getDb();
+  const limit = Math.min(Math.max(opts.limit ?? 20, 1), 100);
+  const order = opts.order === "asc" ? "ASC" : "DESC";
+  const includeArchived = opts.includeArchived ?? false;
+
+  const clauses: string[] = [];
+  const params: unknown[] = [];
+  if (!includeArchived) clauses.push("archived_at IS NULL");
+  if (opts.cursor) {
+    clauses.push(order === "DESC" ? "id < ?" : "id > ?");
+    params.push(opts.cursor);
+  }
+  const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+
+  const rows = db
+    .prepare(
+      `SELECT * FROM environments ${where} ORDER BY id ${order} LIMIT ?`,
+    )
+    .all(...params, limit) as EnvironmentRow[];
+
+  return rows.map(hydrate);
+}
+
+export function hasSessionsAttached(envId: string): boolean {
+  const db = getDb();
+  const row = db
+    .prepare(
+      `SELECT COUNT(*) AS n FROM sessions
+       WHERE environment_id = ? AND archived_at IS NULL AND status != 'terminated'`,
+    )
+    .get(envId) as { n: number } | undefined;
+  return (row?.n ?? 0) > 0;
+}