@data-club/ai-hub-server 0.0.1

package/src/routes/chat.ts

@@ -0,0 +1,534 @@
+/**
+ * `/chat/*` — SSE chat, resumption, cancel (§6.3.2).
+ *
+ * Three endpoints:
+ *
+ * - `POST /chat` — body `{ session_id, user_message, effort?, idempotency_key? }`.
+ *   Streams events per §9. Owner-scoped: the caller must own the
+ *   referenced session.
+ * - `GET  /chat/:turn_id/events?from_seq=N` — resumption: replays
+ *   persisted events with `seq > N`, then live-attaches if the turn is
+ *   still active.
+ * - `POST /chat/:turn_id/cancel` — aborts an in-flight turn. Idempotent
+ *   when the turn already terminated.
+ *
+ * The runner (`state/turnRunner.ts`) owns the actual state machine; this
+ * file is the HTTP/SSE shell. The runner publishes events to a live
+ * channel + persists them; the `POST /chat` writer subscribes to the
+ * same channel and ships bytes to the client. The runner's `onEvent`
+ * callback can write directly; this file uses
+ * `subscribeToTurn` because it shares the same plumbing the resumption
+ * endpoint uses.
+ *
+ * @see SPECIFICATIONS.md §6.3.2 — chat (SSE)
+ * @see SPECIFICATIONS.md §6.6 — server-authoritative state
+ * @see SPECIFICATIONS.md §6.9 — cancellation
+ */
+
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+
+import type { AIHubEvent, TurnStatus } from "@data-club/ai-hub";
+
+import { protectedRoute } from "../auth/middleware.js";
+import { messageOverride, session, turn, turnEvent } from "../db/schema.js";
+import { formatSseEvent, formatSseHeartbeat } from "../handlers/sse.js";
+import {
+  errorResponse,
+  jsonResponse,
+  notFound,
+  validationError,
+} from "../handlers/responses.js";
+import type { RouteHandler } from "../handlers/types.js";
+import {
+  markCancelled,
+  replayPersistedEvents,
+  runTurn,
+  type RunTurnOpts,
+} from "../state/turnRunner.js";
+import {
+  isTurnLive,
+  requestTurnCancellation,
+  subscribeToTurn,
+} from "../state/turnRegistry.js";
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  POST /chat                                                                */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/** Per-message wire body. `effort` is optional with the §7.4 enum. */
+const postChatSchema = z
+  .object({
+    session_id: z.string().uuid(),
+    user_message: z.string().min(1),
+    effort: z
+      .enum(["none", "minimal", "low", "medium", "high", "extra_high"])
+      .optional(),
+    idempotency_key: z.string().min(1).max(255).optional(),
+    /**
+     * Optional tier-3 customization: the human-facing replacement for
+     * `user_message` in the chat UI. When set, AI hub sends
+     * `user_message` to Letta verbatim (system view) but, after the turn
+     * terminates `done`, writes an override row at the position the
+     * persisted user message landed at so subsequent
+     * `GET /sessions/:id/messages` calls display this string instead.
+     *
+     * Persisted only on `done`. On `cancelled` / `failed`, Letta drops
+     * the user message and we drop the override — no orphan row.
+     */
+    user_override: z.string().optional(),
+  })
+  .strict();
+
+/**
+ * `POST /chat` — opens an SSE stream for the new turn.
+ *
+ * Owner-scoped: returns 404 for sessions not owned by the caller. The
+ * `power_user`+ "all-sessions overview" is a different surface.
+ *
+ * The handler returns a `Response` whose body is a `ReadableStream`. The
+ * runner runs in the background, posts events to the registry's live
+ * channel, and the stream subscriber writes them out as `event:`/`data:`
+ * pairs. The runner returns after the stream's terminal event is
+ * persisted; the writer closes the stream shortly after.
+ *
+ * @see SPECIFICATIONS.md §6.3.2
+ * @see SPECIFICATIONS.md §9 — wire protocol
+ */
+export const handlePostChat: RouteHandler = protectedRoute(
+  {},
+  async (req, ctx, auth) => {
+    let raw: unknown;
+    try {
+      raw = await req.json();
+    } catch {
+      return validationError("Request body must be valid JSON.");
+    }
+    const parsed = postChatSchema.safeParse(raw);
+    if (!parsed.success) {
+      const issue = parsed.error.issues[0];
+      return validationError(issue?.message ?? "Invalid request body.");
+    }
+    const body = parsed.data;
+
+    // Owner-scope check.
+    const row = ctx.db
+      .select()
+      .from(session)
+      .where(eq(session.id, body.session_id))
+      .get();
+    if (!row || row.userId !== auth.user.id) return notFound();
+    if (row.isArchived) {
+      return errorResponse(
+        409,
+        "session_archived",
+        "Cannot post to an archived session — unarchive it first.",
+      );
+    }
+
+    // Honor client disconnects: when the request's signal aborts, the
+    // runner's signal aborts too, which closes the upstream Letta call.
+    const requestSignal = req.signal;
+
+    // We need to know the turn id for the response headers. The runner
+    // assigns it at row-insert time; capture it from the `stream_start`
+    // event the runner emits first.
+    const stream = new ReadableStream<Uint8Array>({
+      async start(controller) {
+        let started = false;
+        const writeEvent = (event: AIHubEvent) => {
+          try {
+            controller.enqueue(formatSseEvent(event));
+            started = true;
+          } catch {
+            /* writer was closed (client disconnected) — ignore */
+          }
+        };
+
+        // Periodic heartbeat (§9.1) — every 10 s. Keeps proxies from
+        // closing the connection during long idle phases (tool exec,
+        // 429 wait).
+        const heartbeat = setInterval(() => {
+          try {
+            controller.enqueue(formatSseHeartbeat());
+          } catch {
+            /* writer was closed — clear and bail */
+            clearInterval(heartbeat);
+          }
+        }, 10_000);
+
+        const runnerOpts: RunTurnOpts = {
+          db: ctx.db,
+          lettaClient: ctx.lettaClient,
+          logger: ctx.logger,
+          requestId: (ctx.logger as unknown as { bindings?: () => Record<string, unknown> })
+            .bindings?.()
+            ?.["request_id"] as string ?? "",
+          userId: auth.user.id,
+          sessionId: row.id,
+          lettaConversationId: row.lettaConversationId,
+          lettaAgentId: row.lettaAgentId,
+          sandboxDir: row.sandboxDir,
+          userMessage: body.user_message,
+          ...(body.effort !== undefined ? { effort: body.effort } : {}),
+          ...(body.idempotency_key !== undefined ? { idempotencyKey: body.idempotency_key } : {}),
+          onEvent: (event) => {
+            if (event === null) {
+              clearInterval(heartbeat);
+              try {
+                controller.close();
+              } catch {
+                /* already closed */
+              }
+              return;
+            }
+            writeEvent(event);
+          },
+          signal: requestSignal,
+        };
+
+        // Run the turn. We don't await here — the runner pushes events
+        // via `onEvent`; we keep the stream open until it completes.
+        // But we DO need to catch errors so the stream doesn't dangle if
+        // the runner throws before emitting `stream_end`.
+        //
+        // The `.then` chain handles the tier-3 `user_override` parameter:
+        // after the turn terminates `done`, we list Letta's messages to
+        // find the position the persisted user message landed at, then
+        // upsert an override row so `GET /sessions/:id/messages` will
+        // display `user_override` in place of the wrapped Letta content.
+        // We deliberately don't write on `cancelled` / `failed` — in
+        // those cases Letta drops the user message and a persisted
+        // override would point at nothing.
+        runTurn(runnerOpts)
+          .then(async (result) => {
+            if (result.status !== "done") return;
+            if (body.user_override === undefined) return;
+            try {
+              const messages = await ctx.lettaClient.listMessages(row.lettaConversationId);
+              // Position = chronologically-sorted index of the latest
+              // user_message authored by this caller. Letta is the
+              // source of truth — we don't trust message ordering on
+              // any other axis.
+              const sorted = [...messages].sort((a, b) => {
+                const aT = Date.parse((a as { date?: string }).date ?? "");
+                const bT = Date.parse((b as { date?: string }).date ?? "");
+                if (Number.isNaN(aT) && Number.isNaN(bT)) return 0;
+                if (Number.isNaN(aT)) return 1;
+                if (Number.isNaN(bT)) return -1;
+                return aT - bT;
+              });
+              let position = -1;
+              for (let i = sorted.length - 1; i >= 0; i--) {
+                const msg = sorted[i] as { message_type?: string; sender_id?: string | null };
+                if (msg.message_type === "user_message" && msg.sender_id === auth.user.id) {
+                  position = i;
+                  break;
+                }
+              }
+              if (position < 0) {
+                ctx.logger.warn(
+                  {
+                    event: "user_override_post_turn_no_user_message",
+                    session_id: row.id,
+                  },
+                  "Turn ended `done` but no matching user_message was found in Letta — skipping override write.",
+                );
+                return;
+              }
+              const now = new Date().toISOString();
+              ctx.db
+                .insert(messageOverride)
+                .values({
+                  conversationId: row.lettaConversationId,
+                  ordinalPosition: position,
+                  systemOverride: null,
+                  userOverride: body.user_override,
+                  createdAt: now,
+                  updatedAt: now,
+                })
+                .onConflictDoUpdate({
+                  target: [messageOverride.conversationId, messageOverride.ordinalPosition],
+                  // Merge: only overwrite the user_override layer. Preserve
+                  // any system_override an earlier PUT might have written.
+                  set: { userOverride: body.user_override, updatedAt: now },
+                })
+                .run();
+              ctx.logger.info(
+                {
+                  event: "user_override_post_turn_written",
+                  session_id: row.id,
+                  ordinal_position: position,
+                },
+                "Wrote user_override after successful turn.",
+              );
+            } catch (err) {
+              // Non-fatal: the chat already succeeded. Log and move on.
+              ctx.logger.error(
+                {
+                  event: "user_override_post_turn_failed",
+                  session_id: row.id,
+                  err: err instanceof Error ? err.message : String(err),
+                },
+                "Failed to write user_override post-turn.",
+              );
+            }
+          })
+          .catch((err) => {
+          ctx.logger.error(
+            { event: "turn_runner_threw", err: err instanceof Error ? err.message : String(err) },
+            "Turn runner threw outside the normal lifecycle.",
+          );
+          clearInterval(heartbeat);
+          if (!started) {
+            // No stream_start emitted — close abruptly. The client will
+            // see a connection-error and may retry.
+            try {
+              controller.close();
+            } catch {
+              /* ignored */
+            }
+          }
+        });
+      },
+    });
+
+    return new Response(stream, {
+      status: 200,
+      headers: {
+        "Content-Type": "text/event-stream; charset=utf-8",
+        "Cache-Control": "no-cache, no-transform",
+        "Connection": "keep-alive",
+        "X-Accel-Buffering": "no",
+      },
+    });
+  },
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  GET /chat/:turn_id/events?from_seq=N                                       */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * `GET /chat/:turn_id/events?from_seq=N` — resumption.
+ *
+ * Two-phase:
+ *
+ * 1. Replay persisted `turn_event` rows with `seq > N`, in order.
+ * 2. If the turn is still live, attach to the in-memory broadcaster so
+ *    new events stream through. If the turn is terminal, the response
+ *    closes after the replay.
+ *
+ * Owner-scoped: the caller must own the parent session (the admin
+ * "sessions overview" doesn't go through this endpoint — that's a
+ * separate JSON read).
+ *
+ * @see SPECIFICATIONS.md §6.3.2 — resumption
+ */
+export const handleGetChatEvents: RouteHandler = protectedRoute(
+  {},
+  async (req, ctx, auth, params) => {
+    const turnId = params.turn_id;
+    if (!turnId) return notFound();
+
+    const turnRow = ctx.db.select().from(turn).where(eq(turn.id, turnId)).get();
+    if (!turnRow) return notFound();
+    const sessionRow = ctx.db
+      .select()
+      .from(session)
+      .where(eq(session.id, turnRow.sessionId))
+      .get();
+    if (!sessionRow || sessionRow.userId !== auth.user.id) return notFound();
+
+    const url = new URL(req.url);
+    const fromSeqRaw = url.searchParams.get("from_seq");
+    const fromSeq =
+      fromSeqRaw === null ? -1 : Number.parseInt(fromSeqRaw, 10);
+    if (Number.isNaN(fromSeq)) {
+      return validationError("from_seq must be an integer.", "invalid_from_seq");
+    }
+
+    const requestSignal = req.signal;
+    const turnIsLive = isTurnLive(turnId);
+
+    const stream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        let closed = false;
+        const safeWrite = (event: AIHubEvent) => {
+          if (closed) return;
+          try {
+            controller.enqueue(formatSseEvent(event));
+          } catch {
+            closed = true;
+          }
+        };
+        const safeClose = () => {
+          if (closed) return;
+          closed = true;
+          try {
+            controller.close();
+          } catch {
+            /* ignored */
+          }
+        };
+
+        // Phase 1 — replay every persisted event with seq > fromSeq.
+        const replayed = replayPersistedEvents(ctx.db, turnId, fromSeq);
+        let highestSeqWritten = fromSeq;
+        for (const event of replayed) {
+          safeWrite(event);
+          if (event.seq > highestSeqWritten) highestSeqWritten = event.seq;
+        }
+
+        // Phase 2 — live-attach (only if the turn is still running).
+        if (!turnIsLive) {
+          safeClose();
+          return;
+        }
+
+        const unsubscribe = subscribeToTurn(
+          turnId,
+          (event) => {
+            // De-duplicate against the replay window. Events with seq <=
+            // highestSeqWritten were either already replayed or are stale
+            // re-broadcasts; the runner never re-emits, but we guard
+            // defensively.
+            if (event.seq <= highestSeqWritten) return;
+            highestSeqWritten = event.seq;
+            safeWrite(event);
+          },
+          () => {
+            safeClose();
+          },
+        );
+
+        if (!unsubscribe) {
+          // Turn went terminal between our `isTurnLive` check and
+          // subscription. Re-read any events that arrived in the gap
+          // and close.
+          const tail = replayPersistedEvents(ctx.db, turnId, highestSeqWritten);
+          for (const event of tail) safeWrite(event);
+          safeClose();
+          return;
+        }
+
+        const onAbort = () => {
+          unsubscribe();
+          safeClose();
+        };
+        if (requestSignal.aborted) onAbort();
+        else requestSignal.addEventListener("abort", onAbort, { once: true });
+      },
+    });
+
+    return new Response(stream, {
+      status: 200,
+      headers: {
+        "Content-Type": "text/event-stream; charset=utf-8",
+        "Cache-Control": "no-cache, no-transform",
+        "Connection": "keep-alive",
+        "X-Accel-Buffering": "no",
+      },
+    });
+  },
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  POST /chat/:turn_id/cancel                                                */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * `POST /chat/:turn_id/cancel` — aborts an in-flight turn authoritatively.
+ *
+ * Owner-scoped via the parent session. Idempotent — calling it on a
+ * terminal turn returns the same envelope as the first call (no error,
+ * the existing status is reported as `already_terminal`).
+ *
+ * Two cancellation paths fire here, in order:
+ *
+ * 1. **Letta-side cancel** — `client.agents.messages.cancel({ run_ids })`.
+ *    This is the load-bearing one: it tells Letta to stop the run
+ *    server-side and roll back the in-progress step from the
+ *    conversation history (completed steps survive). **Without this,
+ *    aborting only our SDK call's HTTP connection does nothing** —
+ *    Letta keeps generating, persists the full output, and the user's
+ *    refresh reveals it. Empirically verified.
+ *
+ * 2. **Local registry cancel** — `requestTurnCancellation(turnId)`. Fires
+ *    our runner's AbortSignal so the in-process for-await loop exits
+ *    cleanly + emits `stream_end{reason:"cancelled"}`. Also serves as
+ *    the fallback when (1) fails (network blip, Letta-side error, run
+ *    already terminal): the client still gets a clean terminal event.
+ *
+ * Race-free ordering: we fire (1) first so Letta has begun winding the
+ * run down by the time (2) fires; the few final events Letta delivers
+ * during that window flow through the runner's stream naturally before
+ * the abort lands.
+ *
+ * @see SPECIFICATIONS.md §6.3.2
+ * @see SPECIFICATIONS.md §6.9 — cancellation
+ */
+export const handlePostChatCancel: RouteHandler = protectedRoute(
+  {},
+  async (_req, ctx, auth, params) => {
+    const turnId = params.turn_id;
+    if (!turnId) return notFound();
+
+    const turnRow = ctx.db.select().from(turn).where(eq(turn.id, turnId)).get();
+    if (!turnRow) return notFound();
+    const sessionRow = ctx.db
+      .select()
+      .from(session)
+      .where(eq(session.id, turnRow.sessionId))
+      .get();
+    if (!sessionRow || sessionRow.userId !== auth.user.id) return notFound();
+
+    if (turnRow.status !== "running") {
+      return jsonResponse(200, {
+        turn_id: turnId,
+        status: turnRow.status,
+        was_already_terminal: true,
+      });
+    }
+
+    // Cancel via the runner's `ChatTurnHandle.abort()` —
+    // `requestTurnCancellation` fires the registry's AbortController,
+    // the runner listens for it and translates into a Letta-Code-SDK
+    // `session.abort()` call (which sends `interrupt` to the spawned
+    // CLI subprocess). Pre-migration this also called Letta server's
+    // `agents.messages.cancel({run_ids})` directly via a captured
+    // `lettaRunId`; the SDK abstracts that now and we no longer
+    // thread run-ids through the runner. See migration §4.2.
+    //
+    // Behavioral caveat (migration §7 open question 5): if the spawned
+    // CLI is mid-tool-execution, the interrupt may be queued, not
+    // honored, and the tool runs to completion. The runner emits
+    // `stream_end{cancelled}` regardless once the upstream terminal
+    // result lands, so the React client gets a clean cancel event
+    // even when the run effectively completed.
+    const aborted = requestTurnCancellation(turnId);
+    let finalStatus: TurnStatus = turnRow.status;
+    if (!aborted) {
+      const fresh = ctx.db.select().from(turn).where(eq(turn.id, turnId)).get();
+      finalStatus = fresh?.status ?? "cancelled";
+    } else {
+      finalStatus = "cancelled";
+      markCancelled(ctx.db, turnId);
+    }
+    return jsonResponse(200, {
+      turn_id: turnId,
+      status: finalStatus,
+      was_already_terminal: false,
+    });
+  },
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Re-exports                                                                */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+// Re-exported here for the tests that exercise the persisted-event log
+// directly without going through HTTP.
+export { replayPersistedEvents };
+// Used by integration tests that need to read turn_event rows directly.
+export { turnEvent };

package/src/routes/featureToggles.ts

@@ -0,0 +1,52 @@
+/**
+ * `GET /feature-toggles` — public read of the deployment-wide UI feature
+ * toggles set by `super_admin` (§8.4).
+ *
+ * Unlike `/admin/settings/feature-toggles`, this endpoint is **unauthenticated**
+ * — every page-load can fetch it before login completes, and every role can
+ * read it after login. The blob itself is non-sensitive: it controls which
+ * UI affordances render in the chat shell, not any data. Keeping the read
+ * public matches the precedence rule in §8.4 ("server toggle > React prop >
+ * built-in default") — the toggles need to apply at render time on every
+ * user's UI, not only super_admin's. Writes remain super_admin-only via
+ * `PATCH /admin/settings/feature-toggles`.
+ *
+ * Missing keys are returned as absent in the response (not coerced to false)
+ * so the client can distinguish "explicitly off" from "fall through to the
+ * React prop default."
+ *
+ * @see SPECIFICATIONS.md §8.4 — feature toggles
+ * @see ui-sketches/08-admin-settings.md — feature_toggles_section
+ */
+
+import { eq } from "drizzle-orm";
+
+import { adminSetting } from "../db/schema.js";
+import { internalError, jsonResponse } from "../handlers/responses.js";
+import type { RouteHandler } from "../handlers/types.js";
+
+/**
+ * `GET /feature-toggles` — returns `{ feature_toggles: {...} }`.
+ *
+ * No auth required. Every authenticated AND unauthenticated request gets
+ * the same response. CORS is governed by the framework wrapper; the handler
+ * itself only writes JSON.
+ *
+ * @param _req - the inbound request (unused).
+ * @param ctx - the server context.
+ * @returns 200 with the toggles blob, or 500 if the singleton row is missing.
+ */
+export const handleGetPublicFeatureToggles: RouteHandler = async (
+  _req,
+  ctx,
+) => {
+  const row = ctx.db
+    .select()
+    .from(adminSetting)
+    .where(eq(adminSetting.id, 1))
+    .get();
+  if (!row) return internalError();
+  return jsonResponse(200, {
+    feature_toggles: row.featureToggles ?? {},
+  });
+};

package/src/routes/health.ts

@@ -0,0 +1,44 @@
+/**
+ * `/health` and `/health/ready` handlers.
+ *
+ * Step 2 ships the basic shapes:
+ *
+ * - `/health` — pure liveness, no checks. Returns 200 always (the process is
+ *   up; that's the only signal a liveness probe needs).
+ * - `/health/ready` — readiness. Step 2 checks DB reachability via a trivial
+ *   `SELECT 1`. **Letta reachability is intentionally NOT checked here** —
+ *   the Letta SDK comes online in Step 5, which extends this handler.
+ *
+ * @see SPECIFICATIONS.md §6.3.5 — health endpoints
+ */
+
+import { jsonResponse, errorResponse } from "../handlers/responses.js";
+import type { RouteHandler } from "../handlers/types.js";
+
+/** `GET /health` — returns 200 with a static body. */
+export const handleHealth: RouteHandler = async () =>
+  jsonResponse(200, { status: "ok" });
+
+/**
+ * `GET /health/ready` — runs each readiness probe in turn. Returns 503
+ * with the first failing probe's name on any failure.
+ *
+ * Step 2 checks `db`. Step 5 will append `letta`.
+ */
+export const handleHealthReady: RouteHandler = async (_req, ctx) => {
+  try {
+    ctx.sqlite.prepare("SELECT 1 AS ok").get();
+  } catch (err) {
+    ctx.logger.error(
+      { component: "db", err: errMessage(err) },
+      "Readiness probe failed: db unreachable.",
+    );
+    return errorResponse(503, "not_ready", "Database unreachable");
+  }
+  return jsonResponse(200, { status: "ready", checks: { db: "ok" } });
+};
+
+/** Extracts a string for logging from any thrown value. */
+function errMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}