@data-club/ai-hub-server 0.0.1

package/src/handlers/routeTable.ts

@@ -0,0 +1,188 @@
+/**
+ * Canonical route table.
+ *
+ * Order matters — the matcher walks top-to-bottom and returns the first
+ * pattern that matches. Concrete paths come before any future wildcards.
+ *
+ * Entries are paired with the step that wires the real handler. After Step 5
+ * every endpoint is real; no stubs remain.
+ *
+ * @see SPECIFICATIONS.md §6.3 — API surface
+ * @see docs/IMPLEMENTATION_PLAN.md — per-endpoint step assignment
+ */
+
+import { handleListAgents as handleListAgentsUser } from "../routes/agents.js";
+import { handleGetPublicFeatureToggles } from "../routes/featureToggles.js";
+import {
+  handleCreateAgent,
+  handleListAgents as handleListAgentsAdmin,
+  handlePatchAgent,
+} from "../routes/admin/agents.js";
+import {
+  handleListSessionsOverview,
+  handlePurgeAdminSessionSandbox,
+} from "../routes/admin/sessions.js";
+import {
+  handleCreateRotatingMessage,
+  handleListRotatingMessages,
+  handlePatchRotatingMessage,
+  handleRotateRotatingMessageNow,
+} from "../routes/admin/rotatingMessages.js";
+import {
+  handleGetFeatureToggles,
+  handleGetSettings,
+  handlePatchFeatureToggles,
+  handlePatchSettings,
+  handleRotateMetricsToken,
+  handleRotateSigningKey,
+} from "../routes/admin/settings.js";
+import {
+  handleCreateUser,
+  handleDeleteUser,
+  handleListUsers,
+  handlePatchUserRole,
+  handleResetUserPassword,
+} from "../routes/admin/users.js";
+import {
+  handleChangePassword,
+  handleLogin,
+  handleLogout,
+  handleMe,
+  handleMePreferences,
+} from "../routes/auth.js";
+import { handleHealth, handleHealthReady } from "../routes/health.js";
+import { handleMetrics } from "../routes/metrics.js";
+import {
+  handleGetChatEvents,
+  handlePostChat,
+  handlePostChatCancel,
+} from "../routes/chat.js";
+import {
+  handleAdminGetSessionMessages,
+  handleCreateSession,
+  handleDeleteMessageOverride,
+  handleGetSession,
+  handleGetSessionMessages,
+  handleListMessageOverrides,
+  handleListSessions,
+  handlePatchSession,
+  handlePatchSessionReasoning,
+  handlePutMessageOverride,
+} from "../routes/sessions.js";
+
+import type { RouteEntry } from "./types.js";
+
+/**
+ * Reads as the canonical Step-5 surface in one place. Step 6 adds no new
+ * routes — it extends the chat path with TPM-recovery internals.
+ *
+ * @returns the immutable route table.
+ */
+export function buildRouteTable(): ReadonlyArray<RouteEntry> {
+  return [
+    // Health probes — public.
+    { method: "GET", path: "/health", handler: handleHealth },
+    { method: "GET", path: "/health/ready", handler: handleHealthReady },
+
+    // Auth — full surface after Step 3.
+    { method: "POST", path: "/auth/login", handler: handleLogin },
+    { method: "POST", path: "/auth/change-password", handler: handleChangePassword },
+    { method: "POST", path: "/auth/logout", handler: handleLogout },
+    { method: "GET", path: "/auth/me", handler: handleMe },
+    { method: "PATCH", path: "/auth/me/preferences", handler: handleMePreferences },
+
+    // Public — Step 10 (deployment-wide UI feature toggles per §8.4).
+    { method: "GET", path: "/feature-toggles", handler: handleGetPublicFeatureToggles },
+
+    // User-facing — Step 4.
+    { method: "GET", path: "/agents", handler: handleListAgentsUser },
+    { method: "GET", path: "/sessions", handler: handleListSessions },
+    { method: "POST", path: "/sessions", handler: handleCreateSession },
+    { method: "GET", path: "/sessions/:id", handler: handleGetSession },
+    { method: "PATCH", path: "/sessions/:id", handler: handlePatchSession },
+    {
+      method: "PATCH",
+      path: "/sessions/:id/reasoning",
+      handler: handlePatchSessionReasoning,
+    },
+    { method: "GET", path: "/sessions/:id/messages", handler: handleGetSessionMessages },
+    {
+      method: "GET",
+      path: "/sessions/:id/message-overrides",
+      handler: handleListMessageOverrides,
+    },
+    {
+      method: "PUT",
+      path: "/sessions/:id/message-overrides/:position",
+      handler: handlePutMessageOverride,
+    },
+    {
+      method: "DELETE",
+      path: "/sessions/:id/message-overrides/:position",
+      handler: handleDeleteMessageOverride,
+    },
+
+    // Chat — Step 5 (SSE wire protocol per §9).
+    { method: "POST", path: "/chat", handler: handlePostChat },
+    { method: "GET", path: "/chat/:turn_id/events", handler: handleGetChatEvents },
+    { method: "POST", path: "/chat/:turn_id/cancel", handler: handlePostChatCancel },
+
+    // Admin — Step 4.
+    { method: "GET", path: "/admin/users", handler: handleListUsers },
+    { method: "POST", path: "/admin/users", handler: handleCreateUser },
+    { method: "PATCH", path: "/admin/users/:id/role", handler: handlePatchUserRole },
+    { method: "POST", path: "/admin/users/:id/reset-password", handler: handleResetUserPassword },
+    { method: "DELETE", path: "/admin/users/:id", handler: handleDeleteUser },
+    { method: "GET", path: "/admin/agents", handler: handleListAgentsAdmin },
+    { method: "POST", path: "/admin/agents", handler: handleCreateAgent },
+    { method: "PATCH", path: "/admin/agents/:id", handler: handlePatchAgent },
+    {
+      method: "GET",
+      path: "/admin/rotating-messages",
+      handler: handleListRotatingMessages,
+    },
+    {
+      method: "POST",
+      path: "/admin/rotating-messages",
+      handler: handleCreateRotatingMessage,
+    },
+    {
+      method: "PATCH",
+      path: "/admin/rotating-messages/:id",
+      handler: handlePatchRotatingMessage,
+    },
+    {
+      method: "POST",
+      path: "/admin/rotating-messages/:id/rotate-now",
+      handler: handleRotateRotatingMessageNow,
+    },
+    { method: "GET", path: "/admin/sessions", handler: handleListSessionsOverview },
+    {
+      method: "GET",
+      path: "/admin/sessions/:id/messages",
+      handler: handleAdminGetSessionMessages,
+    },
+    {
+      method: "POST",
+      path: "/admin/sessions/:id/purge-sandbox",
+      handler: handlePurgeAdminSessionSandbox,
+    },
+    { method: "GET", path: "/admin/settings", handler: handleGetSettings },
+    { method: "PATCH", path: "/admin/settings", handler: handlePatchSettings },
+    { method: "GET", path: "/admin/settings/feature-toggles", handler: handleGetFeatureToggles },
+    { method: "PATCH", path: "/admin/settings/feature-toggles", handler: handlePatchFeatureToggles },
+    {
+      method: "POST",
+      path: "/admin/settings/rotate-signing-key",
+      handler: handleRotateSigningKey,
+    },
+    {
+      method: "POST",
+      path: "/admin/settings/rotate-metrics-token",
+      handler: handleRotateMetricsToken,
+    },
+
+    // Metrics — Step 4 (bearer-token-gated, no JWT).
+    { method: "GET", path: "/metrics", handler: handleMetrics },
+  ];
+}

