@data-club/ai-hub-server 0.0.1

package/dist/state/turnRegistry.js

@@ -0,0 +1,149 @@
+/**
+ * In-memory broadcaster for live turn streams.
+ *
+ * Every active turn has at most one writer (the runner) and zero-or-more
+ * subscribers (the original `POST /chat` connection + every
+ * `GET /chat/:turn_id/events?from_seq=N` resumption connection still
+ * running while the turn is live).
+ *
+ * Persistence lives in `turn_events` (§11) — the registry only handles the
+ * **live attach** part of resumption. The first half of a resumption read
+ * (replay from `from_seq`) is a plain DB query.
+ *
+ * The registry is process-local — this matches the single-customer
+ * deployment model (§1). When ai-hub scales to multiple replicas in a
+ * v1.x release, this gets a Redis-backed implementation behind the same
+ * interface; the wire protocol (§9) and the resumption contract (§6.3.2)
+ * stay unchanged.
+ *
+ * @see SPECIFICATIONS.md §6.3.2 — resumption endpoint
+ * @see SPECIFICATIONS.md §6.6 — server-authoritative state machine
+ * @see SPECIFICATIONS.md §11 — `turn_events` table
+ */
+/**
+ * Process-local map of live turn channels. The map prunes a channel on
+ * close as soon as every subscriber has unsubscribed (or immediately if
+ * no subscribers are attached).
+ */
+const channels = new Map();
+/**
+ * Begins a new live turn channel.
+ *
+ * The runner calls this when it inserts the `turn` row, before it starts
+ * pumping events. Returns an opaque `TurnPublisher` the runner uses to
+ * publish + close.
+ *
+ * @param turnId - the freshly-created turn id.
+ * @returns the publisher handle.
+ */
+export function openTurnChannel(turnId) {
+    if (channels.has(turnId)) {
+        throw new Error(`Turn ${turnId} already has an open channel.`);
+    }
+    const channel = {
+        lastSeq: -1,
+        closed: false,
+        listeners: new Set(),
+        closeListeners: new Set(),
+        cancelController: new AbortController(),
+    };
+    channels.set(turnId, channel);
+    return {
+        cancelSignal: channel.cancelController.signal,
+        publish(event) {
+            channel.lastSeq = event.seq;
+            for (const listener of channel.listeners) {
+                try {
+                    listener(event);
+                }
+                catch {
+                    /* swallow — a misbehaving listener cannot break the channel */
+                }
+            }
+        },
+        close() {
+            if (channel.closed)
+                return;
+            channel.closed = true;
+            for (const cb of channel.closeListeners) {
+                try {
+                    cb();
+                }
+                catch {
+                    /* ignored */
+                }
+            }
+            channel.closeListeners.clear();
+            // Drop the channel once every subscriber unsubscribed. If nobody is
+            // listening at close time, prune immediately.
+            if (channel.listeners.size === 0) {
+                channels.delete(turnId);
+            }
+        },
+    };
+}
+/**
+ * Subscribes to a live turn channel.
+ *
+ * Returns `null` when the turn is not active (either never opened or
+ * already closed) — the caller should fall back to replaying persisted
+ * events from `turn_events` instead.
+ *
+ * @param turnId - the turn id to attach to.
+ * @param listener - called once per event (with `seq` already assigned).
+ * @param onClose - called once when the channel closes (after final event).
+ * @returns an unsubscribe function, or `null` when the channel is closed.
+ */
+export function subscribeToTurn(turnId, listener, onClose) {
+    const channel = channels.get(turnId);
+    if (!channel || channel.closed)
+        return null;
+    channel.listeners.add(listener);
+    channel.closeListeners.add(onClose);
+    return () => {
+        channel.listeners.delete(listener);
+        channel.closeListeners.delete(onClose);
+        if (channel.closed && channel.listeners.size === 0) {
+            channels.delete(turnId);
+        }
+    };
+}
+/**
+ * Returns `true` when the turn has an open channel right now.
+ *
+ * The chat handler uses this to disambiguate "turn is in flight" from
+ * "turn completed long ago" without having to query the DB twice.
+ */
+export function isTurnLive(turnId) {
+    const channel = channels.get(turnId);
+    return !!channel && !channel.closed;
+}
+/**
+ * Test-only utility — wipes the registry so tests can isolate from each
+ * other. Production code never calls this.
+ */
+export function _resetTurnRegistryForTests() {
+    channels.clear();
+}
+/**
+ * Triggers cancellation of the named turn. The runner is expected to
+ * have wired its run to the publisher's `cancelSignal`; firing it from
+ * here aborts the upstream Letta call and short-circuits the loop.
+ *
+ * Idempotent: calling on a closed / unknown turn is a no-op. The
+ * `POST /chat/:id/cancel` route's user-facing 200 response covers
+ * race-conditions where the turn terminated between the request and
+ * this call.
+ *
+ * @param turnId - the turn to cancel.
+ * @returns `true` if the signal was fired, `false` if the channel is
+ *   closed or unknown.
+ */
+export function requestTurnCancellation(turnId) {
+    const channel = channels.get(turnId);
+    if (!channel || channel.closed)
+        return false;
+    channel.cancelController.abort();
+    return true;
+}
+//# sourceMappingURL=turnRegistry.js.map

