@data-club/ai-hub 0.0.1

package/dist/client/AIHubClient.d.ts

@@ -0,0 +1,1058 @@
+/**
+ * `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 { type TokenStorage, type TokenStorageMode } from "./tokenStorage.js";
+/**
+ * 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-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;
+}
+/** 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;
+    };
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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 declare class AIHubRequestError extends Error implements AIHubError {
+    /** Machine-readable code; clients branch on this rather than the message. */
+    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);
+}
+/**
+ * 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 declare class AIHubClient {
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly tokenStore;
+    private readonly onUnauthorized?;
+    /** Guards against firing `onUnauthorized` more than once per 401 storm. */
+    private unauthorizedFired;
+    /**
+     * @param options - constructor options. `baseUrl` is required; everything
+     *   else has a sensible default.
+     */
+    constructor(options: AIHubClientOptions);
+    /** Returns the currently-stored token, or null. */
+    getToken(): string | null;
+    /**
+     * 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;
+    /** Clears the stored token. Idempotent. */
+    clearToken(): void;
+    /**
+     * `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.
+     */
+    login(username: string, password: string): Promise<LoginResponse>;
+    /**
+     * `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.
+     */
+    changePassword(currentPassword: string | null, newPassword: string): Promise<{
+        token: string;
+    }>;
+    /**
+     * `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.
+     */
+    logout(): Promise<void>;
+    /**
+     * `GET /auth/me` — fetches the `{ user, deployment }` envelope.
+     */
+    me(): Promise<AIHubAuthContext>;
+    /**
+     * `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.
+     */
+    getFeatureToggles(): Promise<AIHubFeatureToggles>;
+    /**
+     * `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"`).
+     */
+    updatePreferences(prefs: {
+        theme?: "light" | "dark";
+    }): Promise<AIHubAuthContext>;
+    /**
+     * `GET /sessions?agent_id=...&include_archived=...`.
+     *
+     * @param options - filter arguments; `agentId` is required.
+     */
+    listSessions(options: ListSessionsOptions): Promise<Session[]>;
+    /**
+     * `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.
+     */
+    createSession(options: CreateSessionOptions): Promise<Session>;
+    /** `GET /sessions/:id`. */
+    getSession(id: string): Promise<Session>;
+    /**
+     * `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.
+     */
+    patchSession(id: string, patch: PatchSessionOptions): Promise<Session>;
+    /**
+     * `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.
+     */
+    patchSessionReasoning(id: string, patch: PatchSessionReasoningOptions): Promise<Session>;
+    /** `GET /sessions/:id/messages`. */
+    getSessionMessages(id: string): Promise<AIHubMessage[]>;
+    /**
+     * `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.
+     */
+    listMessageOverrides(sessionId: string): Promise<AIHubMessageOverride[]>;
+    /**
+     * `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.
+     */
+    setMessageOverride(sessionId: string, ordinalPosition: number, override: {
+        systemOverride?: string;
+        userOverride?: string;
+    }): Promise<AIHubMessageOverride>;
+    /**
+     * `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.
+     */
+    deleteMessageOverride(sessionId: string, ordinalPosition: number): Promise<void>;
+    /**
+     * `GET /agents` — returns the user-facing agent catalog (non-archived
+     * only) with each entry's `session_count` scoped to the caller.
+     */
+    listAgents(): Promise<AgentSummary[]>;
+    /**
+     * `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>;
+    /**
+     * `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>;
+    /** `POST /chat/:turn_id/cancel`. */
+    cancelTurn(turnId: string): Promise<CancelTurnResponse>;
+    /**
+     * `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.
+     */
+    listAdminUsers(): Promise<AdminUserView[]>;
+    /**
+     * `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).
+     */
+    createAdminUser(body: CreateUserBody): Promise<CreateUserResponse>;
+    /**
+     * `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).
+     */
+    patchAdminUserRole(id: string, role: AIHubRole): Promise<AdminUserView>;
+    /**
+     * `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).
+     */
+    resetAdminUserPassword(id: string): Promise<AdminUserPasswordReveal>;
+    /**
+     * `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).
+     */
+    deleteAdminUser(id: string): Promise<void>;
+    /**
+     * `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.
+     */
+    listAdminAgents(): Promise<AdminAgentView[]>;
+    /**
+     * `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`.
+     */
+    createAdminAgent(body: CreateAdminAgentBody): Promise<AdminAgentView>;
+    /**
+     * `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.
+     */
+    patchAdminAgent(id: string, body: PatchAdminAgentBody): Promise<AdminAgentView>;
+    /**
+     * `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.
+     */
+    listAdminRotatingMessages(): Promise<AdminRotatingMessageView[]>;
+    /**
+     * `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`.
+     */
+    createAdminRotatingMessage(body: CreateAdminRotatingMessageBody): Promise<AdminRotatingMessageView>;
+    /**
+     * `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`.
+     */
+    patchAdminRotatingMessage(id: string, body: PatchAdminRotatingMessageBody): Promise<AdminRotatingMessageView>;
+    /**
+     * `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`.
+     */
+    rotateAdminRotatingMessageNow(id: string): Promise<RotateNowResponse>;
+    /**
+     * `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.
+     */
+    listAdminSessions(options?: ListAdminSessionsOptions): Promise<ListAdminSessionsResponse>;
+    /**
+     * `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.
+     */
+    getAdminSessionMessages(id: string): Promise<AIHubMessage[]>;
+    /**
+     * 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`.
+     */
+    purgeAdminSessionSandbox(id: string): Promise<void>;
+    /**
+     * `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.
+     */
+    getAdminSettings(): Promise<AdminSettingsView>;
+    /**
+     * `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.
+     */
+    patchAdminSettings(body: PatchAdminSettingsBody): Promise<AdminSettingsView>;
+    /**
+     * `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.
+     */
+    getAdminFeatureToggles(): Promise<AIHubFeatureToggles>;
+    /**
+     * `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.
+     */
+    patchAdminFeatureToggles(toggles: AIHubFeatureToggles): Promise<AIHubFeatureToggles>;
+    /**
+     * `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.
+     */
+    rotateAdminSigningKey(): Promise<void>;
+    /**
+     * `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.
+     */
+    rotateAdminMetricsToken(): Promise<AdminMetricsTokenRotateResponse>;
+    /**
+     * 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 requestJson;
+    /**
+     * 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 streamRequest;
+    /**
+     * Clears the token and fires the unauthorized callback (at most once per
+     * 401 storm — the flag resets on next `setToken`).
+     */
+    private handleUnauthorized;
+    /**
+     * 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 errorFromResponse;
+}
+//# sourceMappingURL=AIHubClient.d.ts.map