package/src/handlers/router.ts

@@ -0,0 +1,96 @@
+/**
+ * Tiny path + method matcher.
+ *
+ * Lives in-package — we explicitly do NOT depend on Hono / Express /
+ * Fastify (§6.2). The route table is flat, the patterns are simple, and a
+ * 50-line matcher beats a 500 KB framework runtime that brings its own
+ * plugin ecosystem we wouldn't use.
+ *
+ * Pattern syntax: `/sessions/:id` matches `/sessions/abc` and exposes
+ * `{ id: "abc" }` as the parameter map. The matcher does not support globs
+ * or regex — every spec'd route is a plain segment-by-segment match.
+ *
+ * The `*` method is the wildcard used by `OPTIONS` preflight handlers and
+ * the catch-all 404. First-registered-first-matched, so wildcards always go
+ * at the bottom of the table.
+ *
+ * @see SPECIFICATIONS.md §6.2 — stack (no framework runtime)
+ */
+
+import type { RouteEntry } from "./types.js";
+
+/** A successful match's output. */
+export interface MatchResult {
+  /** The handler to invoke. */
+  entry: RouteEntry;
+  /** Path-parameter map (e.g. `{ id: "abc" }`). */
+  params: Record<string, string>;
+}
+
+/**
+ * Walks `entries` in order and returns the first one whose method + path
+ * pattern match `method` and `pathname`. Returns `null` if nothing matches.
+ *
+ * @param entries - the route table.
+ * @param method - request method (uppercased).
+ * @param pathname - request path with the basePath already stripped.
+ * @returns the matched entry + params, or `null`.
+ */
+export function matchRoute(
+  entries: ReadonlyArray<RouteEntry>,
+  method: string,
+  pathname: string,
+): MatchResult | null {
+  for (const entry of entries) {
+    if (entry.method !== "*" && entry.method !== method) continue;
+    const params = matchPath(entry.path, pathname);
+    if (params) return { entry, params };
+  }
+  return null;
+}
+
+/**
+ * Compares a path template (with `:param` placeholders) against an actual
+ * pathname. Returns the parameter map on a match, `null` otherwise.
+ *
+ * Trailing slashes are tolerated — `/foo/` matches `/foo`.
+ *
+ * @param template - the route template (e.g. `/sessions/:id`).
+ * @param pathname - the actual path being matched.
+ * @returns parameter map on a match, else `null`.
+ */
+function matchPath(
+  template: string,
+  pathname: string,
+): Record<string, string> | null {
+  const tplParts = trimSlashes(template).split("/");
+  const pathParts = trimSlashes(pathname).split("/");
+  if (tplParts.length !== pathParts.length) return null;
+
+  const params: Record<string, string> = {};
+  for (let i = 0; i < tplParts.length; i++) {
+    const tp = tplParts[i] as string;
+    const pp = pathParts[i] as string;
+    if (tp.startsWith(":")) {
+      const name = tp.slice(1);
+      params[name] = decodeURIComponent(pp);
+      continue;
+    }
+    if (tp !== pp) return null;
+  }
+  return params;
+}
+
+/**
+ * Trims a single leading and trailing `/` so `split("/")` yields the same
+ * segment count regardless of slash style.
+ *
+ * @param s - the path or template string.
+ * @returns the input with one leading/trailing slash removed.
+ */
+function trimSlashes(s: string): string {
+  let out = s;
+  if (out.startsWith("/")) out = out.slice(1);
+  if (out.endsWith("/")) out = out.slice(0, -1);
+  return out;
+}

