@data-club/ai-hub 0.0.1

package/dist/types.d.ts

@@ -0,0 +1,787 @@
+/**
+ * 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
+ */
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map