@data-club/ai-hub 0.0.1

package/dist/client/AIHubClient.js

@@ -0,0 +1,950 @@
+/**
+ * `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 { parseSseStream } from "./sseParser.js";
+import { resolveTokenStorage, } from "./tokenStorage.js";
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Internal helpers                                                           */
+/* ────────────────────────────────────────────────────────────────────────── */
+/**
+ * Thrown for any HTTP-level failure (non-2xx, network drop, etc.). The
+ * `code` discriminates by §7.2's `AIHubError` codes; the message is safe
+ * to render to end-users (it's either the server's `error.message` or a
+ * fixed transport-level string).
+ */
+export class AIHubRequestError extends Error {
+    /** Machine-readable code; clients branch on this rather than the message. */
+    name = "AIHubRequestError";
+    /** Discriminator matching `AIHubError.code`. */
+    code;
+    /** HTTP status when one was available. */
+    status;
+    /** Pino `request_id` from the server for log correlation. */
+    request_id;
+    /**
+     * @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, message, status, requestId) {
+        super(message);
+        this.code = code;
+        if (status !== undefined)
+            this.status = status;
+        if (requestId !== undefined)
+            this.request_id = requestId;
+    }
+}
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  AIHubClient                                                                */
+/* ────────────────────────────────────────────────────────────────────────── */
+/**
+ * The typed SDK every React surface in the library is built on.
+ *
+ * The client owns the JWT lifecycle (storage + clearing on 401) and the
+ * SSE plumbing; everything else is a thin HTTP wrapper that translates
+ * camelCase arguments into the server's snake_case wire format.
+ *
+ * @example
+ * ```ts
+ * const client = new AIHubClient({ baseUrl: "/api/ai-hub" });
+ * const { token, mustChangePassword, user } = await client.login("alice", "secret");
+ * if (!mustChangePassword) {
+ *   for await (const event of client.streamChat({
+ *     sessionId: session.id,
+ *     userMessage: "Hello.",
+ *   })) {
+ *     console.log(event);
+ *   }
+ * }
+ * ```
+ */
+export class AIHubClient {
+    baseUrl;
+    fetchImpl;
+    tokenStore;
+    onUnauthorized;
+    /** Guards against firing `onUnauthorized` more than once per 401 storm. */
+    unauthorizedFired = false;
+    /**
+     * @param options - constructor options. `baseUrl` is required; everything
+     *   else has a sensible default.
+     */
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, "");
+        this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.tokenStore = resolveTokenStorage(options.tokenStorage ?? "localStorage");
+        if (options.onUnauthorized)
+            this.onUnauthorized = options.onUnauthorized;
+    }
+    /* ───── token surface ──────────────────────────────────────────────── */
+    /** Returns the currently-stored token, or null. */
+    getToken() {
+        return this.tokenStore.get();
+    }
+    /**
+     * Replaces the stored token. Used by the provider after `login` /
+     * `changePassword` to persist the JWT before the next request fires.
+     *
+     * @param token - the bearer JWT to store.
+     */
+    setToken(token) {
+        this.tokenStore.set(token);
+        this.unauthorizedFired = false;
+    }
+    /** Clears the stored token. Idempotent. */
+    clearToken() {
+        this.tokenStore.clear();
+    }
+    /* ───── auth ───────────────────────────────────────────────────────── */
+    /**
+     * `POST /auth/login`. On success, persists the returned token automatically
+     * so subsequent calls authenticate without the caller threading the JWT
+     * through.
+     *
+     * @param username - the user's login id.
+     * @param password - plaintext password (sent over HTTPS to the server).
+     * @returns the login response, with `mustChangePassword` camelcased.
+     */
+    async login(username, password) {
+        const raw = await this.requestJson("POST", "/auth/login", {
+            body: { username, password },
+            authenticated: false,
+        });
+        this.setToken(raw.token);
+        const response = {
+            token: raw.token,
+            mustChangePassword: raw.must_change_password,
+            user: raw.user,
+        };
+        if (raw.deployment)
+            response.deployment = raw.deployment;
+        return response;
+    }
+    /**
+     * `POST /auth/change-password`. Returns the fresh session token (the
+     * change-only token is consumed by this call).
+     *
+     * @param currentPassword - the user's existing password, or null when
+     *   the caller is authenticating with a password-change-only token
+     *   (forced-change flow — §8.5).
+     * @param newPassword - the new password. Must satisfy the §8.5 policy
+     *   (≥8 chars, ≥2 of {letters, digits, special}).
+     * @returns the new session token, persisted automatically.
+     */
+    async changePassword(currentPassword, newPassword) {
+        const body = { new_password: newPassword };
+        if (currentPassword !== null)
+            body.current_password = currentPassword;
+        const result = await this.requestJson("POST", "/auth/change-password", { body });
+        this.setToken(result.token);
+        return result;
+    }
+    /**
+     * `POST /auth/logout`. Server-side this is a no-op in v1 (no token
+     * blacklist — §6.3.4); we issue it for symmetry and to give the server
+     * an audit-log entry. Always clears the local token afterward, even
+     * when the request fails.
+     */
+    async logout() {
+        try {
+            await this.requestJson("POST", "/auth/logout", { body: {} });
+        }
+        catch {
+            /* network errors here are not fatal — clear and move on */
+        }
+        finally {
+            this.clearToken();
+        }
+    }
+    /**
+     * `GET /auth/me` — fetches the `{ user, deployment }` envelope.
+     */
+    async me() {
+        return this.requestJson("GET", "/auth/me");
+    }
+    /**
+     * `GET /feature-toggles` — fetches the deployment-wide UI feature
+     * toggles set by `super_admin` (§8.4). **Unauthenticated** — no token
+     * required, every role gets the same response. The provider calls this
+     * on mount so the §8.4 precedence ("server toggle > React prop >
+     * built-in default") applies before the chat shell first renders.
+     *
+     * Missing keys are returned absent in the response (not coerced to
+     * `false`) so the client can distinguish "explicitly off" from "fall
+     * through to the React prop default."
+     *
+     * @returns the wire-format toggles blob; may be empty (`{}`) when the
+     *   super_admin hasn't set anything.
+     */
+    async getFeatureToggles() {
+        const result = await this.requestJson("GET", "/feature-toggles");
+        return result.feature_toggles ?? {};
+    }
+    /**
+     * `PATCH /auth/me/preferences` — updates the caller's stored
+     * `theme_preference`. Returns the refreshed envelope.
+     *
+     * Rejected with `AIHubRequestError(code: "theme_switcher_disabled")` (HTTP
+     * 409) when the deployment has the switcher turned off (§7.6).
+     *
+     * @param prefs - the preferences patch (currently only `theme`).
+     * @param prefs.theme - new theme preference (`"light"` or `"dark"`).
+     */
+    async updatePreferences(prefs) {
+        return this.requestJson("PATCH", "/auth/me/preferences", { body: prefs });
+    }
+    /* ───── sessions ───────────────────────────────────────────────────── */
+    /**
+     * `GET /sessions?agent_id=...&include_archived=...`.
+     *
+     * @param options - filter arguments; `agentId` is required.
+     */
+    async listSessions(options) {
+        const query = new URLSearchParams({ agent_id: options.agentId });
+        if (options.includeArchived)
+            query.set("include_archived", "true");
+        const result = await this.requestJson("GET", `/sessions?${query.toString()}`);
+        return result.sessions;
+    }
+    /**
+     * `POST /sessions`.
+     *
+     * Client-side validation: title must be 1..80 chars. Empty / oversize
+     * titles throw `AIHubRequestError(code: "validation")` synchronously
+     * without an HTTP round-trip.
+     *
+     * @param options - the agent id + non-empty title.
+     * @returns the created session row.
+     */
+    async createSession(options) {
+        const title = options.title;
+        if (typeof title !== "string" || title.length === 0) {
+            throw new AIHubRequestError("validation", "Session title is required (1..80 characters).");
+        }
+        if (title.length > 80) {
+            throw new AIHubRequestError("validation", "Session title must be 80 characters or fewer.");
+        }
+        return this.requestJson("POST", "/sessions", {
+            body: { agent_id: options.agentId, title },
+        });
+    }
+    /** `GET /sessions/:id`. */
+    async getSession(id) {
+        return this.requestJson("GET", `/sessions/${encodeURIComponent(id)}`);
+    }
+    /**
+     * `PATCH /sessions/:id` — rename and/or archive in one call. An empty
+     * patch (`{}`) returns the row unchanged.
+     *
+     * @param id - the session id.
+     * @param patch - the fields to update.
+     */
+    async patchSession(id, patch) {
+        const body = {};
+        if (patch.title !== undefined)
+            body.title = patch.title;
+        if (patch.isArchived !== undefined)
+            body.is_archived = patch.isArchived;
+        return this.requestJson("PATCH", `/sessions/${encodeURIComponent(id)}`, { body });
+    }
+    /**
+     * `PATCH /sessions/:id/reasoning` — update the user's per-session reasoning
+     * settings. The server applies them to the agent's `model_settings`
+     * automatically before the next chat turn.
+     *
+     * Returns the refreshed session including `capabilities`, so the caller
+     * can re-render UI controls without a separate GET.
+     */
+    async patchSessionReasoning(id, patch) {
+        const body = {};
+        if (patch.effort !== undefined)
+            body.effort = patch.effort;
+        if (patch.verbosity !== undefined)
+            body.verbosity = patch.verbosity;
+        if (patch.thinkingBudget !== undefined)
+            body.thinking_budget = patch.thinkingBudget;
+        return this.requestJson("PATCH", `/sessions/${encodeURIComponent(id)}/reasoning`, { body });
+    }
+    /** `GET /sessions/:id/messages`. */
+    async getSessionMessages(id) {
+        const result = await this.requestJson("GET", `/sessions/${encodeURIComponent(id)}/messages`);
+        return result.messages;
+    }
+    /* ───── message overrides ──────────────────────────────────────────── */
+    /**
+     * `GET /sessions/:id/message-overrides` — returns the caller's per-message
+     * content substitutions for this session's underlying Letta conversation.
+     *
+     * Overrides are keyed by `ordinal_position` (0-based index into Letta's
+     * chronologically-sorted message list). They're applied automatically by
+     * `getSessionMessages` — callers don't need to merge manually; this
+     * endpoint exists so custom Tier-3 UIs can render an edit affordance
+     * next to each message that has an override.
+     *
+     * @param sessionId - the ai-hub session id.
+     * @returns the overrides sorted by `ordinal_position` ascending.
+     */
+    async listMessageOverrides(sessionId) {
+        const result = await this.requestJson("GET", `/sessions/${encodeURIComponent(sessionId)}/message-overrides`);
+        return result.overrides;
+    }
+    /**
+     * `PUT /sessions/:id/message-overrides/:position` — upsert one or both
+     * override layers for the message at `ordinalPosition`.
+     *
+     * Pass `systemOverride` to set the LLM-facing view, `userOverride` to
+     * set the UI-facing view, or both. At least one must be provided.
+     * **Merge semantics**: only the layer(s) you pass are written; an
+     * existing value on the other layer is preserved.
+     *
+     * **Validation gates** (server-enforced):
+     *
+     * - `409 turn_in_progress` — a turn is currently live for this session.
+     * - `409 message_not_found` — no Letta message exists at this position
+     *   yet (typical when a tier-3 caller tries to override a message
+     *   before it has landed; wait for the turn to finish first).
+     *
+     * Pass empty string for `userOverride` to visually hide the message
+     * (the bubble slot stays — use `deleteMessageOverride` to remove the
+     * slot entirely).
+     *
+     * @param sessionId - the ai-hub session id.
+     * @param ordinalPosition - the 0-based index in Letta's message list.
+     * @param override - one or both layers to write.
+     * @returns the resulting override row.
+     */
+    async setMessageOverride(sessionId, ordinalPosition, override) {
+        const body = {};
+        if (override.systemOverride !== undefined)
+            body.system_override = override.systemOverride;
+        if (override.userOverride !== undefined)
+            body.user_override = override.userOverride;
+        return this.requestJson("PUT", `/sessions/${encodeURIComponent(sessionId)}/message-overrides/${ordinalPosition}`, { body });
+    }
+    /**
+     * `DELETE /sessions/:id/message-overrides/:position` — remove an override.
+     *
+     * Idempotent: returns successfully whether or not the row existed.
+     *
+     * @param sessionId - the ai-hub session id.
+     * @param ordinalPosition - the 0-based index in Letta's message list.
+     */
+    async deleteMessageOverride(sessionId, ordinalPosition) {
+        await this.requestJson("DELETE", `/sessions/${encodeURIComponent(sessionId)}/message-overrides/${ordinalPosition}`);
+    }
+    /* ───── agents ─────────────────────────────────────────────────────── */
+    /**
+     * `GET /agents` — returns the user-facing agent catalog (non-archived
+     * only) with each entry's `session_count` scoped to the caller.
+     */
+    async listAgents() {
+        const result = await this.requestJson("GET", "/agents");
+        return result.agents;
+    }
+    /* ───── chat ───────────────────────────────────────────────────────── */
+    /**
+     * `POST /chat` — opens an SSE stream. Returns an async iterable of
+     * `AIHubEvent`s; consume with `for await (const event of …)`.
+     *
+     * The iterable terminates when the server emits `stream_end` (the bytes
+     * stop after that). To abort early, pass `opts.signal`.
+     *
+     * @param body - the request body (sessionId, userMessage, optional effort,
+     *   optional idempotencyKey).
+     * @param opts - optional abort signal and resumption hint.
+     */
+    streamChat(body, opts = {}) {
+        const wireBody = {
+            session_id: body.sessionId,
+            user_message: body.userMessage,
+        };
+        if (body.effort !== undefined)
+            wireBody.effort = body.effort;
+        if (body.idempotencyKey !== undefined) {
+            wireBody.idempotency_key = body.idempotencyKey;
+        }
+        if (body.userOverride !== undefined) {
+            wireBody.user_override = body.userOverride;
+        }
+        return this.streamRequest("POST", "/chat", wireBody, opts);
+    }
+    /**
+     * `GET /chat/:turn_id/events?from_seq=N` — resumption replay then
+     * live-attach.
+     *
+     * @param turnId - the turn to resume.
+     * @param opts - optional abort signal and `fromSeq` cursor (defaults to
+     *   `-1` so every persisted event is replayed).
+     */
+    getTurnEvents(turnId, opts = {}) {
+        const fromSeq = opts.fromSeq ?? -1;
+        const path = `/chat/${encodeURIComponent(turnId)}/events?from_seq=${encodeURIComponent(String(fromSeq))}`;
+        return this.streamRequest("GET", path, undefined, opts);
+    }
+    /** `POST /chat/:turn_id/cancel`. */
+    async cancelTurn(turnId) {
+        return this.requestJson("POST", `/chat/${encodeURIComponent(turnId)}/cancel`, { body: {} });
+    }
+    /* ───── admin: users ───────────────────────────────────────────────── */
+    /**
+     * `GET /admin/users` — fetches every user row in the deployment.
+     *
+     * Caller must be `admin` or `super_admin`; the server returns 403
+     * otherwise (the SDK surfaces it as `AIHubRequestError(code: "forbidden")`).
+     *
+     * @returns the user rows, sorted alphabetically by username.
+     * @throws {AIHubRequestError} `forbidden` for `user` / `power_user` callers.
+     */
+    async listAdminUsers() {
+        const result = await this.requestJson("GET", "/admin/users");
+        return result.users;
+    }
+    /**
+     * `POST /admin/users` — creates a user; the server generates the password.
+     *
+     * Returns the new row plus the **one-time** plaintext password
+     * (`generatedPassword`). The caller is responsible for surfacing it
+     * exactly once in the UI — there is no way to retrieve it later.
+     *
+     * Admins cannot create `super_admin`s (server returns 403 if the body
+     * requests it). On username collision returns 409 `username_taken`.
+     *
+     * @param body - the new user's identity + initial role.
+     * @returns the created row and the one-time password.
+     * @throws {AIHubRequestError} `forbidden` (caller role insufficient or
+     *   admin tried to grant super_admin), `validation` (malformed body),
+     *   or `username_taken` (409).
+     */
+    async createAdminUser(body) {
+        const wireBody = { username: body.username };
+        if (body.displayName !== undefined) {
+            wireBody.display_name = body.displayName;
+        }
+        if (body.role !== undefined)
+            wireBody.role = body.role;
+        const result = await this.requestJson("POST", "/admin/users", { body: wireBody });
+        return {
+            user: result.user,
+            generatedPassword: result.generated_password,
+        };
+    }
+    /**
+     * `PATCH /admin/users/:id/role` — changes a user's role.
+     *
+     * The server enforces the admin-shield + super-admin-min-count rules
+     * transactionally (§8.1). Violations come back as 403 with codes like
+     * `admin_shield`, `super_admin_min_count`, or `forbidden`.
+     *
+     * @param id - the target user's id.
+     * @param role - the new role.
+     * @returns the updated row.
+     * @throws {AIHubRequestError} `forbidden` (shield / min-count / caller
+     *   cannot grant this role).
+     */
+    async patchAdminUserRole(id, role) {
+        const result = await this.requestJson("PATCH", `/admin/users/${encodeURIComponent(id)}/role`, { body: { role } });
+        return result.user;
+    }
+    /**
+     * `POST /admin/users/:id/reset-password` — issues a fresh password.
+     *
+     * Sets `is_initial_password = true` on the target. The new plaintext is
+     * returned **exactly once** in `generatedPassword`; the admin UI must
+     * surface it via the one-time-reveal modal.
+     *
+     * @param id - the target user's id.
+     * @returns the one-time plaintext.
+     * @throws {AIHubRequestError} `forbidden` (shield / min-count).
+     */
+    async resetAdminUserPassword(id) {
+        const result = await this.requestJson("POST", `/admin/users/${encodeURIComponent(id)}/reset-password`, { body: {} });
+        return { generatedPassword: result.generated_password };
+    }
+    /**
+     * `DELETE /admin/users/:id` — hard-deletes a user.
+     *
+     * Cascades to that user's sessions via the FK. The server blocks
+     * self-delete (returns 403) so a careless click can't brick the caller's
+     * own account; shield + min-count apply as for role change.
+     *
+     * @param id - the target user's id.
+     * @throws {AIHubRequestError} `forbidden` (shield, min-count, or
+     *   attempting to delete oneself).
+     */
+    async deleteAdminUser(id) {
+        await this.requestJson("DELETE", `/admin/users/${encodeURIComponent(id)}`);
+    }
+    /* ───── admin: agents ──────────────────────────────────────────────── */
+    /**
+     * `GET /admin/agents` — every ai-hub agent in the deployment, including
+     * archived ones. Caller must be `power_user`+ per §8.2.
+     *
+     * Sort order: ascending by `display_name` (the server's `ORDER BY`).
+     *
+     * @returns the agent rows.
+     * @throws {AIHubRequestError} `forbidden` for `user` callers.
+     */
+    async listAdminAgents() {
+        const result = await this.requestJson("GET", "/admin/agents");
+        return result.agents;
+    }
+    /**
+     * `POST /admin/agents` — register a new ai-hub agent in the catalog.
+     *
+     * The server validates `lettaAgentId` against Letta; if the id isn't
+     * resolvable the response is 400 `letta_agent_not_found` (surface inline
+     * on the form field).
+     *
+     * @param body - the display name + assigned Letta agent id.
+     * @returns the newly-created row.
+     * @throws {AIHubRequestError} `letta_agent_not_found`, `validation`, `forbidden`.
+     */
+    async createAdminAgent(body) {
+        const wire = {
+            display_name: body.displayName,
+            letta_agent_id: body.lettaAgentId,
+        };
+        if (body.sandboxSeedName !== undefined) {
+            wire.sandbox_seed_name = body.sandboxSeedName;
+        }
+        if (body.forkSourceConversationId !== undefined) {
+            wire.fork_source_conversation_id = body.forkSourceConversationId;
+        }
+        return this.requestJson("POST", "/admin/agents", {
+            body: wire,
+        });
+    }
+    /**
+     * `PATCH /admin/agents/:id` — update one or more fields. Every field is
+     * optional; an empty patch is a 200 no-op.
+     *
+     * Archive / unarchive flows through this same endpoint via `isArchived`.
+     *
+     * @param id - the ai-hub agent id.
+     * @param body - the fields to update.
+     * @returns the refreshed row.
+     * @throws {AIHubRequestError} `letta_agent_not_found` if `lettaAgentId`
+     *   was supplied and doesn't resolve in Letta.
+     */
+    async patchAdminAgent(id, body) {
+        const wire = {};
+        if (body.displayName !== undefined)
+            wire.display_name = body.displayName;
+        if (body.lettaAgentId !== undefined)
+            wire.letta_agent_id = body.lettaAgentId;
+        if (body.isArchived !== undefined)
+            wire.is_archived = body.isArchived;
+        if (body.sandboxSeedName !== undefined) {
+            wire.sandbox_seed_name = body.sandboxSeedName;
+        }
+        if (body.forkSourceConversationId !== undefined) {
+            wire.fork_source_conversation_id = body.forkSourceConversationId;
+        }
+        return this.requestJson("PATCH", `/admin/agents/${encodeURIComponent(id)}`, { body: wire });
+    }
+    /* ───── admin: rotating messages ────────────────────────────────────── */
+    /**
+     * `GET /admin/rotating-messages` — every rotating starting message in the
+     * deployment (archived included), sorted by display name. `power_user`+.
+     *
+     * @returns the rows.
+     * @throws {AIHubRequestError} `forbidden` for `user` callers.
+     */
+    async listAdminRotatingMessages() {
+        const result = await this.requestJson("GET", "/admin/rotating-messages");
+        return result.rotating_messages;
+    }
+    /**
+     * `POST /admin/rotating-messages` — create a rotating starting message. The
+     * server validates `lettaAgentId` against Letta (`letta_agent_not_found`)
+     * and the schedule shape (`invalid_schedule`).
+     *
+     * @param body - the prompt, agent, and schedule config.
+     * @returns the newly-created row (including its `rmsg-…` id).
+     * @throws {AIHubRequestError} `letta_agent_not_found`, `invalid_schedule`, `validation`, `forbidden`.
+     */
+    async createAdminRotatingMessage(body) {
+        const wire = {
+            display_name: body.displayName,
+            prompt: body.prompt,
+            letta_agent_id: body.lettaAgentId,
+            schedule_kind: body.scheduleKind,
+        };
+        if (body.intervalSeconds !== undefined)
+            wire.interval_seconds = body.intervalSeconds;
+        if (body.dailyTime !== undefined)
+            wire.daily_time = body.dailyTime;
+        if (body.cronExpression !== undefined)
+            wire.cron_expression = body.cronExpression;
+        return this.requestJson("POST", "/admin/rotating-messages", { body: wire });
+    }
+    /**
+     * `PATCH /admin/rotating-messages/:id` — update one or more fields. Every
+     * field is optional; an empty patch is a 200 no-op. Changing the schedule
+     * recomputes the next rotation time.
+     *
+     * @param id - the rotating message id.
+     * @param body - the fields to update.
+     * @returns the refreshed row.
+     * @throws {AIHubRequestError} `letta_agent_not_found`, `invalid_schedule`, `not_found`, `forbidden`.
+     */
+    async patchAdminRotatingMessage(id, body) {
+        const wire = {};
+        if (body.displayName !== undefined)
+            wire.display_name = body.displayName;
+        if (body.prompt !== undefined)
+            wire.prompt = body.prompt;
+        if (body.lettaAgentId !== undefined)
+            wire.letta_agent_id = body.lettaAgentId;
+        if (body.scheduleKind !== undefined)
+            wire.schedule_kind = body.scheduleKind;
+        if (body.intervalSeconds !== undefined)
+            wire.interval_seconds = body.intervalSeconds;
+        if (body.dailyTime !== undefined)
+            wire.daily_time = body.dailyTime;
+        if (body.cronExpression !== undefined)
+            wire.cron_expression = body.cronExpression;
+        if (body.isArchived !== undefined)
+            wire.is_archived = body.isArchived;
+        return this.requestJson("PATCH", `/admin/rotating-messages/${encodeURIComponent(id)}`, { body: wire });
+    }
+    /**
+     * `POST /admin/rotating-messages/:id/rotate-now` — run a rotation inline
+     * (preview / force-refresh). May take a while — it spawns the Letta Code
+     * subprocess like a real chat turn.
+     *
+     * @param id - the rotating message id.
+     * @returns the refreshed row plus the attempt's outcome.
+     * @throws {AIHubRequestError} `not_found`, `forbidden`.
+     */
+    async rotateAdminRotatingMessageNow(id) {
+        return this.requestJson("POST", `/admin/rotating-messages/${encodeURIComponent(id)}/rotate-now`, { body: {} });
+    }
+    /* ───── admin: sessions overview ───────────────────────────────────── */
+    /**
+     * `GET /admin/sessions` — paginated read-only browser over every session
+     * in the deployment. `power_user`+ per §8.2.
+     *
+     * Each row carries `owner_username` + `agent_display_name` joined
+     * server-side. Use `nextCursor` (when non-null) as the `cursor` for the
+     * next page.
+     *
+     * @param options - filter + pagination args. All optional.
+     * @returns the page plus the next-cursor.
+     */
+    async listAdminSessions(options = {}) {
+        const query = new URLSearchParams();
+        if (options.ownerId !== undefined)
+            query.set("owner_id", options.ownerId);
+        if (options.agentId !== undefined)
+            query.set("agent_id", options.agentId);
+        if (options.status !== undefined)
+            query.set("status", options.status);
+        if (options.search !== undefined && options.search.length > 0) {
+            query.set("search", options.search);
+        }
+        if (options.cursor !== undefined)
+            query.set("cursor", options.cursor);
+        if (options.limit !== undefined)
+            query.set("limit", String(options.limit));
+        const qs = query.toString();
+        const path = qs.length > 0 ? `/admin/sessions?${qs}` : "/admin/sessions";
+        const result = await this.requestJson("GET", path);
+        return { sessions: result.sessions, nextCursor: result.next_cursor };
+    }
+    /**
+     * `GET /admin/sessions/:id/messages` — read-only history for any session
+     * (cross-user). Returns the same `AIHubMessage[]` shape as the user-facing
+     * `getSessionMessages` so the same `<MessageBubble />` rendering can be
+     * reused.
+     *
+     * @param id - any session id in the deployment.
+     * @returns the projected message list.
+     * @throws {AIHubRequestError} `forbidden` for `user` callers, `not_found`
+     *   if the session id doesn't exist.
+     */
+    async getAdminSessionMessages(id) {
+        const result = await this.requestJson("GET", `/admin/sessions/${encodeURIComponent(id)}/messages`);
+        return result.messages;
+    }
+    /**
+     * Step-12.5 — `POST /admin/sessions/:id/purge-sandbox`.
+     *
+     * Removes the per-session sandbox folder from disk + clears
+     * `session.sandbox_dir`. Idempotent: 204 on success regardless of
+     * whether the session ever had a sandbox. Rejects with
+     * `409 turn_running` if a chat turn is live for the session.
+     *
+     * `super_admin` only — `admin` / `power_user` callers get 403.
+     *
+     * @param id - the ai-hub session id.
+     * @throws {AIHubRequestError} `turn_running`, `forbidden`, `not_found`.
+     */
+    async purgeAdminSessionSandbox(id) {
+        await this.requestJson("POST", `/admin/sessions/${encodeURIComponent(id)}/purge-sandbox`);
+    }
+    /* ───── admin: settings ────────────────────────────────────────────── */
+    /**
+     * `GET /admin/settings` — deployment-wide configuration (super_admin only).
+     *
+     * The Letta API key is never returned in plaintext; the response carries
+     * `letta_api_key_set` + `letta_api_key_masked` so the UI can render
+     * "configured / not configured" affordances.
+     */
+    async getAdminSettings() {
+        return this.requestJson("GET", "/admin/settings");
+    }
+    /**
+     * `PATCH /admin/settings` — update one or more deployment settings.
+     *
+     * The API key, when supplied, is encrypted under `AI_HUB_ENCRYPTION_KEY`
+     * server-side. Theme fields live as separate columns and follow the same
+     * precedence as the React props (server > prop > built-in default).
+     *
+     * @param body - the patch. Each field independent.
+     * @returns the refreshed settings view.
+     */
+    async patchAdminSettings(body) {
+        const wire = {};
+        if (body.lettaBaseUrl !== undefined)
+            wire.letta_base_url = body.lettaBaseUrl;
+        if (body.lettaAdeUrl !== undefined)
+            wire.letta_ade_url = body.lettaAdeUrl;
+        if (body.lettaApiKey !== undefined)
+            wire.letta_api_key = body.lettaApiKey;
+        if (body.theme !== undefined) {
+            const themeWire = {};
+            if (body.theme.default !== undefined)
+                themeWire.default = body.theme.default;
+            if (body.theme.switcherEnabled !== undefined) {
+                themeWire.switcher_enabled = body.theme.switcherEnabled;
+            }
+            wire.theme = themeWire;
+        }
+        return this.requestJson("PATCH", "/admin/settings", {
+            body: wire,
+        });
+    }
+    /**
+     * `GET /admin/settings/feature-toggles` — the §8.4 toggle blob the
+     * super-admin sees. Same payload the `getFeatureToggles` (unauthenticated)
+     * endpoint returns, but gated and intended for the settings editor.
+     */
+    async getAdminFeatureToggles() {
+        const result = await this.requestJson("GET", "/admin/settings/feature-toggles");
+        return result.feature_toggles ?? {};
+    }
+    /**
+     * `PATCH /admin/settings/feature-toggles` — merge-patch the §8.4 toggle
+     * blob. Unknown keys are rejected with 400; the server's strict schema is
+     * the source of truth for which toggles are accepted.
+     *
+     * @param toggles - the partial — only the keys you want to write.
+     */
+    async patchAdminFeatureToggles(toggles) {
+        const result = await this.requestJson("PATCH", "/admin/settings/feature-toggles", { body: toggles });
+        return result.feature_toggles;
+    }
+    /**
+     * `POST /admin/settings/rotate-signing-key` — replace the JWT signing key
+     * in place. **Every outstanding JWT is invalidated immediately**, including
+     * the caller's own. The next protected request from the UI will 401 and
+     * the provider routes back to login (§6.7).
+     *
+     * Returns nothing — the new key never leaves the server.
+     */
+    async rotateAdminSigningKey() {
+        await this.requestJson("POST", "/admin/settings/rotate-signing-key", {
+            body: {},
+        });
+    }
+    /**
+     * `POST /admin/settings/rotate-metrics-token` — rotate the `/metrics`
+     * bearer token. The new token is returned **exactly once** in
+     * `{ token }`; subsequent `getAdminSettings` calls do NOT echo it back.
+     * The admin must copy it into their Prometheus / Alloy config before
+     * dismissing the reveal modal (§6.10).
+     *
+     * Does NOT invalidate the caller's JWT — only the metrics-scraper bearer
+     * changes.
+     */
+    async rotateAdminMetricsToken() {
+        return this.requestJson("POST", "/admin/settings/rotate-metrics-token", { body: {} });
+    }
+    /* ───── internal request plumbing ─────────────────────────────────── */
+    /**
+     * Sends a JSON request and parses the JSON response. Centralizes auth
+     * header injection, 401 handling, and error normalization.
+     *
+     * @param method - HTTP method.
+     * @param path - path under `baseUrl`.
+     * @param opts - optional body and unauthenticated-mode flag.
+     * @param opts.body - JSON body to send (omit for GET / DELETE).
+     * @param opts.authenticated - set to `false` to skip the bearer header
+     *   (login is the only such caller). Defaults to true.
+     * @returns the parsed response.
+     */
+    async requestJson(method, path, opts = {}) {
+        const headers = { Accept: "application/json" };
+        const authenticated = opts.authenticated !== false;
+        if (authenticated) {
+            const token = this.tokenStore.get();
+            if (token)
+                headers.Authorization = `Bearer ${token}`;
+        }
+        let body;
+        if (opts.body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            body = JSON.stringify(opts.body);
+        }
+        let response;
+        try {
+            response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+                method,
+                headers,
+                ...(body !== undefined ? { body } : {}),
+            });
+        }
+        catch (err) {
+            throw new AIHubRequestError("network", err instanceof Error ? err.message : "Network request failed.");
+        }
+        if (response.status === 401) {
+            this.handleUnauthorized();
+        }
+        if (!response.ok) {
+            throw await this.errorFromResponse(response);
+        }
+        // 204 / 205 / empty body
+        const ct = response.headers.get("content-type") ?? "";
+        if (response.status === 204 || !ct.includes("application/json")) {
+            return undefined;
+        }
+        return (await response.json());
+    }
+    /**
+     * 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`.
+     */
+    async *streamRequest(method, path, body, opts) {
+        const headers = { Accept: "text/event-stream" };
+        const token = this.tokenStore.get();
+        if (token)
+            headers.Authorization = `Bearer ${token}`;
+        let bodyInit;
+        if (body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            bodyInit = JSON.stringify(body);
+        }
+        let response;
+        try {
+            response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+                method,
+                headers,
+                ...(bodyInit !== undefined ? { body: bodyInit } : {}),
+                ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
+            });
+        }
+        catch (err) {
+            throw new AIHubRequestError("network", err instanceof Error ? err.message : "SSE request failed.");
+        }
+        if (response.status === 401)
+            this.handleUnauthorized();
+        if (!response.ok)
+            throw await this.errorFromResponse(response);
+        if (!response.body) {
+            throw new AIHubRequestError("internal", "SSE response had no body.");
+        }
+        for await (const event of parseSseStream(response.body)) {
+            yield event;
+        }
+    }
+    /**
+     * Clears the token and fires the unauthorized callback (at most once per
+     * 401 storm — the flag resets on next `setToken`).
+     */
+    handleUnauthorized() {
+        this.clearToken();
+        if (this.unauthorizedFired)
+            return;
+        this.unauthorizedFired = true;
+        this.onUnauthorized?.();
+    }
+    /**
+     * Builds an `AIHubRequestError` from a non-ok server response. Reads the
+     * server's `{ error: { code, message, request_id } }` envelope when
+     * present; falls back to status-code-derived defaults otherwise.
+     *
+     * @param response - the fetch response (status >= 400).
+     * @returns the normalized error.
+     */
+    async errorFromResponse(response) {
+        let envelope = {};
+        try {
+            const ct = response.headers.get("content-type") ?? "";
+            if (ct.includes("application/json")) {
+                envelope = (await response.json());
+            }
+        }
+        catch {
+            /* malformed body — fall through to defaults */
+        }
+        const errorBlock = envelope.error;
+        const wireCode = errorBlock?.code;
+        const message = errorBlock?.message ?? `Request failed with status ${response.status}.`;
+        const code = wireCode ?? defaultCodeForStatus(response.status);
+        return new AIHubRequestError(code, message, response.status, errorBlock?.request_id);
+    }
+}
+/**
+ * Maps an HTTP status to a default `AIHubError.code` when the server didn't
+ * include one in the response envelope.
+ */
+function defaultCodeForStatus(status) {
+    if (status === 401)
+        return "unauthorized";
+    if (status === 403)
+        return "forbidden";
+    if (status === 404)
+        return "not_found";
+    if (status >= 400 && status < 500)
+        return "validation";
+    if (status >= 500)
+        return "internal";
+    return "internal";
+}
+//# sourceMappingURL=AIHubClient.js.map