package/src/handlers/sse.ts

@@ -0,0 +1,55 @@
+/**
+ * Small SSE writer helpers.
+ *
+ * The chat handler builds a `ReadableStream` of bytes and pipes named
+ * events into it. This file holds the encoding (utf-8 + `event:`/`data:`
+ * lines) and a `formatSseEvent` helper so the writer stays in one place.
+ *
+ * @see SPECIFICATIONS.md §9.5 — why SSE (not EventSource)
+ */
+
+import type { AIHubEvent } from "@data-club/ai-hub";
+
+/**
+ * Formats one ai-hub event into the byte payload an SSE client expects.
+ *
+ * Format per the W3C EventSource spec:
+ *
+ * ```
+ * event: <event-name>
+ * data: <json-payload>
+ *
+ * ```
+ *
+ * The blank line separator is required. Multi-line payloads get one
+ * `data:` line per newline; we shouldn't see any in practice (the events
+ * we emit are flat JSON), but the helper handles it defensively.
+ *
+ * @param event - the ai-hub event.
+ * @returns the SSE-formatted bytes.
+ */
+export function formatSseEvent(event: AIHubEvent): Uint8Array {
+  // `heartbeat` events carry no `data` per the wire-protocol union — for
+  // every other variant `data` is present. We pull it out with a narrowing
+  // `in` check so we don't include `data: undefined` in the wire payload
+  // when there's nothing to send.
+  const payload = JSON.stringify({
+    seq: event.seq,
+    ...("data" in event ? { data: event.data } : {}),
+    state: event.state,
+  });
+  const dataLines = payload.split("\n").map((l) => `data: ${l}`).join("\n");
+  const text = `event: ${event.event}\n${dataLines}\n\n`;
+  return new TextEncoder().encode(text);
+}
+
+/**
+ * Formats a plain SSE comment-line (used for heartbeats). Browsers and
+ * proxies treat any line starting with `:` as a comment — keeps the
+ * connection alive without delivering an event to the consumer.
+ *
+ * @returns the bytes of a `:hb\n\n` heartbeat.
+ */
+export function formatSseHeartbeat(): Uint8Array {
+  return new TextEncoder().encode(":hb\n\n");
+}

