@data-club/ai-hub 0.0.1

package/src/client/AIHubClient.ts

@@ -0,0 +1,1718 @@
+/**
+ * `AIHubClient` — the typed TypeScript SDK for `@data-club/ai-hub-server`.
+ *
+ * Used internally by `<AIHubProvider>` to power every component in the
+ * library; also exported for apps that build entirely custom UIs without
+ * the React layer (§7.8).
+ *
+ * Design notes:
+ *
+ * - **Wire is snake_case; SDK arguments are camelCase.** The translation is
+ *   per-method and explicit so the reader can see exactly which fields cross
+ *   the boundary. The only header-level camelCase translation is on
+ *   `login()`'s response: `must_change_password` → `mustChangePassword`
+ *   (per §6.3.4). `user.*` and `deployment.*` keep their snake_case keys —
+ *   they're echoed through to React state and the BEM CSS contract is
+ *   already snake_case-aware.
+ * - **SSE uses `fetch` + `ReadableStream`, not `EventSource`** (§9.5 — the
+ *   browser API can't carry custom auth headers).
+ * - **No silent refresh** (§6.7). A 401 on any protected request fires the
+ *   `onUnauthorized` callback exactly once; the provider then routes the
+ *   user back to `<DataClubAIHubLogin />`.
+ * - **Empty-title rejection on `createSession`** is enforced client-side
+ *   before the request goes out so we don't burn an HTTP round-trip on a
+ *   case the server will 400 anyway.
+ *
+ * @see SPECIFICATIONS.md §7.8 — client SDK
+ * @see SPECIFICATIONS.md §6.3  — API surface
+ * @see SPECIFICATIONS.md §6.7  — auth model
+ */
+
+import type {
+  AIHubAuthContext,
+  AIHubDeployment,
+  AIHubError,
+  AIHubEvent,
+  AIHubFeatureToggles,
+  AIHubMessage,
+  AIHubMessageOverride,
+  AIHubRole,
+  AIHubUser,
+  Session,
+} from "../types.js";
+
+import { parseSseStream } from "./sseParser.js";
+import {
+  resolveTokenStorage,
+  type TokenStorage,
+  type TokenStorageMode,
+} from "./tokenStorage.js";
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Public shapes                                                              */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Constructor options for `AIHubClient`.
+ */
+export interface AIHubClientOptions {
+  /**
+   * Base URL the server is mounted at — typically `/api/ai-hub` in a
+   * per-customer wrapper (§5). No trailing slash; the client appends paths.
+   */
+  baseUrl: string;
+  /**
+   * Custom `fetch`. Defaults to `globalThis.fetch`. Override for tests or
+   * for non-DOM environments (Workers, Bun, etc.).
+   */
+  fetch?: typeof fetch;
+  /**
+   * How to persist the JWT. Either one of the three built-in modes or a
+   * custom adapter. Defaults to `"localStorage"`.
+   */
+  tokenStorage?: TokenStorageMode | TokenStorage;
+  /**
+   * Fired when the server returns 401 on a protected request — the provider
+   * uses this to route back to login (§6.7 — no silent refresh in v1).
+   * The token is cleared before the callback fires.
+   */
+  onUnauthorized?: () => void;
+}
+
+/**
+ * Response shape returned by `login()`. The `deployment` block is omitted
+ * when `mustChangePassword === true` (the change-only token grants no
+ * deployment access — §6.3.4).
+ */
+export interface LoginResponse {
+  /** The bearer token. Either a 24 h session JWT or a 5 min change-only JWT. */
+  token: string;
+  /**
+   * True when the user must call `changePassword` before any other endpoint
+   * will accept the token. Camelcased from the wire's `must_change_password`.
+   */
+  mustChangePassword: boolean;
+  /** The authenticated user (per-user identity). */
+  user: AIHubUser;
+  /** Per-deployment context. Absent when `mustChangePassword === true`. */
+  deployment?: AIHubDeployment;
+}
+
+/** Filter args for `listSessions`. */
+export interface ListSessionsOptions {
+  /** The ai-hub agent the sessions belong to. Required (§6.3.1). */
+  agentId: string;
+  /** Surface archived rows as well. Defaults to false. */
+  includeArchived?: boolean;
+}
+
+/** Body for `createSession`. */
+export interface CreateSessionOptions {
+  /** The ai-hub agent the new session is scoped to. */
+  agentId: string;
+  /** The user-entered chat title. 1..80 chars; empty is rejected client-side. */
+  title: string;
+}
+
+/** Body for `patchSession`. Either or both fields may be supplied. */
+export interface PatchSessionOptions {
+  /** New title (1..80 chars). */
+  title?: string;
+  /** New archive state. */
+  isArchived?: boolean;
+}
+
+/**
+ * Body for `patchSessionReasoning`. Fields are independent — the UI may
+ * send just the one the user changed. `null` explicitly clears a field
+ * (back to agent default); omitting it keeps the existing value.
+ *
+ * Enum values depend on the agent's model — server-side validation is
+ * intentionally loose so this layer stays schema-driven. The actual
+ * rejection (if any) happens when Letta receives the patched `model_settings`
+ * before the next turn.
+ */
+export interface PatchSessionReasoningOptions {
+  /** Anthropic/Bedrock-shape effort OR OpenAI-shape reasoning_effort — handled the same here. */
+  effort?: string | null;
+  /** OpenAI verbosity. */
+  verbosity?: string | null;
+  /** Google numeric thinking budget. */
+  thinkingBudget?: number | null;
+}
+
+/** Reasoning-effort enum (§7.4). `none` means no reasoning at all. */
+export type AIHubEffort =
+  | "none"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "extra_high";
+
+/** Body for `streamChat`. */
+export interface StreamChatBody {
+  /** The ai-hub session id the message is being posted to. */
+  sessionId: string;
+  /** The user's message text. Non-empty per the server's Zod schema. */
+  userMessage: string;
+  /** Per-message reasoning effort (§7.4). */
+  effort?: AIHubEffort;
+  /**
+   * Allows reconnecting to the same turn from a different connection;
+   * see §6.3.2.
+   */
+  idempotencyKey?: string;
+  /**
+   * Optional tier-3 customization: the human-facing replacement to show
+   * in the chat transcript at the position the new user message lands
+   * at. When set, the server sends `userMessage` to Letta verbatim
+   * (system view), then — only after the turn terminates `done` —
+   * writes an override row whose `user_override` field is this string.
+   * Subsequent `getSessionMessages` calls will substitute it in place
+   * of the wrapped Letta content.
+   *
+   * Persisted only on `done`. On `cancelled` / `failed`, Letta drops
+   * the user message and we drop the override too (no orphan row).
+   */
+  userOverride?: string;
+}
+
+/** Per-call options shared by `streamChat` + `getTurnEvents`. */
+export interface StreamChatOptions {
+  /** Aborts the in-flight stream. */
+  signal?: AbortSignal;
+  /**
+   * Resumption cursor for `getTurnEvents`; ignored on `streamChat` in v1
+   * but accepted for forward-compat with the §6.3.2 idempotency surface.
+   */
+  fromSeq?: number;
+}
+
+/** Per-agent entry returned by `listAgents`. */
+export interface AgentSummary {
+  /** Stable id of the ai-hub agent. */
+  id: string;
+  /** User-visible name shown in the agents picker. */
+  display_name: string;
+  /**
+   * Caller-scoped count of the caller's own non-archived sessions against
+   * this agent — populated server-side in one round-trip (§6.3.3).
+   */
+  session_count: number;
+}
+
+/** Response shape from `cancelTurn`. */
+export interface CancelTurnResponse {
+  /** The cancelled turn's id (echoed). */
+  turn_id: string;
+  /** Terminal status after cancellation. Usually `"cancelled"`. */
+  status: "running" | "done" | "cancelled" | "failed";
+  /** True when the turn had already settled before the call landed. */
+  was_already_terminal: boolean;
+}
+
+/**
+ * Admin-view shape of a single user row, as returned by `GET /admin/users`,
+ * `POST /admin/users`, and `PATCH /admin/users/:id/role`.
+ *
+ * Excludes `password_hash` and `identity_source` (server-internal — §6.3.4).
+ * Note the surface is wider than the user-facing `AIHubUser` — admins need
+ * to see `is_initial_password` (to flag rows with the ⚠ indicator) plus the
+ * created / updated timestamps.
+ *
+ * @see SPECIFICATIONS.md §6.3.4 — admin users endpoints
+ * @see ui-sketches/05-admin-users.md
+ */
+export interface AdminUserView {
+  /** Stable UUID. */
+  id: string;
+  /** Login identifier (unique per deployment). */
+  username: string;
+  /** Optional human-readable name. `null` when unset. */
+  display_name: string | null;
+  /** Effective role used for access control. */
+  role: AIHubRole;
+  /**
+   * True until the user completes the change-password flow on first login
+   * (or after an admin-initiated password reset). Drives the ⚠ marker in
+   * the admin Users table.
+   */
+  is_initial_password: boolean;
+  /** The user's stored theme preference, or `null` when not set. */
+  theme_preference: "light" | "dark" | null;
+  /** ISO-8601 timestamp. */
+  created_at: string;
+  /** ISO-8601 timestamp; bumped on role change / password reset. */
+  updated_at: string;
+}
+
+/** Body for `createUser`. */
+export interface CreateUserBody {
+  /** Login identifier. Must be unique (server returns 409 on collision). */
+  username: string;
+  /** Optional human-readable name. */
+  displayName?: string | null;
+  /**
+   * Initial role. Defaults to `"user"` server-side. Admins cannot create
+   * `super_admin`s (server enforces).
+   */
+  role?: AIHubRole;
+}
+
+/** Response from `createUser` / `resetUserPassword` — plaintext returned once. */
+export interface AdminUserPasswordReveal {
+  /**
+   * 16-char alphanumeric plaintext password the server just generated.
+   * Returned **exactly once** — there is no path to retrieve this value
+   * again. The admin UI must surface it in a one-time-reveal modal before
+   * the user dismisses it; calling `resetUserPassword` again issues a
+   * different value (and invalidates the old).
+   */
+  generatedPassword: string;
+}
+
+/** Response from `createUser` — the new user plus its one-time password. */
+export interface CreateUserResponse extends AdminUserPasswordReveal {
+  /** The newly-created user row. */
+  user: AdminUserView;
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Admin agents (catalog)                                                     */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Admin-view shape of an ai-hub agent row. Differs from the user-facing
+ * `AgentSummary` (returned by `GET /agents`) by carrying the Letta `agent_id`
+ * the admin needs to see / edit, the (deprecated-but-still-stored) TPM
+ * settings, and the archive flag.
+ *
+ * @see SPECIFICATIONS.md §6.3.4 — admin agents endpoints
+ * @see ui-sketches/06-admin-agents.md
+ */
+export interface AdminAgentView {
+  /** Stable UUID. */
+  id: string;
+  /** Display name surfaced to end users in the agents picker. */
+  display_name: string;
+  /** The assigned Letta agent id. */
+  letta_agent_id: string;
+  /**
+   * TPM-recovery state — kept on the row post-Step-11.5 for forward
+   * compatibility but **no longer read by runtime code** (§6.5). The admin
+   * Agents page deliberately does not surface a TPM settings modal anymore.
+   */
+  tpm_recovery_enabled: boolean;
+  /** Same — retained for forward compatibility. */
+  max_recovery_attempts: number;
+  /** Same — retained for forward compatibility. */
+  default_retry_after_seconds: number;
+  /** Same — retained for forward compatibility. */
+  stream_idle_timeout_seconds: number;
+  /**
+   * Soft-hide flag. Archived agents disappear from `GET /agents` so no new
+   * sessions can start against them; existing sessions remain readable +
+   * writable (§6.3.4).
+   */
+  is_archived: boolean;
+  /**
+   * Step-12.5 — name of the seed folder under `AI_HUB_FILES_DIR/seeds/`.
+   * `null` when no sandbox is configured for this agent. See
+   * docs/server/session-sandboxes.md.
+   */
+  sandbox_seed_name: string | null;
+  /**
+   * Step-12.5 — Letta conversation id (`conv-…`) to fork from at session
+   * create. `null` when this agent starts every session brand-new.
+   */
+  fork_source_conversation_id: string | null;
+  /** ISO-8601 timestamp. */
+  created_at: string;
+  /** ISO-8601 timestamp. */
+  updated_at: string;
+}
+
+/** Body for `createAdminAgent`. */
+export interface CreateAdminAgentBody {
+  /** Display name; must be 1..255 chars. */
+  displayName: string;
+  /**
+   * The Letta-side agent id this ai-hub agent will point at. Validated by
+   * the server against `client.agents.retrieve(...)`; if Letta doesn't
+   * recognize the id, the server returns 400 `letta_agent_not_found`.
+   */
+  lettaAgentId: string;
+  /**
+   * Step-12.5 — optional seed folder name. When non-null, each new
+   * session for this agent gets a fresh copy of `seeds/<name>/` as its
+   * working directory. Validated against `^[a-zA-Z0-9_-]+$` + filesystem
+   * existence; misses return 400 `seed_name_invalid` / `seed_dir_not_found`.
+   */
+  sandboxSeedName?: string | null;
+  /**
+   * Step-12.5 — optional Letta conversation id to fork from at session
+   * create. Validated against Letta + agent-id match; misses return
+   * 400 `fork_source_not_found` / `fork_source_agent_mismatch`.
+   */
+  forkSourceConversationId?: string | null;
+}
+
+/** Body for `patchAdminAgent`. Each field independently optional. */
+export interface PatchAdminAgentBody {
+  /** New display name. */
+  displayName?: string;
+  /**
+   * New assigned Letta agent id. The server validates it before accepting;
+   * see {@link CreateAdminAgentBody.lettaAgentId} for the failure mode.
+   */
+  lettaAgentId?: string;
+  /** Archive / unarchive flag. */
+  isArchived?: boolean;
+  /**
+   * Step-12.5 — set / change / clear (with `null`) the sandbox seed name.
+   * Same validation as on create.
+   */
+  sandboxSeedName?: string | null;
+  /**
+   * Step-12.5 — set / change / clear (with `null`) the fork source. Same
+   * validation as on create. May be a raw `conv-…` id or an `rmsg-…`
+   * rotating-message reference.
+   */
+  forkSourceConversationId?: string | null;
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Admin rotating messages                                                    */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/** Which scheduling shape a rotating message uses. */
+export type RotatingMessageScheduleKind = "every" | "daily" | "cron";
+
+/**
+ * One row from `GET /admin/rotating-messages`. A rotating starting message
+ * runs `prompt` against `letta_agent_id` on the configured schedule and stores
+ * the agent's reply as `current_conversation_id` — a forkable base conversation
+ * referenced elsewhere by its `rmsg-…` `id`.
+ *
+ * @see docs/server/rotating-messages.md
+ */
+export interface AdminRotatingMessageView {
+  /** The `rmsg-…` identifier — also the value pasted into an agent's Base conversation field. */
+  id: string;
+  /** Operator-facing display name. */
+  display_name: string;
+  /** The prompt sent to the agent each rotation. */
+  prompt: string;
+  /** Raw Letta agent id the prompt runs against. */
+  letta_agent_id: string;
+  /** Schedule discriminator. */
+  schedule_kind: RotatingMessageScheduleKind;
+  /** Interval (seconds) when `schedule_kind === "every"`; else null. */
+  interval_seconds: number | null;
+  /** `"HH:MM"` (UTC) when `schedule_kind === "daily"`; else null. */
+  daily_time: string | null;
+  /** 5-field cron expression when `schedule_kind === "cron"`; else null. */
+  cron_expression: string | null;
+  /** Current prepared conversation id; null until the first successful rotation. */
+  current_conversation_id: string | null;
+  /** Outcome of the most recent rotation. */
+  last_status: "pending" | "ok" | "error";
+  /** Error from the last failed rotation; null otherwise. */
+  last_error: string | null;
+  /** ISO-8601 timestamp of the last successful rotation; null until first success. */
+  last_rotated_at: string | null;
+  /** ISO-8601 timestamp the scheduler uses to decide when to rotate next. */
+  next_rotation_at: string;
+  /** Soft-hide flag. */
+  is_archived: boolean;
+  /** ISO-8601 timestamp. */
+  created_at: string;
+  /** ISO-8601 timestamp. */
+  updated_at: string;
+}
+
+/** Body for `createAdminRotatingMessage`. */
+export interface CreateAdminRotatingMessageBody {
+  displayName: string;
+  prompt: string;
+  lettaAgentId: string;
+  scheduleKind: RotatingMessageScheduleKind;
+  /** Required when `scheduleKind === "every"`. */
+  intervalSeconds?: number | null;
+  /** Required when `scheduleKind === "daily"` (`"HH:MM"`, UTC). */
+  dailyTime?: string | null;
+  /** Required when `scheduleKind === "cron"` (5-field cron). */
+  cronExpression?: string | null;
+}
+
+/** Body for `patchAdminRotatingMessage`. Each field independently optional. */
+export interface PatchAdminRotatingMessageBody {
+  displayName?: string;
+  prompt?: string;
+  lettaAgentId?: string;
+  scheduleKind?: RotatingMessageScheduleKind;
+  intervalSeconds?: number | null;
+  dailyTime?: string | null;
+  cronExpression?: string | null;
+  isArchived?: boolean;
+}
+
+/** Response from `rotateAdminRotatingMessageNow`. */
+export interface RotateNowResponse {
+  /** The refreshed row after the inline rotation attempt. */
+  rotating_message: AdminRotatingMessageView;
+  /** The attempt's outcome. */
+  outcome: { status: "ok" | "error"; conversationId?: string; error?: string };
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Admin sessions overview                                                    */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * One row in `GET /admin/sessions` — the session row joined to its owner
+ * username + agent display name so the admin table can render labels without
+ * a follow-up round-trip.
+ *
+ * @see SPECIFICATIONS.md §6.3.4 — admin sessions endpoint
+ * @see ui-sketches/07-admin-sessions-overview.md
+ */
+export interface AdminSessionView {
+  /** Stable session id. */
+  id: string;
+  /** Owner's user id. */
+  user_id: string;
+  /** Agent (ai-hub catalog) id. */
+  agent_id: string;
+  /** Session title. */
+  title: string;
+  /** Soft-hide flag. */
+  is_archived: boolean;
+  /**
+   * Step-12.5 — `true` when the session has a per-session sandbox folder
+   * on disk; the super_admin's `[Purge sandbox]` button is shown only
+   * when this is true. The absolute path is deliberately NOT exposed
+   * over the wire (server filesystem-layout leak).
+   */
+  has_sandbox: boolean;
+  /** ISO-8601 timestamp. */
+  created_at: string;
+  /** ISO-8601 timestamp; bumped on rename / archive flip / new turn. */
+  updated_at: string;
+  /** Owner's username — server-joined. */
+  owner_username: string;
+  /** Agent's display name — server-joined. */
+  agent_display_name: string;
+}
+
+/** Filter args for `listAdminSessions`. */
+export interface ListAdminSessionsOptions {
+  /** Filter by owner. */
+  ownerId?: string;
+  /** Filter by ai-hub agent. */
+  agentId?: string;
+  /** Filter by archive state. Defaults to `"active"` per the server. */
+  status?: "active" | "archived" | "all";
+  /** Case-insensitive substring match against the session title. */
+  search?: string;
+  /** Opaque pagination cursor returned in the previous page's `nextCursor`. */
+  cursor?: string;
+  /** Page size; 1..200. Defaults to 50 server-side. */
+  limit?: number;
+}
+
+/**
+ * Response shape from `listAdminSessions` — a page of rows plus a cursor for
+ * the next page.
+ */
+export interface ListAdminSessionsResponse {
+  /** The page of sessions. */
+  sessions: AdminSessionView[];
+  /** Cursor to pass back as `cursor` for the next page; `null` on last page. */
+  nextCursor: string | null;
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Admin settings                                                             */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Response shape from `GET /admin/settings` — deployment-wide configuration
+ * the super-admin sees on the settings page.
+ *
+ * Encrypted Letta API key is **never** returned in plaintext through this
+ * endpoint. `letta_api_key_set` + `letta_api_key_masked` let the UI display
+ * "configured / not configured" without exposing the value.
+ *
+ * @see SPECIFICATIONS.md §6.3.4 — settings endpoints
+ * @see ui-sketches/08-admin-settings.md
+ */
+export interface AdminSettingsView {
+  /** Letta API base URL (e.g. `http://letta:8283`). `null` until set. */
+  letta_base_url: string | null;
+  /** Optional override for the "Open Letta ADE" link target. `null` when unset. */
+  letta_ade_url: string | null;
+  /** Masked placeholder (`••••••••`) when a key is stored in the DB; `null` otherwise. */
+  letta_api_key_masked: string | null;
+  /**
+   * True when the runtime has a usable API key from EITHER source — DB or
+   * env. The admin UI uses this to decide whether to render "configured"
+   * vs. "missing." Pair with `letta_api_key_source` for source-aware copy.
+   */
+  letta_api_key_set: boolean;
+  /**
+   * Which source the runtime is *currently* using for the Letta API key —
+   * `"db"` when a super-admin set it via the admin panel (DB wins over
+   * env per spec), `"env"` when the DB column is empty and the server's
+   * `LETTA_API_KEY` env var is set, `"none"` when no usable value exists
+   * anywhere (chat path will throw). Lets the UI label the field
+   * "(from env)" / "(from admin panel)" so operators aren't confused
+   * about why their `.env` change didn't appear to take effect (or did).
+   */
+  letta_api_key_source: "db" | "env" | "none";
+  /** Theme settings, stored as separate columns server-side. */
+  theme: {
+    default: "light" | "dark";
+    switcher_enabled: boolean;
+  };
+  /** The flat §8.4 feature-toggles blob. */
+  feature_toggles: AIHubFeatureToggles;
+  /** ISO-8601 of the last signing-key rotation. `null` until first rotation. */
+  signing_key_rotated_at: string | null;
+  /** ISO-8601 of the last metrics-token rotation. `null` until first rotation. */
+  metrics_scrape_token_rotated_at: string | null;
+  /** ISO-8601 of the last settings update. */
+  updated_at: string;
+}
+
+/** Body for `patchAdminSettings`. Each field independently optional. */
+export interface PatchAdminSettingsBody {
+  /** Letta base URL. Pass `null` to clear (the schema accepts null + URL). */
+  lettaBaseUrl?: string | null;
+  /** Letta ADE URL. Pass `null` to clear. */
+  lettaAdeUrl?: string | null;
+  /** New Letta API key (plaintext over HTTPS; encrypted server-side at rest). */
+  lettaApiKey?: string;
+  /** Theme partial — either or both fields. */
+  theme?: {
+    default?: "light" | "dark";
+    switcherEnabled?: boolean;
+  };
+}
+
+/** Response from `rotateAdminMetricsToken` — the new token returned **once**. */
+export interface AdminMetricsTokenRotateResponse {
+  /** The freshly-generated 32-byte hex token. Shown to the admin exactly once. */
+  token: string;
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Internal helpers                                                           */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Thrown for any HTTP-level failure (non-2xx, network drop, etc.). The
+ * `code` discriminates by §7.2's `AIHubError` codes; the message is safe
+ * to render to end-users (it's either the server's `error.message` or a
+ * fixed transport-level string).
+ */
+export class AIHubRequestError extends Error implements AIHubError {
+  /** Machine-readable code; clients branch on this rather than the message. */
+  override readonly name = "AIHubRequestError";
+  /** Discriminator matching `AIHubError.code`. */
+  readonly code: AIHubError["code"];
+  /** HTTP status when one was available. */
+  readonly status?: number;
+  /** Pino `request_id` from the server for log correlation. */
+  readonly request_id?: string;
+
+  /**
+   * @param code - the error discriminator.
+   * @param message - the human-readable message.
+   * @param status - HTTP status, when available.
+   * @param requestId - request id, when available.
+   */
+  constructor(
+    code: AIHubError["code"],
+    message: string,
+    status?: number,
+    requestId?: string,
+  ) {
+    super(message);
+    this.code = code;
+    if (status !== undefined) this.status = status;
+    if (requestId !== undefined) this.request_id = requestId;
+  }
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  AIHubClient                                                                */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * The typed SDK every React surface in the library is built on.
+ *
+ * The client owns the JWT lifecycle (storage + clearing on 401) and the
+ * SSE plumbing; everything else is a thin HTTP wrapper that translates
+ * camelCase arguments into the server's snake_case wire format.
+ *
+ * @example
+ * ```ts
+ * const client = new AIHubClient({ baseUrl: "/api/ai-hub" });
+ * const { token, mustChangePassword, user } = await client.login("alice", "secret");
+ * if (!mustChangePassword) {
+ *   for await (const event of client.streamChat({
+ *     sessionId: session.id,
+ *     userMessage: "Hello.",
+ *   })) {
+ *     console.log(event);
+ *   }
+ * }
+ * ```
+ */
+export class AIHubClient {
+  private readonly baseUrl: string;
+  private readonly fetchImpl: typeof fetch;
+  private readonly tokenStore: TokenStorage;
+  private readonly onUnauthorized?: () => void;
+  /** Guards against firing `onUnauthorized` more than once per 401 storm. */
+  private unauthorizedFired = false;
+
+  /**
+   * @param options - constructor options. `baseUrl` is required; everything
+   *   else has a sensible default.
+   */
+  constructor(options: AIHubClientOptions) {
+    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+    this.tokenStore = resolveTokenStorage(options.tokenStorage ?? "localStorage");
+    if (options.onUnauthorized) this.onUnauthorized = options.onUnauthorized;
+  }
+
+  /* ───── token surface ──────────────────────────────────────────────── */
+
+  /** Returns the currently-stored token, or null. */
+  getToken(): string | null {
+    return this.tokenStore.get();
+  }
+
+  /**
+   * Replaces the stored token. Used by the provider after `login` /
+   * `changePassword` to persist the JWT before the next request fires.
+   *
+   * @param token - the bearer JWT to store.
+   */
+  setToken(token: string): void {
+    this.tokenStore.set(token);
+    this.unauthorizedFired = false;
+  }
+
+  /** Clears the stored token. Idempotent. */
+  clearToken(): void {
+    this.tokenStore.clear();
+  }
+
+  /* ───── auth ───────────────────────────────────────────────────────── */
+
+  /**
+   * `POST /auth/login`. On success, persists the returned token automatically
+   * so subsequent calls authenticate without the caller threading the JWT
+   * through.
+   *
+   * @param username - the user's login id.
+   * @param password - plaintext password (sent over HTTPS to the server).
+   * @returns the login response, with `mustChangePassword` camelcased.
+   */
+  async login(username: string, password: string): Promise<LoginResponse> {
+    const raw = await this.requestJson<{
+      token: string;
+      must_change_password: boolean;
+      user: AIHubUser;
+      deployment?: AIHubDeployment;
+    }>("POST", "/auth/login", {
+      body: { username, password },
+      authenticated: false,
+    });
+    this.setToken(raw.token);
+    const response: LoginResponse = {
+      token: raw.token,
+      mustChangePassword: raw.must_change_password,
+      user: raw.user,
+    };
+    if (raw.deployment) response.deployment = raw.deployment;
+    return response;
+  }
+
+  /**
+   * `POST /auth/change-password`. Returns the fresh session token (the
+   * change-only token is consumed by this call).
+   *
+   * @param currentPassword - the user's existing password, or null when
+   *   the caller is authenticating with a password-change-only token
+   *   (forced-change flow — §8.5).
+   * @param newPassword - the new password. Must satisfy the §8.5 policy
+   *   (≥8 chars, ≥2 of {letters, digits, special}).
+   * @returns the new session token, persisted automatically.
+   */
+  async changePassword(
+    currentPassword: string | null,
+    newPassword: string,
+  ): Promise<{ token: string }> {
+    const body: Record<string, unknown> = { new_password: newPassword };
+    if (currentPassword !== null) body.current_password = currentPassword;
+    const result = await this.requestJson<{ token: string }>(
+      "POST",
+      "/auth/change-password",
+      { body },
+    );
+    this.setToken(result.token);
+    return result;
+  }
+
+  /**
+   * `POST /auth/logout`. Server-side this is a no-op in v1 (no token
+   * blacklist — §6.3.4); we issue it for symmetry and to give the server
+   * an audit-log entry. Always clears the local token afterward, even
+   * when the request fails.
+   */
+  async logout(): Promise<void> {
+    try {
+      await this.requestJson<unknown>("POST", "/auth/logout", { body: {} });
+    } catch {
+      /* network errors here are not fatal — clear and move on */
+    } finally {
+      this.clearToken();
+    }
+  }
+
+  /**
+   * `GET /auth/me` — fetches the `{ user, deployment }` envelope.
+   */
+  async me(): Promise<AIHubAuthContext> {
+    return this.requestJson<AIHubAuthContext>("GET", "/auth/me");
+  }
+
+  /**
+   * `GET /feature-toggles` — fetches the deployment-wide UI feature
+   * toggles set by `super_admin` (§8.4). **Unauthenticated** — no token
+   * required, every role gets the same response. The provider calls this
+   * on mount so the §8.4 precedence ("server toggle > React prop >
+   * built-in default") applies before the chat shell first renders.
+   *
+   * Missing keys are returned absent in the response (not coerced to
+   * `false`) so the client can distinguish "explicitly off" from "fall
+   * through to the React prop default."
+   *
+   * @returns the wire-format toggles blob; may be empty (`{}`) when the
+   *   super_admin hasn't set anything.
+   */
+  async getFeatureToggles(): Promise<AIHubFeatureToggles> {
+    const result = await this.requestJson<{
+      feature_toggles?: AIHubFeatureToggles;
+    }>("GET", "/feature-toggles");
+    return result.feature_toggles ?? {};
+  }
+
+  /**
+   * `PATCH /auth/me/preferences` — updates the caller's stored
+   * `theme_preference`. Returns the refreshed envelope.
+   *
+   * Rejected with `AIHubRequestError(code: "theme_switcher_disabled")` (HTTP
+   * 409) when the deployment has the switcher turned off (§7.6).
+   *
+   * @param prefs - the preferences patch (currently only `theme`).
+   * @param prefs.theme - new theme preference (`"light"` or `"dark"`).
+   */
+  async updatePreferences(
+    prefs: { theme?: "light" | "dark" },
+  ): Promise<AIHubAuthContext> {
+    return this.requestJson<AIHubAuthContext>(
+      "PATCH",
+      "/auth/me/preferences",
+      { body: prefs },
+    );
+  }
+
+  /* ───── sessions ───────────────────────────────────────────────────── */
+
+  /**
+   * `GET /sessions?agent_id=...&include_archived=...`.
+   *
+   * @param options - filter arguments; `agentId` is required.
+   */
+  async listSessions(options: ListSessionsOptions): Promise<Session[]> {
+    const query = new URLSearchParams({ agent_id: options.agentId });
+    if (options.includeArchived) query.set("include_archived", "true");
+    const result = await this.requestJson<{ sessions: Session[] }>(
+      "GET",
+      `/sessions?${query.toString()}`,
+    );
+    return result.sessions;
+  }
+
+  /**
+   * `POST /sessions`.
+   *
+   * Client-side validation: title must be 1..80 chars. Empty / oversize
+   * titles throw `AIHubRequestError(code: "validation")` synchronously
+   * without an HTTP round-trip.
+   *
+   * @param options - the agent id + non-empty title.
+   * @returns the created session row.
+   */
+  async createSession(options: CreateSessionOptions): Promise<Session> {
+    const title = options.title;
+    if (typeof title !== "string" || title.length === 0) {
+      throw new AIHubRequestError(
+        "validation",
+        "Session title is required (1..80 characters).",
+      );
+    }
+    if (title.length > 80) {
+      throw new AIHubRequestError(
+        "validation",
+        "Session title must be 80 characters or fewer.",
+      );
+    }
+    return this.requestJson<Session>("POST", "/sessions", {
+      body: { agent_id: options.agentId, title },
+    });
+  }
+
+  /** `GET /sessions/:id`. */
+  async getSession(id: string): Promise<Session> {
+    return this.requestJson<Session>("GET", `/sessions/${encodeURIComponent(id)}`);
+  }
+
+  /**
+   * `PATCH /sessions/:id` — rename and/or archive in one call. An empty
+   * patch (`{}`) returns the row unchanged.
+   *
+   * @param id - the session id.
+   * @param patch - the fields to update.
+   */
+  async patchSession(id: string, patch: PatchSessionOptions): Promise<Session> {
+    const body: Record<string, unknown> = {};
+    if (patch.title !== undefined) body.title = patch.title;
+    if (patch.isArchived !== undefined) body.is_archived = patch.isArchived;
+    return this.requestJson<Session>(
+      "PATCH",
+      `/sessions/${encodeURIComponent(id)}`,
+      { body },
+    );
+  }
+
+  /**
+   * `PATCH /sessions/:id/reasoning` — update the user's per-session reasoning
+   * settings. The server applies them to the agent's `model_settings`
+   * automatically before the next chat turn.
+   *
+   * Returns the refreshed session including `capabilities`, so the caller
+   * can re-render UI controls without a separate GET.
+   */
+  async patchSessionReasoning(
+    id: string,
+    patch: PatchSessionReasoningOptions,
+  ): Promise<Session> {
+    const body: Record<string, unknown> = {};
+    if (patch.effort !== undefined) body.effort = patch.effort;
+    if (patch.verbosity !== undefined) body.verbosity = patch.verbosity;
+    if (patch.thinkingBudget !== undefined) body.thinking_budget = patch.thinkingBudget;
+    return this.requestJson<Session>(
+      "PATCH",
+      `/sessions/${encodeURIComponent(id)}/reasoning`,
+      { body },
+    );
+  }
+
+  /** `GET /sessions/:id/messages`. */
+  async getSessionMessages(id: string): Promise<AIHubMessage[]> {
+    const result = await this.requestJson<{ messages: AIHubMessage[] }>(
+      "GET",
+      `/sessions/${encodeURIComponent(id)}/messages`,
+    );
+    return result.messages;
+  }
+
+  /* ───── message overrides ──────────────────────────────────────────── */
+
+  /**
+   * `GET /sessions/:id/message-overrides` — returns the caller's per-message
+   * content substitutions for this session's underlying Letta conversation.
+   *
+   * Overrides are keyed by `ordinal_position` (0-based index into Letta's
+   * chronologically-sorted message list). They're applied automatically by
+   * `getSessionMessages` — callers don't need to merge manually; this
+   * endpoint exists so custom Tier-3 UIs can render an edit affordance
+   * next to each message that has an override.
+   *
+   * @param sessionId - the ai-hub session id.
+   * @returns the overrides sorted by `ordinal_position` ascending.
+   */
+  async listMessageOverrides(sessionId: string): Promise<AIHubMessageOverride[]> {
+    const result = await this.requestJson<{ overrides: AIHubMessageOverride[] }>(
+      "GET",
+      `/sessions/${encodeURIComponent(sessionId)}/message-overrides`,
+    );
+    return result.overrides;
+  }
+
+  /**
+   * `PUT /sessions/:id/message-overrides/:position` — upsert one or both
+   * override layers for the message at `ordinalPosition`.
+   *
+   * Pass `systemOverride` to set the LLM-facing view, `userOverride` to
+   * set the UI-facing view, or both. At least one must be provided.
+   * **Merge semantics**: only the layer(s) you pass are written; an
+   * existing value on the other layer is preserved.
+   *
+   * **Validation gates** (server-enforced):
+   *
+   * - `409 turn_in_progress` — a turn is currently live for this session.
+   * - `409 message_not_found` — no Letta message exists at this position
+   *   yet (typical when a tier-3 caller tries to override a message
+   *   before it has landed; wait for the turn to finish first).
+   *
+   * Pass empty string for `userOverride` to visually hide the message
+   * (the bubble slot stays — use `deleteMessageOverride` to remove the
+   * slot entirely).
+   *
+   * @param sessionId - the ai-hub session id.
+   * @param ordinalPosition - the 0-based index in Letta's message list.
+   * @param override - one or both layers to write.
+   * @returns the resulting override row.
+   */
+  async setMessageOverride(
+    sessionId: string,
+    ordinalPosition: number,
+    override: { systemOverride?: string; userOverride?: string },
+  ): Promise<AIHubMessageOverride> {
+    const body: Record<string, string> = {};
+    if (override.systemOverride !== undefined) body.system_override = override.systemOverride;
+    if (override.userOverride !== undefined) body.user_override = override.userOverride;
+    return this.requestJson<AIHubMessageOverride>(
+      "PUT",
+      `/sessions/${encodeURIComponent(sessionId)}/message-overrides/${ordinalPosition}`,
+      { body },
+    );
+  }
+
+  /**
+   * `DELETE /sessions/:id/message-overrides/:position` — remove an override.
+   *
+   * Idempotent: returns successfully whether or not the row existed.
+   *
+   * @param sessionId - the ai-hub session id.
+   * @param ordinalPosition - the 0-based index in Letta's message list.
+   */
+  async deleteMessageOverride(sessionId: string, ordinalPosition: number): Promise<void> {
+    await this.requestJson<void>(
+      "DELETE",
+      `/sessions/${encodeURIComponent(sessionId)}/message-overrides/${ordinalPosition}`,
+    );
+  }
+
+  /* ───── agents ─────────────────────────────────────────────────────── */
+
+  /**
+   * `GET /agents` — returns the user-facing agent catalog (non-archived
+   * only) with each entry's `session_count` scoped to the caller.
+   */
+  async listAgents(): Promise<AgentSummary[]> {
+    const result = await this.requestJson<{ agents: AgentSummary[] }>(
+      "GET",
+      "/agents",
+    );
+    return result.agents;
+  }
+
+  /* ───── chat ───────────────────────────────────────────────────────── */
+
+  /**
+   * `POST /chat` — opens an SSE stream. Returns an async iterable of
+   * `AIHubEvent`s; consume with `for await (const event of …)`.
+   *
+   * The iterable terminates when the server emits `stream_end` (the bytes
+   * stop after that). To abort early, pass `opts.signal`.
+   *
+   * @param body - the request body (sessionId, userMessage, optional effort,
+   *   optional idempotencyKey).
+   * @param opts - optional abort signal and resumption hint.
+   */
+  streamChat(
+    body: StreamChatBody,
+    opts: StreamChatOptions = {},
+  ): AsyncIterable<AIHubEvent> {
+    const wireBody: Record<string, unknown> = {
+      session_id: body.sessionId,
+      user_message: body.userMessage,
+    };
+    if (body.effort !== undefined) wireBody.effort = body.effort;
+    if (body.idempotencyKey !== undefined) {
+      wireBody.idempotency_key = body.idempotencyKey;
+    }
+    if (body.userOverride !== undefined) {
+      wireBody.user_override = body.userOverride;
+    }
+    return this.streamRequest("POST", "/chat", wireBody, opts);
+  }
+
+  /**
+   * `GET /chat/:turn_id/events?from_seq=N` — resumption replay then
+   * live-attach.
+   *
+   * @param turnId - the turn to resume.
+   * @param opts - optional abort signal and `fromSeq` cursor (defaults to
+   *   `-1` so every persisted event is replayed).
+   */
+  getTurnEvents(
+    turnId: string,
+    opts: StreamChatOptions = {},
+  ): AsyncIterable<AIHubEvent> {
+    const fromSeq = opts.fromSeq ?? -1;
+    const path = `/chat/${encodeURIComponent(turnId)}/events?from_seq=${encodeURIComponent(
+      String(fromSeq),
+    )}`;
+    return this.streamRequest("GET", path, undefined, opts);
+  }
+
+  /** `POST /chat/:turn_id/cancel`. */
+  async cancelTurn(turnId: string): Promise<CancelTurnResponse> {
+    return this.requestJson<CancelTurnResponse>(
+      "POST",
+      `/chat/${encodeURIComponent(turnId)}/cancel`,
+      { body: {} },
+    );
+  }
+
+  /* ───── admin: users ───────────────────────────────────────────────── */
+
+  /**
+   * `GET /admin/users` — fetches every user row in the deployment.
+   *
+   * Caller must be `admin` or `super_admin`; the server returns 403
+   * otherwise (the SDK surfaces it as `AIHubRequestError(code: "forbidden")`).
+   *
+   * @returns the user rows, sorted alphabetically by username.
+   * @throws {AIHubRequestError} `forbidden` for `user` / `power_user` callers.
+   */
+  async listAdminUsers(): Promise<AdminUserView[]> {
+    const result = await this.requestJson<{ users: AdminUserView[] }>(
+      "GET",
+      "/admin/users",
+    );
+    return result.users;
+  }
+
+  /**
+   * `POST /admin/users` — creates a user; the server generates the password.
+   *
+   * Returns the new row plus the **one-time** plaintext password
+   * (`generatedPassword`). The caller is responsible for surfacing it
+   * exactly once in the UI — there is no way to retrieve it later.
+   *
+   * Admins cannot create `super_admin`s (server returns 403 if the body
+   * requests it). On username collision returns 409 `username_taken`.
+   *
+   * @param body - the new user's identity + initial role.
+   * @returns the created row and the one-time password.
+   * @throws {AIHubRequestError} `forbidden` (caller role insufficient or
+   *   admin tried to grant super_admin), `validation` (malformed body),
+   *   or `username_taken` (409).
+   */
+  async createAdminUser(body: CreateUserBody): Promise<CreateUserResponse> {
+    const wireBody: Record<string, unknown> = { username: body.username };
+    if (body.displayName !== undefined) {
+      wireBody.display_name = body.displayName;
+    }
+    if (body.role !== undefined) wireBody.role = body.role;
+    const result = await this.requestJson<{
+      user: AdminUserView;
+      generated_password: string;
+    }>("POST", "/admin/users", { body: wireBody });
+    return {
+      user: result.user,
+      generatedPassword: result.generated_password,
+    };
+  }
+
+  /**
+   * `PATCH /admin/users/:id/role` — changes a user's role.
+   *
+   * The server enforces the admin-shield + super-admin-min-count rules
+   * transactionally (§8.1). Violations come back as 403 with codes like
+   * `admin_shield`, `super_admin_min_count`, or `forbidden`.
+   *
+   * @param id - the target user's id.
+   * @param role - the new role.
+   * @returns the updated row.
+   * @throws {AIHubRequestError} `forbidden` (shield / min-count / caller
+   *   cannot grant this role).
+   */
+  async patchAdminUserRole(
+    id: string,
+    role: AIHubRole,
+  ): Promise<AdminUserView> {
+    const result = await this.requestJson<{ user: AdminUserView }>(
+      "PATCH",
+      `/admin/users/${encodeURIComponent(id)}/role`,
+      { body: { role } },
+    );
+    return result.user;
+  }
+
+  /**
+   * `POST /admin/users/:id/reset-password` — issues a fresh password.
+   *
+   * Sets `is_initial_password = true` on the target. The new plaintext is
+   * returned **exactly once** in `generatedPassword`; the admin UI must
+   * surface it via the one-time-reveal modal.
+   *
+   * @param id - the target user's id.
+   * @returns the one-time plaintext.
+   * @throws {AIHubRequestError} `forbidden` (shield / min-count).
+   */
+  async resetAdminUserPassword(
+    id: string,
+  ): Promise<AdminUserPasswordReveal> {
+    const result = await this.requestJson<{ generated_password: string }>(
+      "POST",
+      `/admin/users/${encodeURIComponent(id)}/reset-password`,
+      { body: {} },
+    );
+    return { generatedPassword: result.generated_password };
+  }
+
+  /**
+   * `DELETE /admin/users/:id` — hard-deletes a user.
+   *
+   * Cascades to that user's sessions via the FK. The server blocks
+   * self-delete (returns 403) so a careless click can't brick the caller's
+   * own account; shield + min-count apply as for role change.
+   *
+   * @param id - the target user's id.
+   * @throws {AIHubRequestError} `forbidden` (shield, min-count, or
+   *   attempting to delete oneself).
+   */
+  async deleteAdminUser(id: string): Promise<void> {
+    await this.requestJson<unknown>(
+      "DELETE",
+      `/admin/users/${encodeURIComponent(id)}`,
+    );
+  }
+
+  /* ───── admin: agents ──────────────────────────────────────────────── */
+
+  /**
+   * `GET /admin/agents` — every ai-hub agent in the deployment, including
+   * archived ones. Caller must be `power_user`+ per §8.2.
+   *
+   * Sort order: ascending by `display_name` (the server's `ORDER BY`).
+   *
+   * @returns the agent rows.
+   * @throws {AIHubRequestError} `forbidden` for `user` callers.
+   */
+  async listAdminAgents(): Promise<AdminAgentView[]> {
+    const result = await this.requestJson<{ agents: AdminAgentView[] }>(
+      "GET",
+      "/admin/agents",
+    );
+    return result.agents;
+  }
+
+  /**
+   * `POST /admin/agents` — register a new ai-hub agent in the catalog.
+   *
+   * The server validates `lettaAgentId` against Letta; if the id isn't
+   * resolvable the response is 400 `letta_agent_not_found` (surface inline
+   * on the form field).
+   *
+   * @param body - the display name + assigned Letta agent id.
+   * @returns the newly-created row.
+   * @throws {AIHubRequestError} `letta_agent_not_found`, `validation`, `forbidden`.
+   */
+  async createAdminAgent(body: CreateAdminAgentBody): Promise<AdminAgentView> {
+    const wire: Record<string, unknown> = {
+      display_name: body.displayName,
+      letta_agent_id: body.lettaAgentId,
+    };
+    if (body.sandboxSeedName !== undefined) {
+      wire.sandbox_seed_name = body.sandboxSeedName;
+    }
+    if (body.forkSourceConversationId !== undefined) {
+      wire.fork_source_conversation_id = body.forkSourceConversationId;
+    }
+    return this.requestJson<AdminAgentView>("POST", "/admin/agents", {
+      body: wire,
+    });
+  }
+
+  /**
+   * `PATCH /admin/agents/:id` — update one or more fields. Every field is
+   * optional; an empty patch is a 200 no-op.
+   *
+   * Archive / unarchive flows through this same endpoint via `isArchived`.
+   *
+   * @param id - the ai-hub agent id.
+   * @param body - the fields to update.
+   * @returns the refreshed row.
+   * @throws {AIHubRequestError} `letta_agent_not_found` if `lettaAgentId`
+   *   was supplied and doesn't resolve in Letta.
+   */
+  async patchAdminAgent(
+    id: string,
+    body: PatchAdminAgentBody,
+  ): Promise<AdminAgentView> {
+    const wire: Record<string, unknown> = {};
+    if (body.displayName !== undefined) wire.display_name = body.displayName;
+    if (body.lettaAgentId !== undefined) wire.letta_agent_id = body.lettaAgentId;
+    if (body.isArchived !== undefined) wire.is_archived = body.isArchived;
+    if (body.sandboxSeedName !== undefined) {
+      wire.sandbox_seed_name = body.sandboxSeedName;
+    }
+    if (body.forkSourceConversationId !== undefined) {
+      wire.fork_source_conversation_id = body.forkSourceConversationId;
+    }
+    return this.requestJson<AdminAgentView>(
+      "PATCH",
+      `/admin/agents/${encodeURIComponent(id)}`,
+      { body: wire },
+    );
+  }
+
+  /* ───── admin: rotating messages ────────────────────────────────────── */
+
+  /**
+   * `GET /admin/rotating-messages` — every rotating starting message in the
+   * deployment (archived included), sorted by display name. `power_user`+.
+   *
+   * @returns the rows.
+   * @throws {AIHubRequestError} `forbidden` for `user` callers.
+   */
+  async listAdminRotatingMessages(): Promise<AdminRotatingMessageView[]> {
+    const result = await this.requestJson<{
+      rotating_messages: AdminRotatingMessageView[];
+    }>("GET", "/admin/rotating-messages");
+    return result.rotating_messages;
+  }
+
+  /**
+   * `POST /admin/rotating-messages` — create a rotating starting message. The
+   * server validates `lettaAgentId` against Letta (`letta_agent_not_found`)
+   * and the schedule shape (`invalid_schedule`).
+   *
+   * @param body - the prompt, agent, and schedule config.
+   * @returns the newly-created row (including its `rmsg-…` id).
+   * @throws {AIHubRequestError} `letta_agent_not_found`, `invalid_schedule`, `validation`, `forbidden`.
+   */
+  async createAdminRotatingMessage(
+    body: CreateAdminRotatingMessageBody,
+  ): Promise<AdminRotatingMessageView> {
+    const wire: Record<string, unknown> = {
+      display_name: body.displayName,
+      prompt: body.prompt,
+      letta_agent_id: body.lettaAgentId,
+      schedule_kind: body.scheduleKind,
+    };
+    if (body.intervalSeconds !== undefined) wire.interval_seconds = body.intervalSeconds;
+    if (body.dailyTime !== undefined) wire.daily_time = body.dailyTime;
+    if (body.cronExpression !== undefined) wire.cron_expression = body.cronExpression;
+    return this.requestJson<AdminRotatingMessageView>(
+      "POST",
+      "/admin/rotating-messages",
+      { body: wire },
+    );
+  }
+
+  /**
+   * `PATCH /admin/rotating-messages/:id` — update one or more fields. Every
+   * field is optional; an empty patch is a 200 no-op. Changing the schedule
+   * recomputes the next rotation time.
+   *
+   * @param id - the rotating message id.
+   * @param body - the fields to update.
+   * @returns the refreshed row.
+   * @throws {AIHubRequestError} `letta_agent_not_found`, `invalid_schedule`, `not_found`, `forbidden`.
+   */
+  async patchAdminRotatingMessage(
+    id: string,
+    body: PatchAdminRotatingMessageBody,
+  ): Promise<AdminRotatingMessageView> {
+    const wire: Record<string, unknown> = {};
+    if (body.displayName !== undefined) wire.display_name = body.displayName;
+    if (body.prompt !== undefined) wire.prompt = body.prompt;
+    if (body.lettaAgentId !== undefined) wire.letta_agent_id = body.lettaAgentId;
+    if (body.scheduleKind !== undefined) wire.schedule_kind = body.scheduleKind;
+    if (body.intervalSeconds !== undefined) wire.interval_seconds = body.intervalSeconds;
+    if (body.dailyTime !== undefined) wire.daily_time = body.dailyTime;
+    if (body.cronExpression !== undefined) wire.cron_expression = body.cronExpression;
+    if (body.isArchived !== undefined) wire.is_archived = body.isArchived;
+    return this.requestJson<AdminRotatingMessageView>(
+      "PATCH",
+      `/admin/rotating-messages/${encodeURIComponent(id)}`,
+      { body: wire },
+    );
+  }
+
+  /**
+   * `POST /admin/rotating-messages/:id/rotate-now` — run a rotation inline
+   * (preview / force-refresh). May take a while — it spawns the Letta Code
+   * subprocess like a real chat turn.
+   *
+   * @param id - the rotating message id.
+   * @returns the refreshed row plus the attempt's outcome.
+   * @throws {AIHubRequestError} `not_found`, `forbidden`.
+   */
+  async rotateAdminRotatingMessageNow(id: string): Promise<RotateNowResponse> {
+    return this.requestJson<RotateNowResponse>(
+      "POST",
+      `/admin/rotating-messages/${encodeURIComponent(id)}/rotate-now`,
+      { body: {} },
+    );
+  }
+
+  /* ───── admin: sessions overview ───────────────────────────────────── */
+
+  /**
+   * `GET /admin/sessions` — paginated read-only browser over every session
+   * in the deployment. `power_user`+ per §8.2.
+   *
+   * Each row carries `owner_username` + `agent_display_name` joined
+   * server-side. Use `nextCursor` (when non-null) as the `cursor` for the
+   * next page.
+   *
+   * @param options - filter + pagination args. All optional.
+   * @returns the page plus the next-cursor.
+   */
+  async listAdminSessions(
+    options: ListAdminSessionsOptions = {},
+  ): Promise<ListAdminSessionsResponse> {
+    const query = new URLSearchParams();
+    if (options.ownerId !== undefined) query.set("owner_id", options.ownerId);
+    if (options.agentId !== undefined) query.set("agent_id", options.agentId);
+    if (options.status !== undefined) query.set("status", options.status);
+    if (options.search !== undefined && options.search.length > 0) {
+      query.set("search", options.search);
+    }
+    if (options.cursor !== undefined) query.set("cursor", options.cursor);
+    if (options.limit !== undefined) query.set("limit", String(options.limit));
+    const qs = query.toString();
+    const path = qs.length > 0 ? `/admin/sessions?${qs}` : "/admin/sessions";
+    const result = await this.requestJson<{
+      sessions: AdminSessionView[];
+      next_cursor: string | null;
+    }>("GET", path);
+    return { sessions: result.sessions, nextCursor: result.next_cursor };
+  }
+
+  /**
+   * `GET /admin/sessions/:id/messages` — read-only history for any session
+   * (cross-user). Returns the same `AIHubMessage[]` shape as the user-facing
+   * `getSessionMessages` so the same `<MessageBubble />` rendering can be
+   * reused.
+   *
+   * @param id - any session id in the deployment.
+   * @returns the projected message list.
+   * @throws {AIHubRequestError} `forbidden` for `user` callers, `not_found`
+   *   if the session id doesn't exist.
+   */
+  async getAdminSessionMessages(id: string): Promise<AIHubMessage[]> {
+    const result = await this.requestJson<{ messages: AIHubMessage[] }>(
+      "GET",
+      `/admin/sessions/${encodeURIComponent(id)}/messages`,
+    );
+    return result.messages;
+  }
+
+  /**
+   * Step-12.5 — `POST /admin/sessions/:id/purge-sandbox`.
+   *
+   * Removes the per-session sandbox folder from disk + clears
+   * `session.sandbox_dir`. Idempotent: 204 on success regardless of
+   * whether the session ever had a sandbox. Rejects with
+   * `409 turn_running` if a chat turn is live for the session.
+   *
+   * `super_admin` only — `admin` / `power_user` callers get 403.
+   *
+   * @param id - the ai-hub session id.
+   * @throws {AIHubRequestError} `turn_running`, `forbidden`, `not_found`.
+   */
+  async purgeAdminSessionSandbox(id: string): Promise<void> {
+    await this.requestJson<void>(
+      "POST",
+      `/admin/sessions/${encodeURIComponent(id)}/purge-sandbox`,
+    );
+  }
+
+  /* ───── admin: settings ────────────────────────────────────────────── */
+
+  /**
+   * `GET /admin/settings` — deployment-wide configuration (super_admin only).
+   *
+   * The Letta API key is never returned in plaintext; the response carries
+   * `letta_api_key_set` + `letta_api_key_masked` so the UI can render
+   * "configured / not configured" affordances.
+   */
+  async getAdminSettings(): Promise<AdminSettingsView> {
+    return this.requestJson<AdminSettingsView>("GET", "/admin/settings");
+  }
+
+  /**
+   * `PATCH /admin/settings` — update one or more deployment settings.
+   *
+   * The API key, when supplied, is encrypted under `AI_HUB_ENCRYPTION_KEY`
+   * server-side. Theme fields live as separate columns and follow the same
+   * precedence as the React props (server > prop > built-in default).
+   *
+   * @param body - the patch. Each field independent.
+   * @returns the refreshed settings view.
+   */
+  async patchAdminSettings(
+    body: PatchAdminSettingsBody,
+  ): Promise<AdminSettingsView> {
+    const wire: Record<string, unknown> = {};
+    if (body.lettaBaseUrl !== undefined) wire.letta_base_url = body.lettaBaseUrl;
+    if (body.lettaAdeUrl !== undefined) wire.letta_ade_url = body.lettaAdeUrl;
+    if (body.lettaApiKey !== undefined) wire.letta_api_key = body.lettaApiKey;
+    if (body.theme !== undefined) {
+      const themeWire: Record<string, unknown> = {};
+      if (body.theme.default !== undefined) themeWire.default = body.theme.default;
+      if (body.theme.switcherEnabled !== undefined) {
+        themeWire.switcher_enabled = body.theme.switcherEnabled;
+      }
+      wire.theme = themeWire;
+    }
+    return this.requestJson<AdminSettingsView>("PATCH", "/admin/settings", {
+      body: wire,
+    });
+  }
+
+  /**
+   * `GET /admin/settings/feature-toggles` — the §8.4 toggle blob the
+   * super-admin sees. Same payload the `getFeatureToggles` (unauthenticated)
+   * endpoint returns, but gated and intended for the settings editor.
+   */
+  async getAdminFeatureToggles(): Promise<AIHubFeatureToggles> {
+    const result = await this.requestJson<{
+      feature_toggles?: AIHubFeatureToggles;
+    }>("GET", "/admin/settings/feature-toggles");
+    return result.feature_toggles ?? {};
+  }
+
+  /**
+   * `PATCH /admin/settings/feature-toggles` — merge-patch the §8.4 toggle
+   * blob. Unknown keys are rejected with 400; the server's strict schema is
+   * the source of truth for which toggles are accepted.
+   *
+   * @param toggles - the partial — only the keys you want to write.
+   */
+  async patchAdminFeatureToggles(
+    toggles: AIHubFeatureToggles,
+  ): Promise<AIHubFeatureToggles> {
+    const result = await this.requestJson<{ feature_toggles: AIHubFeatureToggles }>(
+      "PATCH",
+      "/admin/settings/feature-toggles",
+      { body: toggles },
+    );
+    return result.feature_toggles;
+  }
+
+  /**
+   * `POST /admin/settings/rotate-signing-key` — replace the JWT signing key
+   * in place. **Every outstanding JWT is invalidated immediately**, including
+   * the caller's own. The next protected request from the UI will 401 and
+   * the provider routes back to login (§6.7).
+   *
+   * Returns nothing — the new key never leaves the server.
+   */
+  async rotateAdminSigningKey(): Promise<void> {
+    await this.requestJson<unknown>("POST", "/admin/settings/rotate-signing-key", {
+      body: {},
+    });
+  }
+
+  /**
+   * `POST /admin/settings/rotate-metrics-token` — rotate the `/metrics`
+   * bearer token. The new token is returned **exactly once** in
+   * `{ token }`; subsequent `getAdminSettings` calls do NOT echo it back.
+   * The admin must copy it into their Prometheus / Alloy config before
+   * dismissing the reveal modal (§6.10).
+   *
+   * Does NOT invalidate the caller's JWT — only the metrics-scraper bearer
+   * changes.
+   */
+  async rotateAdminMetricsToken(): Promise<AdminMetricsTokenRotateResponse> {
+    return this.requestJson<AdminMetricsTokenRotateResponse>(
+      "POST",
+      "/admin/settings/rotate-metrics-token",
+      { body: {} },
+    );
+  }
+
+  /* ───── internal request plumbing ─────────────────────────────────── */
+
+  /**
+   * Sends a JSON request and parses the JSON response. Centralizes auth
+   * header injection, 401 handling, and error normalization.
+   *
+   * @param method - HTTP method.
+   * @param path - path under `baseUrl`.
+   * @param opts - optional body and unauthenticated-mode flag.
+   * @param opts.body - JSON body to send (omit for GET / DELETE).
+   * @param opts.authenticated - set to `false` to skip the bearer header
+   *   (login is the only such caller). Defaults to true.
+   * @returns the parsed response.
+   */
+  private async requestJson<T>(
+    method: string,
+    path: string,
+    opts: { body?: unknown; authenticated?: boolean } = {},
+  ): Promise<T> {
+    const headers: Record<string, string> = { Accept: "application/json" };
+    const authenticated = opts.authenticated !== false;
+    if (authenticated) {
+      const token = this.tokenStore.get();
+      if (token) headers.Authorization = `Bearer ${token}`;
+    }
+    let body: BodyInit | undefined;
+    if (opts.body !== undefined) {
+      headers["Content-Type"] = "application/json";
+      body = JSON.stringify(opts.body);
+    }
+
+    let response: Response;
+    try {
+      response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        method,
+        headers,
+        ...(body !== undefined ? { body } : {}),
+      });
+    } catch (err) {
+      throw new AIHubRequestError(
+        "network",
+        err instanceof Error ? err.message : "Network request failed.",
+      );
+    }
+
+    if (response.status === 401) {
+      this.handleUnauthorized();
+    }
+
+    if (!response.ok) {
+      throw await this.errorFromResponse(response);
+    }
+
+    // 204 / 205 / empty body
+    const ct = response.headers.get("content-type") ?? "";
+    if (response.status === 204 || !ct.includes("application/json")) {
+      return undefined as T;
+    }
+    return (await response.json()) as T;
+  }
+
+  /**
+   * Shared backbone for `streamChat` and `getTurnEvents`. Yields events
+   * from an SSE response; throws `AIHubRequestError` on 4xx/5xx before the
+   * stream opens.
+   *
+   * @param method - HTTP method.
+   * @param path - path under `baseUrl`.
+   * @param body - optional JSON body (POST /chat only).
+   * @param opts - abort signal.
+   * @yields each ai-hub event from the SSE stream until `stream_end`.
+   */
+  private async *streamRequest(
+    method: string,
+    path: string,
+    body: unknown,
+    opts: StreamChatOptions,
+  ): AsyncIterable<AIHubEvent> {
+    const headers: Record<string, string> = { Accept: "text/event-stream" };
+    const token = this.tokenStore.get();
+    if (token) headers.Authorization = `Bearer ${token}`;
+    let bodyInit: BodyInit | undefined;
+    if (body !== undefined) {
+      headers["Content-Type"] = "application/json";
+      bodyInit = JSON.stringify(body);
+    }
+
+    let response: Response;
+    try {
+      response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        method,
+        headers,
+        ...(bodyInit !== undefined ? { body: bodyInit } : {}),
+        ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
+      });
+    } catch (err) {
+      throw new AIHubRequestError(
+        "network",
+        err instanceof Error ? err.message : "SSE request failed.",
+      );
+    }
+
+    if (response.status === 401) this.handleUnauthorized();
+    if (!response.ok) throw await this.errorFromResponse(response);
+    if (!response.body) {
+      throw new AIHubRequestError("internal", "SSE response had no body.");
+    }
+
+    for await (const event of parseSseStream(response.body)) {
+      yield event;
+    }
+  }
+
+  /**
+   * Clears the token and fires the unauthorized callback (at most once per
+   * 401 storm — the flag resets on next `setToken`).
+   */
+  private handleUnauthorized(): void {
+    this.clearToken();
+    if (this.unauthorizedFired) return;
+    this.unauthorizedFired = true;
+    this.onUnauthorized?.();
+  }
+
+  /**
+   * Builds an `AIHubRequestError` from a non-ok server response. Reads the
+   * server's `{ error: { code, message, request_id } }` envelope when
+   * present; falls back to status-code-derived defaults otherwise.
+   *
+   * @param response - the fetch response (status >= 400).
+   * @returns the normalized error.
+   */
+  private async errorFromResponse(response: Response): Promise<AIHubRequestError> {
+    interface ErrorEnvelope {
+      error?: { code?: string; message?: string; request_id?: string };
+    }
+    let envelope: ErrorEnvelope = {};
+    try {
+      const ct = response.headers.get("content-type") ?? "";
+      if (ct.includes("application/json")) {
+        envelope = (await response.json()) as ErrorEnvelope;
+      }
+    } catch {
+      /* malformed body — fall through to defaults */
+    }
+    const errorBlock = envelope.error;
+    const wireCode = errorBlock?.code;
+    const message =
+      errorBlock?.message ?? `Request failed with status ${response.status}.`;
+    const code = wireCode ?? defaultCodeForStatus(response.status);
+    return new AIHubRequestError(code, message, response.status, errorBlock?.request_id);
+  }
+}
+
+/**
+ * Maps an HTTP status to a default `AIHubError.code` when the server didn't
+ * include one in the response envelope.
+ */
+function defaultCodeForStatus(status: number): AIHubError["code"] {
+  if (status === 401) return "unauthorized";
+  if (status === 403) return "forbidden";
+  if (status === 404) return "not_found";
+  if (status >= 400 && status < 500) return "validation";
+  if (status >= 500) return "internal";
+  return "internal";
+}