package/dist/state/turnRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turnRegistry.js","sourceRoot":"","sources":["../../src/state/turnRegistry.ts"],"names":[],"mappings":"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"}

package/dist/state/turnRunner.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Server-authoritative turn lifecycle (§6.6, §10).
+ *
+ * `runTurn(...)` is the one entry point that:
+ *
+ * 1. Inserts the `turn` row in status=running, phase=model_text.
+ * 2. Opens a live channel (`turnRegistry.openTurnChannel`) so concurrent
+ *    resumption attempts can attach.
+ * 3. Emits `stream_start` (seq 0).
+ * 4. Calls `LettaClient.streamUserMessage(...)` which spawns a Letta
+ *    Code subprocess, acquires the throttle lease, sends the user
+ *    message. Returns a `ChatTurnHandle`.
+ * 5. Iterates the handle's `events` stream:
+ *    - Non-terminal SDK messages → `translateSdkMessage(...)` →
+ *      stamps + persists + broadcasts each emitted ai-hub event.
+ *    - Terminal `result` SDK message → `finalizeTerminal(...)` →
+ *      emits the closing `assistant_message_complete` + `stream_end`
+ *      with the correct reason (`done` / `cancelled` / `error`).
+ * 6. On cancellation (caller signal OR `requestTurnCancellation`):
+ *    calls `handle.abort()` to send `interrupt` to the CLI, keeps
+ *    draining until terminal, then closes.
+ * 7. On throttle rejection (`ServerOverloadedError`): emits
+ *    `error{code:"server_overloaded"}` + `stream_end{error}`.
+ *    Transitions turn → failed.
+ * 8. On unhandled error: emits `error` + `stream_end{error}`,
+ *    `turn.status = "failed"`.
+ * 9. Always calls `handle.close()` in finally (releases subprocess +
+ *    throttle lease).
+ *
+ * @see SPECIFICATIONS.md §6.3.2 — chat / SSE
+ * @see SPECIFICATIONS.md §6.6 — state-machine ownership
+ * @see SPECIFICATIONS.md §6.9 — cancellation
+ * @see SPECIFICATIONS.md §9 — wire protocol
+ * @see SPECIFICATIONS.md §10 — state machine
+ */
+import type { AIHubEvent, TurnStatus } from "@data-club/ai-hub";
+import type { DrizzleDB } from "../db/connection.js";
+import { type LettaClient } from "../letta/client.js";
+import type { Logger } from "../observability/logger.js";
+/** The ai-hub SSE wire-protocol version this server speaks (§9.1). */
+export declare const WIRE_PROTOCOL_VERSION = "1.0";
+/** Parameters for `runTurn`. */
+export interface RunTurnOpts {
+    /** Drizzle handle. */
+    db: DrizzleDB;
+    /** Letta client wrapper (production wraps the SDKs; tests mock). */
+    lettaClient: LettaClient;
+    /** Pino logger for this request. */
+    logger: Logger;
+    /** Per-request id for log correlation (stamped on `error` events). */
+    requestId: string;
+    /** Owner of the session. */
+    userId: string;
+    /** ai-hub session id this turn belongs to. */
+    sessionId: string;
+    /** The Letta conversation id stored on the session row. */
+    lettaConversationId: string;
+    /** The Letta agent id stored on the session row. */
+    lettaAgentId: string;
+    /**
+     * Step-12.5 — absolute path of the per-session sandbox folder, or
+     * `null` when the session has no sandbox (today's stateless shape).
+     * Threaded as `cwd` into the Letta Code subprocess spawn so the
+     * agent's filesystem tools operate inside the seeded folder. When
+     * non-null, also flips the disallowed-tools list to re-enable
+     * `Read` / `Write` / `Bash` / etc.
+     */
+    sandboxDir: string | null;
+    /** The user's typed message. */
+    userMessage: string;
+    /** Optional idempotency key from the request body. */
+    idempotencyKey?: string;
+    /**
+     * Listener that receives every event the runner emits. The chat
+     * handler subscribes its SSE writer here. `null` events signal
+     * "channel closed; no more events coming."
+     */
+    onEvent: (event: AIHubEvent | null) => void;
+    /**
+     * Caller-supplied AbortSignal. When aborted, the runner calls
+     * `handle.abort()` on the spawned Letta Code subprocess and emits
+     * `stream_end{reason:"cancelled"}` after the upstream terminal
+     * `result` arrives.
+     */
+    signal?: AbortSignal;
+}
+/** Returned by `runTurn`. The runner returns after `turn_event`s are committed. */
+export interface RunTurnResult {
+    /** The new turn id (the `turn_id` carried in `stream_start`). */
+    turnId: string;
+    /** Terminal status (`done` / `cancelled` / `failed`). */
+    status: Exclude<TurnStatus, "idle" | "running">;
+}
+/**
+ * Runs one turn from "user pressed Send" to terminal status. Returns a
+ * promise that resolves when the runner has persisted the terminal
+ * event(s), closed the live channel, and torn down the Letta Code
+ * subprocess.
+ *
+ * The caller is expected to keep `onEvent` alive for the entire run.
+ *
+ * @param opts - see `RunTurnOpts`.
+ * @returns the turn id and terminal status.
+ */
+export declare function runTurn(opts: RunTurnOpts): Promise<RunTurnResult>;
+/**
+ * Replays persisted `turn_event` rows newer than `fromSeq`, returned as
+ * ai-hub-shaped events. Used by `GET /chat/:turn_id/events?from_seq=N`
+ * for the replay half of resumption.
+ *
+ * @param db - Drizzle handle.
+ * @param turnId - the turn id.
+ * @param fromSeq - replays events with `seq > fromSeq`.
+ * @returns the persisted events.
+ *
+ * @see SPECIFICATIONS.md §6.3.2 — resumption
+ */
+export declare function replayPersistedEvents(db: DrizzleDB, turnId: string, fromSeq: number): ReadonlyArray<AIHubEvent>;
+/**
+ * Idempotently marks a turn as cancelled in the DB. Returns the row's
+ * resulting status. Called by `POST /chat/:turn_id/cancel` after firing
+ * `requestTurnCancellation`. The runner's catch arm also persists
+ * `cancelled` via `syncTurnRow`; this helper just guarantees the row
+ * is updated when the runner has already exited (terminal-after-cancel
+ * race).
+ *
+ * Does not overwrite `done` / `failed` — those are terminal states.
+ *
+ * @param db - Drizzle handle.
+ * @param turnId - the turn to cancel.
+ * @returns the row's resulting status, or `null` if no such row.
+ */
+export declare function markCancelled(db: DrizzleDB, turnId: string): TurnStatus | null;
+//# sourceMappingURL=turnRunner.d.ts.map

package/dist/state/turnRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turnRunner.d.ts","sourceRoot":"","sources":["../../src/state/turnRunner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAMH,OAAO,KAAK,EACV,UAAU,EAGV,UAAU,EACX,MAAM,mBAAmB,CAAC;AAG3B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAA8C,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AASlG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAGzD,sEAAsE;AACtE,eAAO,MAAM,qBAAqB,QAAQ,CAAC;AAM3C,gCAAgC;AAChC,MAAM,WAAW,WAAW;IAC1B,sBAAsB;IACtB,EAAE,EAAE,SAAS,CAAC;IACd,oEAAoE;IACpE,WAAW,EAAE,WAAW,CAAC;IACzB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,mBAAmB,EAAE,MAAM,CAAC;IAC5B,oDAAoD;IACpD,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,gCAAgC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,KAAK,IAAI,CAAC;IAC5C;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,MAAM,EAAE,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CACjD;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CA4VvE;AAuCD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,SAAS,EACb,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,aAAa,CAAC,UAAU,CAAC,CAa3B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC3B,EAAE,EAAE,SAAS,EACb,MAAM,EAAE,MAAM,GACb,UAAU,GAAG,IAAI,CAenB"}