package/src/handlers/types.ts

@@ -0,0 +1,104 @@
+/**
+ * Shared types for the Fetch routing core.
+ *
+ * `AIHubServerContext` is the per-server-instance bundle: DB, logger, parsed
+ * encryption key, route prefix. Subsequent steps extend it (Letta client,
+ * mock-Letta toggle, etc.) — additions are additive.
+ *
+ * Handlers are Web-Standard `(Request, ctx) => Promise<Response>` per §6.2.
+ * No framework runtime, no plugin ecosystem.
+ *
+ * @see SPECIFICATIONS.md §6.2 — stack
+ */
+
+import type Database from "better-sqlite3";
+
+import type { DrizzleDB } from "../db/connection.js";
+import type { LettaClient } from "../letta/client.js";
+import type { SubprocessThrottle } from "../letta/subprocessThrottle.js";
+import type { Logger } from "../observability/logger.js";
+
+/** Per-server-instance context wired by `createFetchHandler`. */
+export interface AIHubServerContext {
+  /** Drizzle client typed against the schema — call this for typed queries. */
+  db: DrizzleDB;
+  /** Raw better-sqlite3 handle — used only for `transaction()` + low-level ops. */
+  sqlite: Database.Database;
+  /** Pino logger with redaction applied. */
+  logger: Logger;
+  /** Parsed `AI_HUB_ENCRYPTION_KEY` (32 bytes). */
+  encryptionKey: Buffer;
+  /**
+   * The route prefix (default `/api/ai-hub`). The matcher peels this off
+   * before pattern-matching. Set via `createFetchHandler({ basePath })`.
+   */
+  basePath: string;
+  /**
+   * Project-shaped Letta client (§6.4). The handler imports types from
+   * `letta/client.ts` and calls this for every Letta interaction —
+   * **never raw HTTP**. Tests inject a mock via
+   * `createFetchHandler({ lettaClient })`.
+   */
+  lettaClient: LettaClient;
+  /**
+   * Per-process throttle that gates Letta Code subprocess spawning. The chat
+   * route's `streamUserMessage` path calls `acquire()` before spawning and
+   * `release()` in the finally; if acquire throws `ServerOverloadedError`
+   * the route returns HTTP 503 with an `error {server_overloaded}` SSE
+   * event. The throttle is per-server-instance (the live-count counter is
+   * in-memory) and is constructed once in `createFetchHandler` from env-
+   * derived config. Tests can inject a configured-for-the-test instance.
+   *
+   * @see ../letta/subprocessThrottle.ts
+   */
+  subprocessThrottle: SubprocessThrottle;
+  /**
+   * Env-var record used as the fallback source for the Letta API key when
+   * the `admin_setting.letta_api_key_encrypted` column is empty (see
+   * `letta/client.ts:resolveApiKey` for the precedence). Production passes
+   * `process.env`; tests pass the synthesized record they boot with so
+   * the fallback behavior is exercisable without touching the real
+   * environment.
+   */
+  envSource: Record<string, string | undefined>;
+  /**
+   * Step-12.5 — absolute base directory holding `seeds/` and `sandboxes/`.
+   * Resolved once by `resolveFilesDir(env)` at boot from
+   * `AI_HUB_FILES_DIR` (or the `${AI_HUB_DATA_DIR}/files` fallback) and
+   * threaded through every route that touches sandbox dirs: the admin
+   * agents validator (seed existence check), `POST /sessions`
+   * (seed → sandbox copy), and `POST /admin/sessions/:id/purge-sandbox`.
+   *
+   * @see ../letta/sandbox.ts
+   * @see docs/server/session-sandboxes.md
+   */
+  filesDir: string;
+}
+
+/**
+ * The shape every route handler implements. Mirrors the Web-Standard fetch
+ * function signature plus the per-instance context bundle and the matched
+ * path parameters.
+ *
+ * `params` is keyed by the `:name` placeholders in the route template — e.g.
+ * `/admin/users/:id/role` yields `{ id: "abc" }`. Handlers that don't use
+ * params can simply omit the third argument (TypeScript bivariance allows it).
+ */
+export type RouteHandler = (
+  req: Request,
+  ctx: AIHubServerContext,
+  params: Readonly<Record<string, string>>,
+) => Promise<Response>;
+
+/** A path-aware handler entry consumed by the matcher. */
+export interface RouteEntry {
+  /** Uppercase HTTP method, or `"*"` to match any. */
+  method: string;
+  /**
+   * Path template with `:param` placeholders (e.g. `/sessions/:id`). Matched
+   * against the request path *after* the `basePath` prefix has been peeled.
+   */
+  path: string;
+  /** The handler. */
+  handler: RouteHandler;
+}

