@data-club/ai-hub 0.0.1

package/src/types.ts

@@ -0,0 +1,867 @@
+/**
+ * Shared type definitions for the ai-hub library.
+ *
+ * Owned by `@data-club/ai-hub` per SPECIFICATIONS.md §7.1; the server package
+ * imports from here via the workspace symlink so the wire protocol (§9), the
+ * state machine (§10), and the role / user / session shapes (§11, §8) stay in
+ * exactly one place.
+ *
+ * Step 1 only defines the types — there is intentionally no runtime code in
+ * this file. Subsequent steps add reducers (Step 7), server handlers (Steps 2+),
+ * and React components (Steps 8+) that consume these.
+ *
+ * @see SPECIFICATIONS.md §7.1 — exports
+ * @see SPECIFICATIONS.md §9 — wire protocol
+ * @see SPECIFICATIONS.md §10 — state machine
+ * @see SPECIFICATIONS.md §11 — data model
+ */
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Roles + users                                                             */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * The four-role RBAC model. Every JWT carries one of these in its `role` claim;
+ * every protected endpoint enforces a minimum-role gate per the §8.2 matrix.
+ *
+ * Hierarchy (top → bottom = more capabilities):
+ *
+ * - `super_admin` — DataClub staff. Holds Letta connection settings, signing-key
+ *   rotation, metrics-token rotation, and the deployment-wide feature toggles.
+ * - `admin` — customer leadership. Manages users (incl. password resets) but
+ *   cannot touch other admins (admin shield rule, §8.1).
+ * - `power_user` — elevated employee. CRUD on the ai-hub agents catalog + TPM
+ *   recovery settings.
+ * - `user` — regular end-user. Chat only.
+ *
+ * @see SPECIFICATIONS.md §8.1 — role model
+ * @see SPECIFICATIONS.md §8.2 — permission matrix
+ */
+export type AIHubRole = "user" | "power_user" | "admin" | "super_admin";
+
+/**
+ * Per-user identity payload returned by `/auth/me` and `/auth/login`. Pure
+ * per-user state — no deployment-wide context lives on this shape (those
+ * fields are on `AIHubDeployment`).
+ *
+ * Does NOT include `password_hash`, `is_initial_password`, or any other
+ * internal column from the §11 `user` schema — those stay server-side.
+ *
+ * @see SPECIFICATIONS.md §6.3.4 — `GET /auth/me`
+ * @see SPECIFICATIONS.md §11 — `user` table
+ */
+export interface AIHubUser {
+  /** Stable UUID assigned at row creation. */
+  id: string;
+  /** Login identifier (unique per deployment). */
+  username: string;
+  /** Optional human-readable name shown in admin lists. NULL when unset. */
+  display_name: string | null;
+  /** Effective role used for access control; drives the §8.2 matrix. */
+  role: AIHubRole;
+  /**
+   * The user's stored theme preference (`"light"` or `"dark"`). NULL when the
+   * user has not picked one explicitly — the client falls through to
+   * `deployment.theme_default` (subject to `deployment.theme_switcher_enabled`).
+   *
+   * @see SPECIFICATIONS.md §7.6 — theme resolution
+   */
+  theme_preference: "light" | "dark" | null;
+}
+
+/**
+ * Per-deployment context returned alongside `AIHubUser` from `/auth/me` and
+ * `/auth/login`. These fields are properties of the deployment as a whole
+ * (sourced from `admin_setting`), not of the individual user — they're
+ * bundled into the auth response for a single round-trip on shell render.
+ *
+ * The resolved theme is **not** included here — the client computes it from
+ * `user.theme_preference + deployment.{theme_default, theme_switcher_enabled}`
+ * per §7.6 (two lines in the React provider).
+ *
+ * `letta_ade_url` is included only when the caller's role is `power_user`
+ * or higher; for `user`-role callers the field is absent — by design
+ * (§6.3.4: the URL is an admin-surface concern).
+ *
+ * @see SPECIFICATIONS.md §6.3.4 — `GET /auth/me`
+ * @see SPECIFICATIONS.md §7.6 — theme resolution
+ */
+export interface AIHubDeployment {
+  /**
+   * Initial theme for new users; the only theme used when the switcher is
+   * disabled.
+   */
+  theme_default: "light" | "dark";
+  /**
+   * When `false`, the deployment is single-theme — `AIHub.ThemeSwitcher` is
+   * hidden and every user sees `theme_default` regardless of any stored
+   * `user.theme_preference`.
+   */
+  theme_switcher_enabled: boolean;
+  /**
+   * Browser-facing URL of the self-hosted Letta ADE — only present when the
+   * caller's role is `power_user` or higher. Absent for `user`-role callers.
+   */
+  letta_ade_url?: string;
+}
+
+/**
+ * Combined `{ user, deployment }` envelope returned by `/auth/me`,
+ * `/auth/me/preferences`, and embedded in `/auth/login`'s response.
+ *
+ * The split (per Step-3 spec revision) makes the per-user vs. per-deployment
+ * boundary explicit on the wire — clients never have to guess whether a
+ * field is "about me" or "about my deployment."
+ *
+ * @see SPECIFICATIONS.md §6.3.4
+ */
+export interface AIHubAuthContext {
+  /** The authenticated user's identity + stored preferences. */
+  user: AIHubUser;
+  /** The deployment-wide context the client needs to render the shell. */
+  deployment: AIHubDeployment;
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Sessions + messages (catalog-side shapes the React client consumes)       */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Public session shape returned by `/sessions` and `/sessions/{id}`.
+ *
+ * Does not expose Letta's `conversation_id` to the React client — that's
+ * server-internal (§11). The client identifies a session purely by `id`.
+ *
+ * @see SPECIFICATIONS.md §6.3.1 — sessions
+ * @see SPECIFICATIONS.md §11 — `session` table
+ */
+export interface Session {
+  /** Stable UUID. */
+  id: string;
+  /** Owner user-id. The server enforces (caller_id === user_id) on read/write. */
+  user_id: string;
+  /** The ai-hub agent (use-case) this session is scoped to. */
+  agent_id: string;
+  /** User-supplied title (1..80 chars, required at create-time per §6.3.1). */
+  title: string;
+  /**
+   * Soft-hide flag. Archived sessions are excluded from `GET /sessions` by
+   * default; pass `?include_archived=true` to surface them. There is no
+   * hard-delete in v1 (§6.3.1).
+   */
+  is_archived: boolean;
+  /** ISO-8601 timestamp. */
+  created_at: string;
+  /** ISO-8601 timestamp; bumped on rename / archive flip. */
+  updated_at: string;
+  /**
+   * Per-session reasoning state — applied to the agent's `model_settings`
+   * before each turn. `null` for a field means "use agent default".
+   *
+   * The accepted enum values depend on the agent's model: Anthropic uses
+   * `low|medium|high|xhigh|max`; OpenAI uses `none|minimal|low|medium|high|xhigh`.
+   * The `capabilities` field (present on `GET /sessions/:id` responses)
+   * drives which controls the UI should render.
+   */
+  reasoning?: {
+    effort: string | null;
+    verbosity: string | null;
+    thinking_budget: number | null;
+  };
+  /**
+   * Per-model reasoning capabilities. Present on `GET /sessions/:id`
+   * (single-session fetch); omitted on the list endpoint to save a Letta
+   * call per row.
+   *
+   * Mirrors the SDK schema shape — when Letta adds new providers or knobs,
+   * we copy the diff and the UI picks it up automatically.
+   */
+  capabilities?: {
+    /** Anthropic-shape effort dropdown. Present for `anthropic/*`, `bedrock/*`. */
+    effort?: { enum: ReadonlyArray<string> };
+    /** OpenAI-shape `reasoning_effort` dropdown. */
+    reasoning_effort?: { enum: ReadonlyArray<string> };
+    /** OpenAI verbosity dropdown — independent of effort. */
+    verbosity?: { enum: ReadonlyArray<string> };
+    /** Google-style numeric thinking budget. */
+    thinking_budget?: { min: number; max: number };
+  };
+}
+
+/**
+ * One assembled message as the React client renders it. Distinct from the
+ * streaming-event shape (`AIHubEvent`) — events build up to one of these and
+ * then `assistant_message_complete` carries the final assembled value.
+ *
+ * The exact rich-content variants (markdown, tool-call records inline, reasoning
+ * blocks) are filled in in Step 5 (server-side translator) and Step 7 (client
+ * reducer); Step 1 ships the structural skeleton.
+ *
+ * @see SPECIFICATIONS.md §9.2 — `assistant_message_complete`
+ */
+export interface AIHubMessage {
+  /** Stable id assigned by Letta (per-message in a conversation). */
+  id: string;
+  /** Originator role — drives the bubble variant (§7.3). */
+  role: "user" | "assistant" | "system" | "tool";
+  /** Plain-text content; rich-content rendering is handled in Step 7. */
+  content: string;
+  /** ISO-8601 timestamp. */
+  created_at: string;
+  /**
+   * Reasoning block produced by the assistant turn, when present.
+   *
+   * Set only on `assistant`-role messages whose turn was sent with a
+   * non-`none` `effort` and produced a `reasoning_message` row in Letta.
+   * The React `<ReasoningView />` primitive renders this inside the
+   * assistant bubble (collapsed by default).
+   *
+   * Concatenation of every `reasoning_message` row that shared the turn's
+   * id — Letta sometimes emits multiple reasoning rows per turn.
+   *
+   * @see SPECIFICATIONS.md §7.4 — reasoning effort
+   * @see ui-sketches/03-chat.md — reasoning_block
+   */
+  reasoning?: string | null;
+  /**
+   * Tool calls the assistant turn invoked, when any.
+   *
+   * Set only on `assistant`-role messages whose turn produced at least one
+   * `tool_call_message` + matching `tool_return_message` row in Letta. The
+   * React `<ToolCallView />` primitive renders one card per entry inside
+   * the assistant bubble.
+   *
+   * @see SPECIFICATIONS.md §9.3 — tool events
+   * @see SPECIFICATIONS.md §10.3 — tool error vs. agent error
+   * @see ui-sketches/03-chat.md — tool_call_card
+   */
+  tool_calls?: AIHubToolCallRecord[] | null;
+  /**
+   * Provider-reported token usage for the turn that produced this
+   * message. Set on the LAST assistant message of each turn (the
+   * `usage_statistics` event is per-run, not per-message; we stamp it
+   * on the visible final bubble). Renders as a small cache-status
+   * badge in the chat UI; hover for the full breakdown.
+   *
+   * @see AIHubMessageUsage
+   */
+  usage?: AIHubMessageUsage | null;
+}
+
+/**
+ * One tool call invoked during an assistant turn, as carried on
+ * `AIHubMessage.tool_calls`. Distinct from the streaming
+ * `tool_call_*` events: this is the finalized record persisted with
+ * the assistant message.
+ */
+export interface AIHubToolCallRecord {
+  /** Letta-assigned id; correlates the call to its result. */
+  tool_call_id: string;
+  /** The tool name (e.g. `"search_web"`). */
+  tool_name: string;
+  /** Tool input — pretty-printed JSON when parseable. */
+  input: string;
+  /**
+   * Tool output (success path), or `null` if the call errored / hasn't
+   * returned. For `error` status, `error` is populated instead.
+   */
+  output?: string | null;
+  /** Error text (error path), or `null` on success. */
+  error?: string | null;
+  /** Terminal status; mirrors Letta's `tool_return_message.status`. */
+  status: "success" | "error";
+}
+
+/**
+ * One row in a session's message-override table. Customizations write
+ * these to substitute message content at the wire boundary; each row
+ * carries up to two layers (`system_override`, `user_override`) keyed by
+ * `ordinal_position` (Letta's rotating message ids are NOT used — they
+ * change on every system-prompt recompile).
+ *
+ * **Layers**:
+ *
+ * - `system_override` — what the LLM saw / should see at this position.
+ *   Stored but not consulted at display time today; reserved for future
+ *   context-replay features and audit/debug tooling.
+ * - `user_override` — what the human sees in the chat transcript at
+ *   this position. Substituted into the wire `content` field on
+ *   `getSessionMessages`.
+ *
+ * At least one layer is always non-null. The two writers (the
+ * `/chat` post-turn writer and the `setMessageOverride` SDK method)
+ * merge into the same row: each only touches the column(s) it cares
+ * about, the other layer is preserved.
+ *
+ * @see `AIHubClient.listMessageOverrides`
+ * @see `AIHubClient.setMessageOverride`
+ */
+export interface AIHubMessageOverride {
+  /**
+   * 0-based index into Letta's chronologically-sorted message list for
+   * this conversation. Position 0 is typically Letta's compiled
+   * `system_message`; subsequent positions interleave user / assistant /
+   * tool rows in the order Letta surfaces them.
+   */
+  ordinal_position: number;
+  /**
+   * System-view replacement. `null` when no system-layer override was
+   * written. Stored but inert at display time.
+   */
+  system_override: string | null;
+  /**
+   * User-view replacement. `null` when no user-layer override was
+   * written. Substituted into the wire `content` field on
+   * `getSessionMessages` when non-null.
+   */
+  user_override: string | null;
+  /** ISO-8601 timestamp the override was first written. */
+  created_at: string;
+  /** ISO-8601 timestamp of the last update. */
+  updated_at: string;
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  State machine — §10                                                       */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Top-level turn status. Orthogonal to `RunningPhase` — `phase` is only
+ * meaningful when `status === "running"`. Terminal states (`done`, `cancelled`,
+ * `failed`) end the turn but never the session — every session can always
+ * accept a new turn.
+ *
+ * @see SPECIFICATIONS.md §10.1 — status × phase
+ */
+export type TurnStatus = "idle" | "running" | "done" | "cancelled" | "failed";
+
+/**
+ * The sub-state of a running turn. Drives the §10.4 affordance predicate table
+ * (which buttons / banners / spinners / cards render) and the
+ * `TurnStatusIndicator` label table.
+ *
+ * @see SPECIFICATIONS.md §10.1 — phase enumeration
+ * @see SPECIFICATIONS.md §10.4 — affordances bound to (status, phase)
+ */
+export type RunningPhase =
+  | "model_text"
+  | "model_reasoning"
+  | "model_tool_input"
+  | "tool_executing"
+  | "waiting_provider"
+  | "awaiting_user";
+
+/**
+ * The reducer-level state derived from the SSE event stream.
+ *
+ * The ai-hub server is authoritative; `AIHubState` is the React client's
+ * derivation, rebuilt on reconnect by replaying the persisted event log. The
+ * reducer (~100 LOC, lands in Step 7) takes `AIHubState` + `AIHubEvent` and
+ * returns the next `AIHubState`.
+ *
+ * @see SPECIFICATIONS.md §7.5 — state on the client
+ * @see SPECIFICATIONS.md §10 — state machine
+ */
+export interface AIHubState {
+  /** Top-level turn status. */
+  status: TurnStatus;
+  /** Sub-phase; only meaningful when `status === "running"`. */
+  phase: RunningPhase | null;
+  /**
+   * Highest event `seq` consumed so far for the active turn — used as the
+   * `from_seq` cursor on resumption (§9, §6.3.2).
+   */
+  last_seq: number;
+  /** The active turn's id, or null when idle / between turns. */
+  turn_id: string | null;
+  /** The currently-open session's id, or null when no session is selected. */
+  session_id: string | null;
+  /**
+   * The countdown deadline (ISO-8601) attached to the latest
+   * `system_notice {code: "tpm_wait"}`. The TPM banner reads this for its
+   * countdown timer. Null when not in TPM recovery.
+   *
+   * @see SPECIFICATIONS.md §6.5 — TPM recovery
+   */
+  tpm_retry_at: string | null;
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  SSE wire protocol — §9                                                    */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Snapshot of `(status, phase)` carried by every SSE event so the client can
+ * branch on a single field without having to track the reducer's intermediate
+ * state. The server emits this snapshot at the moment of emission (§9).
+ */
+export interface AIHubEventState {
+  /** Status at the moment the event was emitted. */
+  status: TurnStatus;
+  /** Phase at the moment of emission. Null when status is not `running`. */
+  phase: RunningPhase | null;
+}
+
+/**
+ * Common envelope shared by every SSE event the server emits. Concrete events
+ * extend this with `event` (the discriminator) + `data` (the payload).
+ *
+ * @see SPECIFICATIONS.md §9 — wire protocol
+ */
+interface AIHubEventBase {
+  /** Monotonic per-turn sequence, starting at 0 — used for resumption. */
+  seq: number;
+  /** `(status, phase)` snapshot at emission time. */
+  state: AIHubEventState;
+}
+
+/**
+ * Lifecycle: emitted once at the start of every turn. Carries the
+ * `protocol_version` so future wire-protocol bumps surface as a discriminator
+ * rather than silent shape drift.
+ *
+ * @see SPECIFICATIONS.md §9.1
+ */
+export interface AIHubLifecycleStreamStartEvent extends AIHubEventBase {
+  event: "stream_start";
+  data: {
+    /** Wire-protocol version, bumped independently of package versions. */
+    protocol_version: string;
+    /** The session this turn belongs to. */
+    session_id: string;
+    /** This turn's id — used as the cursor on `/chat/{turn_id}/events`. */
+    turn_id: string;
+  };
+}
+
+/**
+ * Lifecycle: emitted once at the end of every turn. The `reason` discriminates
+ * between a healthy completion, a user-driven cancel, and an unrecoverable
+ * error.
+ *
+ * @see SPECIFICATIONS.md §9.1
+ */
+export interface AIHubLifecycleStreamEndEvent extends AIHubEventBase {
+  event: "stream_end";
+  data: {
+    /** Why the stream ended. Drives the terminal `TurnStatus`. */
+    reason: "done" | "cancelled" | "error";
+  };
+}
+
+/**
+ * Lifecycle: keep-alive while the turn is idle. No payload — exists purely so
+ * intermediary proxies don't time the connection out (§9.5).
+ *
+ * @see SPECIFICATIONS.md §9.1
+ */
+export interface AIHubLifecycleHeartbeatEvent extends AIHubEventBase {
+  event: "heartbeat";
+}
+
+/**
+ * Content: streaming assistant text. The reducer concatenates `delta`s into
+ * the active assistant bubble.
+ *
+ * @see SPECIFICATIONS.md §9.2
+ */
+export interface AIHubContentAssistantDeltaEvent extends AIHubEventBase {
+  event: "assistant_delta";
+  data: {
+    /** Next chunk of assistant text. */
+    delta: string;
+  };
+}
+
+/**
+ * Content: streaming reasoning text. Only emitted on turns the user sent with
+ * a non-`none` effort — `none` means no reasoning at all (§7.4).
+ *
+ * @see SPECIFICATIONS.md §9.2
+ */
+export interface AIHubContentReasoningDeltaEvent extends AIHubEventBase {
+  event: "reasoning_delta";
+  data: {
+    /** Next chunk of reasoning text. */
+    delta: string;
+  };
+}
+
+/**
+ * Content: the fully assembled assistant turn, emitted once near `stream_end`.
+ * The React reducer uses this to replace the running bubble with the canonical
+ * message shape returned by the API.
+ *
+ * @see SPECIFICATIONS.md §9.2
+ */
+export interface AIHubContentAssistantMessageCompleteEvent extends AIHubEventBase {
+  event: "assistant_message_complete";
+  data: {
+    /** The fully assembled message as it should be persisted in history. */
+    message: AIHubMessage;
+  };
+}
+
+/**
+ * Tool: the model started emitting a tool call's input. Phase →
+ * `model_tool_input`; the UI's tool-call card opens with the input streaming
+ * in.
+ *
+ * @see SPECIFICATIONS.md §9.3
+ */
+export interface AIHubToolCallStartedEvent extends AIHubEventBase {
+  event: "tool_call_started";
+  data: {
+    /** Stable id used to correlate every event for this call. */
+    tool_call_id: string;
+    /** Letta-side tool name. */
+    tool_name: string;
+  };
+}
+
+/**
+ * Tool: the model is streaming the call's input character-by-character.
+ *
+ * @see SPECIFICATIONS.md §9.3
+ */
+export interface AIHubToolCallInputDeltaEvent extends AIHubEventBase {
+  event: "tool_call_input_delta";
+  data: {
+    /** Correlates back to the originating `tool_call_started`. */
+    tool_call_id: string;
+    /** Next chunk of the call's JSON input. */
+    partial_json: string;
+  };
+}
+
+/**
+ * Tool: the model finished emitting input; Letta is dispatching the tool now.
+ * Phase → `tool_executing`.
+ *
+ * @see SPECIFICATIONS.md §9.3
+ */
+export interface AIHubToolCallDispatchedEvent extends AIHubEventBase {
+  event: "tool_call_dispatched";
+  data: {
+    /** Correlates back to the originating `tool_call_started`. */
+    tool_call_id: string;
+    /** The fully assembled JSON input the tool was called with. */
+    input: unknown;
+  };
+}
+
+/**
+ * Tool: optional progress event for long-running tools.
+ *
+ * @see SPECIFICATIONS.md §9.3
+ */
+export interface AIHubToolCallProgressEvent extends AIHubEventBase {
+  event: "tool_call_progress";
+  data: {
+    /** Correlates back to the originating `tool_call_started`. */
+    tool_call_id: string;
+    /** Implementation-defined progress chunk (string or structured payload). */
+    chunk: unknown;
+  };
+}
+
+/**
+ * Tool: the call resolved.
+ *
+ * Tool errors are NOT turn errors — phase reverts to `model_text` and the
+ * model decides what to do next (retry, apologize, change approach). Only an
+ * `error` event flips the turn to `failed` (§10.3).
+ *
+ * @see SPECIFICATIONS.md §9.3
+ * @see SPECIFICATIONS.md §10.3 — tool error vs. agent error
+ */
+export interface AIHubToolCallResultEvent extends AIHubEventBase {
+  event: "tool_call_result";
+  data: {
+    /** Correlates back to the originating `tool_call_started`. */
+    tool_call_id: string;
+    /** Either an output (success) or an error (tool-side failure). */
+    output?: unknown;
+    error?: {
+      /** Short machine-readable code for the tool's error. */
+      code: string;
+      /** Human-readable description. */
+      message: string;
+    };
+  };
+}
+
+/**
+ * System: TPM-recovery status notice. Codes:
+ *
+ * - `tpm_wait` — provider rate-limited; the server is waiting for `retry_at`.
+ * - `resumed` — recovery succeeded; streaming continues.
+ * - (extensible — additional codes may be added in future minor versions)
+ *
+ * @see SPECIFICATIONS.md §6.5 — TPM recovery
+ * @see SPECIFICATIONS.md §9.4
+ */
+export interface AIHubSystemNoticeEvent extends AIHubEventBase {
+  event: "system_notice";
+  data: {
+    /** Discriminator for the notice variant. */
+    code: "tpm_wait" | "resumed" | (string & {});
+    /** Human-readable message; safe to surface to end-users. */
+    message: string;
+    /** Only set on `tpm_wait` — ISO-8601 deadline for the countdown. */
+    retry_at?: string;
+  };
+}
+
+/**
+ * System: per-turn token-usage counters propagated from Letta. Stamped
+ * on the LAST assistant message of the turn — the React reducer uses
+ * `letta_message_id` to attach the badge to the right bubble. Also
+ * persisted server-side so a refresh keeps the badge.
+ *
+ * @see SPECIFICATIONS.md §9.4
+ * @see docs/server/chat-sse.md
+ */
+export interface AIHubSystemUsageEvent extends AIHubEventBase {
+  event: "usage";
+  data: {
+    /**
+     * Letta message id this usage attaches to (the turn's last assistant
+     * message). The reducer joins this against the chat history to put
+     * the cache badge on the right bubble. Optional for forward
+     * compatibility with future per-message usage events.
+     */
+    letta_message_id?: string;
+    /** Non-cached input-token count (prompt_tokens). */
+    input?: number;
+    /** Output-token count (completion_tokens). */
+    output?: number;
+    /** Cache-read-token count — Anthropic / OpenAI / Gemini all report. */
+    cache_read?: number;
+    /** Cache-write-token count — Anthropic only; null elsewhere. */
+    cache_write?: number;
+    /** Reasoning / thinking tokens for models that produce them. */
+    reasoning?: number;
+    /** Letta's rolling context-window-size estimate post-turn. */
+    context?: number;
+    /** Sum reported by provider (may differ from input+output when reasoning is counted separately). */
+    total?: number;
+  };
+}
+
+/**
+ * Per-assistant-message cache + token usage, attached to the
+ * historical chat record. Returned from `GET /sessions/{id}/messages`
+ * via `AIHubMessage.usage`. Same shape as the live wire event's
+ * `data` minus the `letta_message_id` (which is already the message
+ * itself).
+ *
+ * @see AIHubSystemUsageEvent
+ */
+export interface AIHubMessageUsage {
+  input?: number | null;
+  output?: number | null;
+  cache_read?: number | null;
+  cache_write?: number | null;
+  reasoning?: number | null;
+  context?: number | null;
+  total?: number | null;
+}
+
+/**
+ * System: non-recoverable error. Followed by `stream_end {reason: "error"}`.
+ * The turn transitions to `failed`; the session remains usable.
+ *
+ * @see SPECIFICATIONS.md §9.4
+ * @see SPECIFICATIONS.md §10.3
+ */
+export interface AIHubSystemErrorEvent extends AIHubEventBase {
+  event: "error";
+  data: {
+    /** Machine-readable error code for client branching. */
+    code: "tpm_exhausted" | "provider_error" | "internal" | "stream_idle" | (string & {});
+    /** Human-readable description. */
+    message: string;
+    /** Pino `request_id` for log correlation. */
+    request_id: string;
+  };
+}
+
+/**
+ * Discriminated union of every SSE event the ai-hub server emits.
+ *
+ * Branch on `event` to narrow to a concrete payload. The reducer (Step 7) is
+ * the canonical consumer; the server's `eventTranslator.ts` (Step 5) is the
+ * canonical producer.
+ *
+ * @see SPECIFICATIONS.md §9 — full wire protocol
+ */
+export type AIHubEvent =
+  | AIHubLifecycleStreamStartEvent
+  | AIHubLifecycleStreamEndEvent
+  | AIHubLifecycleHeartbeatEvent
+  | AIHubContentAssistantDeltaEvent
+  | AIHubContentReasoningDeltaEvent
+  | AIHubContentAssistantMessageCompleteEvent
+  | AIHubToolCallStartedEvent
+  | AIHubToolCallInputDeltaEvent
+  | AIHubToolCallDispatchedEvent
+  | AIHubToolCallProgressEvent
+  | AIHubToolCallResultEvent
+  | AIHubSystemNoticeEvent
+  | AIHubSystemUsageEvent
+  | AIHubSystemErrorEvent;
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Feature toggles — deployment-wide UI gates set by super_admin             */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * The deployment-wide UI feature toggles set by `super_admin` (§8.4), served
+ * by the public `GET /feature-toggles` endpoint and consumed by the React
+ * provider on mount.
+ *
+ * Every key is **optional** — a missing key means "fall back to the React
+ * prop's value (which itself falls back to the built-in default)". The
+ * server stores a flat JSON blob keyed by these names; only the keys the
+ * super_admin explicitly set are present on the wire.
+ *
+ * Precedence at render time (highest → lowest): server toggle > React prop >
+ * built-in default. The provider applies precedence client-side via
+ * `useAffordanceFlags()` (Step 10).
+ *
+ * Adding a new toggle requires updating:
+ *
+ * 1. This interface (the wire type).
+ * 2. `packages/ai-hub-server/src/routes/admin/settings.ts` (`featureTogglesSchema`).
+ * 3. `packages/ai-hub/src/state/affordances.ts` (`useAffordanceFlags`).
+ *
+ * @see SPECIFICATIONS.md §8.4 — feature toggles
+ * @see ui-sketches/08-admin-settings.md — feature_toggles_section
+ */
+export interface AIHubFeatureToggles {
+  /** Overrides `sessions` prop on `<DataClubAIHub />`. */
+  sessions_panel_enabled?: boolean;
+  /** Overrides `sessionsPanelResizable` prop. */
+  sessions_panel_resizable?: boolean;
+  /** Overrides `sessionsPanelCollapsible` prop. */
+  sessions_panel_collapsible?: boolean;
+  /** Overrides `showCreateSessionButton` prop. */
+  create_session_button_enabled?: boolean;
+  /** Overrides `userInput` prop. */
+  user_input_enabled?: boolean;
+  /** Overrides `showStopButton` prop. */
+  stop_button_enabled?: boolean;
+  /** Overrides `showToolCalls` prop. */
+  tool_calls_visible?: boolean;
+  /** Overrides `showReasoning` prop. */
+  reasoning_visible?: boolean;
+  /** Overrides `showSystemMessages` prop. */
+  system_messages_visible?: boolean;
+  /** Overrides `showTpmNotice` prop. */
+  tpm_notice_visible?: boolean;
+  /** Overrides `showEffortControl` prop. */
+  effort_control_visible?: boolean;
+  /** Overrides `showScrollToPresentButton` prop. */
+  scroll_to_present_visible?: boolean;
+  /** Overrides `showTurnStatus` prop. */
+  turn_status_visible?: boolean;
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Errors                                                                    */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Top-level error shape the React client hands to user-supplied `onError`
+ * callbacks. Distinct from the in-stream `AIHubSystemErrorEvent`: this is the
+ * library's outward error surface, used for both transport-level failures
+ * (network, 401, 5xx) and surfaced stream errors.
+ *
+ * @see SPECIFICATIONS.md §7.2 — provider props
+ */
+export interface AIHubError {
+  /** Machine-readable code; clients use this for branching, not `message`. */
+  code:
+    | "unauthorized"
+    | "forbidden"
+    | "not_found"
+    | "validation"
+    | "network"
+    | "tpm_exhausted"
+    | "provider_error"
+    | "internal"
+    | (string & {});
+  /** Human-readable message; safe to render to end-users. */
+  message: string;
+  /** HTTP status, when the error originated from a server response. */
+  status?: number;
+  /** Pino `request_id` for log correlation when available. */
+  request_id?: string;
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Slot props — Tier 2 / Tier 3 customization renderers                      */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Renderer for the action bar of every message bubble. Tier 2 wrappers pass
+ * one of these via `customMessageActions` on `<DataClubAIHub />`; Tier 3
+ * wrappers pass the same shape via `renderMessageActions` on
+ * `<AIHub.MessageList />`.
+ *
+ * Returning `null` (or an empty fragment) disables the action bar for that
+ * message.
+ *
+ * @see SPECIFICATIONS.md §7.3 — `<DataClubAIHub />` props
+ * @see SPECIFICATIONS.md §7.9 — primitive composition
+ */
+export type AIHubMessageActionRenderer = (msg: AIHubMessage) => unknown;
+
+/**
+ * Renderer that replaces the entire message bubble. Advanced — most wrappers
+ * should use `AIHubMessageActionRenderer` instead. Tier 2: `customMessageBubble`;
+ * Tier 3: `renderMessageBubble` on `<AIHub.MessageList />`.
+ *
+ * @see SPECIFICATIONS.md §7.3
+ * @see SPECIFICATIONS.md §7.9
+ */
+export type AIHubMessageBubbleRenderer = (msg: AIHubMessage) => unknown;
+
+/**
+ * Aggregated slot-prop bag — convenience type for wrappers that pass a single
+ * options object instead of individual props. The fields mirror the slot props
+ * on `<DataClubAIHub />` (§7.3).
+ *
+ * `unknown` (rather than React.ReactNode) is used here so this types module
+ * stays React-version-agnostic; the React package re-exports a stricter
+ * variant from `index.ts` once React is in scope.
+ *
+ * @see SPECIFICATIONS.md §7.3 — slot props
+ */
+export interface AIHubSlotProps {
+  /**
+   * Replaces the default gradient text logo in the shell header. Per-customer
+   * wrappers populate this with their logo + brand name + nav links.
+   */
+  customShellHeaderLeft?: unknown;
+  /**
+   * Renders a footer strip below `main_area`. Unset (default) → no footer.
+   */
+  customShellFooter?: unknown;
+  /**
+   * Rendered next to the agent name + turn-status indicator inside the chat
+   * column header (distinct from the shell header above).
+   */
+  customHeaderContent?: unknown;
+  /** Per-message action bar slot (e.g. thumbs-up / thumbs-down). */
+  customMessageActions?: AIHubMessageActionRenderer;
+  /** Override the entire message bubble — advanced. */
+  customMessageBubble?: AIHubMessageBubbleRenderer;
+  /** Extra items in the input toolbar (next to the effort dropdown). */
+  customInputToolbarItems?: unknown;
+  /** Top-of-sessions-panel slot. */
+  customSidebarHeader?: unknown;
+  /** Bottom-of-sessions-panel slot. */
+  customSidebarFooter?: unknown;
+}