@agentstep/agent-sdk 0.1.0

package/src/queue/index.ts

@@ -0,0 +1,111 @@
+/**
+ * Turn-level concurrency queue.
+ *
+ * Enforces two limits:
+ *   - Global: `config.concurrency` (how many turns may run simultaneously
+ *     across all sessions/environments)
+ *   - Per-environment: `config.maxSpritesPerEnv` (real resource constraint,
+ *     since each running turn owns a sprite in its env's pool)
+ *
+ * Sessions are pinned to sprites 1:1, so a session's active turn naturally
+ * consumes one env slot. The queue tracks pending enqueues and releases
+ * capacity as turns complete.
+ *
+ * Pattern inspired by
+ * 
+ * reparameterized per plan §Important I3.
+ */
+import { getConfig } from "../config";
+import { serverBusy } from "../errors";
+
+interface Job<T> {
+  envId: string;
+  run: () => Promise<T>;
+  resolve: (v: T) => void;
+  reject: (e: unknown) => void;
+}
+
+type State = {
+  queue: Job<unknown>[];
+  activeGlobal: number;
+  activeByEnv: Map<string, number>;
+};
+
+type GlobalQueue = typeof globalThis & { __caQueue?: State };
+
+function state(): State {
+  const g = globalThis as GlobalQueue;
+  if (!g.__caQueue) {
+    g.__caQueue = {
+      queue: [],
+      activeGlobal: 0,
+      activeByEnv: new Map(),
+    };
+  }
+  return g.__caQueue;
+}
+
+/**
+ * Enqueue a turn-runner against the given environment. Throws `serverBusy`
+ * immediately if the queue depth limit is exceeded.
+ */
+export function enqueueTurn<T>(envId: string, run: () => Promise<T>): Promise<T> {
+  const s = state();
+  const cfg = getConfig();
+  const maxDepth = 100; // generous — each job is lightweight
+  if (s.queue.length >= maxDepth) {
+    throw serverBusy("turn queue is full");
+  }
+
+  return new Promise<T>((resolve, reject) => {
+    s.queue.push({
+      envId,
+      run: run as () => Promise<unknown>,
+      resolve: resolve as (v: unknown) => void,
+      reject,
+    });
+    drain();
+  });
+
+  function drain(): void {
+    const st = state();
+    const c = getConfig();
+    for (let i = 0; i < st.queue.length; i++) {
+      if (st.activeGlobal >= c.concurrency) break;
+      const job = st.queue[i];
+      const envActive = st.activeByEnv.get(job.envId) ?? 0;
+      if (envActive >= c.maxSpritesPerEnv) continue;
+
+      // Take this job
+      st.queue.splice(i, 1);
+      i--;
+      st.activeGlobal++;
+      st.activeByEnv.set(job.envId, envActive + 1);
+
+      void (async () => {
+        try {
+          const r = await job.run();
+          job.resolve(r);
+        } catch (err) {
+          job.reject(err);
+        } finally {
+          const st2 = state();
+          st2.activeGlobal--;
+          const envAct = st2.activeByEnv.get(job.envId) ?? 1;
+          if (envAct <= 1) st2.activeByEnv.delete(job.envId);
+          else st2.activeByEnv.set(job.envId, envAct - 1);
+          drain();
+        }
+      })();
+    }
+  }
+}
+
+export function queueStats() {
+  const s = state();
+  return {
+    queued: s.queue.length,
+    activeGlobal: s.activeGlobal,
+    activeByEnv: Array.from(s.activeByEnv.entries()),
+  };
+}

package/src/sessions/actor.ts

@@ -0,0 +1,53 @@
+/**
+ * Per-session async-serialized actor.
+ *
+ * This is the concurrency primitive everything else depends on for ordering
+ * correctness. One actor per session; all mutating work (append events, run
+ * turns, interrupt, archive, delete) goes through `enqueue(fn)` which runs
+ * tasks serially in FIFO order.
+ *
+ * Rationale (plan §Critical fix C2): per-event SQL transactions do not
+ * serialize the DECISION to abort with respect to the event stream. A real
+ * in-memory lock is required, and the cleanest shape is a FIFO promise chain
+ * scoped to the session.
+ */
+type GlobalActors = typeof globalThis & {
+  __caActors?: Map<string, SessionActor>;
+};
+
+export class SessionActor {
+  private tail: Promise<unknown> = Promise.resolve();
+
+  constructor(public readonly sessionId: string) {}
+
+  enqueue<T>(fn: () => Promise<T>): Promise<T> {
+    const run = this.tail.then(fn, fn);
+    // Swallow errors on the chain so one failed job doesn't kill the actor.
+    this.tail = run.catch(() => {});
+    return run;
+  }
+}
+
+function registry(): Map<string, SessionActor> {
+  const g = globalThis as GlobalActors;
+  if (!g.__caActors) g.__caActors = new Map();
+  return g.__caActors;
+}
+
+export function getActor(sessionId: string): SessionActor {
+  const reg = registry();
+  let actor = reg.get(sessionId);
+  if (!actor) {
+    actor = new SessionActor(sessionId);
+    reg.set(sessionId, actor);
+  }
+  return actor;
+}
+
+export function dropActor(sessionId: string): void {
+  registry().delete(sessionId);
+}
+
+export function allActorIds(): string[] {
+  return Array.from(registry().keys());
+}

package/src/sessions/bus.ts