package/src/index.ts

@@ -0,0 +1,60 @@
+/**
+ * Public entry point for `@data-club/ai-hub-server`.
+ *
+ * Step 2 ships:
+ *
+ * - `createFetchHandler({...})` — the canonical Web-Standard Fetch entry point.
+ * - `createNextRouteHandler({...})` — first-class Next.js App Router adapter.
+ * - `bootServer({...})` — convenience: env → DB → migrate → seed → handler.
+ * - The shared types re-exported from `@data-club/ai-hub`.
+ *
+ * Subsequent steps add: full `/auth/*` + role middleware (Step 3), `/admin/*`
+ * + `/sessions` + `/agents` + `/metrics` (Step 4), Letta integration + `/chat`
+ * SSE (Step 5), TPM recovery (Step 6).
+ *
+ * @see SPECIFICATIONS.md §6 — server responsibilities
+ * @see SPECIFICATIONS.md §6.2 — stack
+ * @see docs/IMPLEMENTATION_PLAN.md — step-by-step delivery schedule
+ */
+
+export type {
+  AIHubRole,
+  AIHubUser,
+  Session,
+  AIHubMessage,
+  TurnStatus,
+  RunningPhase,
+  AIHubState,
+  AIHubEventState,
+  AIHubEvent,
+  AIHubError,
+} from "@data-club/ai-hub";
+
+export {
+  createFetchHandler,
+  type CreateFetchHandlerOptions,
+  type FetchHandler,
+} from "./handlers/fetch.js";
+
+export { createNextRouteHandler } from "./handlers/nextjs.js";
+
+export {
+  bootServer,
+  parseEnvConfig,
+  type BootServerOptions,
+  type BootedServer,
+  type EnvConfig,
+  type EnvLike,
+} from "./bootstrap.js";
+
+export {
+  SUPER_ADMIN_SEED_PASSWORD,
+  SUPER_ADMIN_SEED_USERNAME,
+} from "./db/seed.js";
+
+export {
+  createDefaultLettaClient,
+  type CreateLettaClientDeps,
+  type LettaClient,
+  type StreamUserMessageOpts,
+} from "./letta/client.js";