@@ -0,0 +1,155 @@
+/**
+ * Session event bus: append-only log + EventEmitter fan-out.
+ *
+ * The DB is authoritative; the emitter is the live tail. Callers mutate the
+ * session log exclusively through `appendEvent` / `appendEventsBatch`, which
+ * insert under an IMMEDIATE transaction and THEN emit post-commit. This is
+ * how the Managed Agents stream-first reconnect contract works: subscribers
+ * can attach anytime, backfill from the DB, and keep tailing the emitter.
+ *
+ * Every append MUST be invoked from inside the corresponding session's
+ * `SessionActor` (see `lib/sessions/actor.ts`) to preserve ordering.
+ */
+import { EventEmitter } from "node:events";
+import {
+  appendEvent as dbAppend,
+  appendEventsBatch as dbAppendBatch,
+  listEvents,
+  rowToManagedEvent,
+  type AppendInput,
+} from "../db/events";
+import { getSession } from "../db/sessions";
+import { getAgent } from "../db/agents";
+import type { EventRow, ManagedEvent } from "../types";
+
+type GlobalBus = typeof globalThis & {
+  __caBusEmitters?: Map<string, EventEmitter>;
+};
+
+function emitters(): Map<string, EventEmitter> {
+  const g = globalThis as GlobalBus;
+  if (!g.__caBusEmitters) g.__caBusEmitters = new Map();
+  return g.__caBusEmitters;
+}
+
+/** Cached webhook config per session — avoids 2 DB reads (getSession + getAgent) per event. */
+interface WebhookCacheEntry {
+  webhookUrl: string | null;
+  webhookEvents: string[];
+}
+const webhookCache = new Map<string, WebhookCacheEntry>();
+
+function getWebhookConfig(sessionId: string): WebhookCacheEntry {
+  const cached = webhookCache.get(sessionId);
+  if (cached) return cached;
+
+  const session = getSession(sessionId);
+  if (!session) {
+    const entry: WebhookCacheEntry = { webhookUrl: null, webhookEvents: [] };
+    webhookCache.set(sessionId, entry);
+    return entry;
+  }
+  const agent = getAgent(session.agent.id, session.agent.version);
+  const entry: WebhookCacheEntry = {
+    webhookUrl: agent?.webhook_url ?? null,
+    webhookEvents: agent?.webhook_events ?? [],
+  };
+  webhookCache.set(sessionId, entry);
+  return entry;
+}
+
+function getOrCreateEmitter(sessionId: string): EventEmitter {
+  const reg = emitters();
+  let em = reg.get(sessionId);
+  if (!em) {
+    em = new EventEmitter();
+    em.setMaxListeners(0); // unbounded subscribers per session
+    reg.set(sessionId, em);
+  }
+  return em;
+}
+
+function fireWebhook(sessionId: string, row: EventRow): void {
+  try {
+    const config = getWebhookConfig(sessionId);
+    if (!config.webhookUrl) return;
+    if (!config.webhookEvents.includes(row.type)) return;
+
+    const payload = JSON.stringify(rowToManagedEvent(row));
+    void fetch(config.webhookUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: payload,
+      signal: AbortSignal.timeout(5000),
+    }).catch((err: unknown) => {
+      console.warn(`[webhook] POST to ${config.webhookUrl} failed:`, err);
+    });
+  } catch {
+    // best-effort — never let webhook errors propagate
+  }
+}
+
+export function appendEvent(sessionId: string, input: AppendInput): EventRow {
+  const row = dbAppend(sessionId, input);
+  getOrCreateEmitter(sessionId).emit("event", row);
+  fireWebhook(sessionId, row);
+  return row;
+}
+
+export function appendEventsBatch(sessionId: string, inputs: AppendInput[]): EventRow[] {
+  const rows = dbAppendBatch(sessionId, inputs);
+  const em = getOrCreateEmitter(sessionId);
+  for (const row of rows) {
+    em.emit("event", row);
+    fireWebhook(sessionId, row);
+  }
+  return rows;
+}
+
+export interface Subscription {
+  unsubscribe(): void;
+}
+
+/**
+ * Subscribe to live events for a session. First emits any backlog rows with
+ * `seq > fromSeq` (read from the DB), then attaches a live listener. The
+ * backlog read and live attach happen in sequence; a small race is possible
+ * where an event lands between the DB read and the listener attach, so the
+ * live handler dedupes by tracking `lastDeliveredSeq`.
+ */
+export function subscribe(
+  sessionId: string,
+  fromSeq: number,
+  onEvent: (evt: ManagedEvent) => void,
+): Subscription {
+  const em = getOrCreateEmitter(sessionId);
+  let lastDeliveredSeq = fromSeq;
+
+  // Backlog drain
+  const backlog = listEvents(sessionId, { limit: 500, order: "asc", afterSeq: fromSeq });
+  for (const row of backlog) {
+    onEvent(rowToManagedEvent(row));
+    if (row.seq > lastDeliveredSeq) lastDeliveredSeq = row.seq;
+  }
+
+  const handler = (row: EventRow) => {
+    if (row.seq <= lastDeliveredSeq) return;
+    onEvent(rowToManagedEvent(row));
+    lastDeliveredSeq = row.seq;
+  };
+  em.on("event", handler);
+
+  return {
+    unsubscribe() {
+      em.off("event", handler);
+    },
+  };
+}
+
+export function dropEmitter(sessionId: string): void {
+  const reg = emitters();
+  const em = reg.get(sessionId);
+  if (em) em.removeAllListeners();
+  reg.delete(sessionId);
+  webhookCache.delete(sessionId);
+}