@data-club/ai-hub 0.0.1

package/src/context/AIHubContext.ts

@@ -0,0 +1,249 @@
+/**
+ * Internal React context shared by `<AIHubProvider>` + the `useAIHub` /
+ * `useAIHubAuth` hooks.
+ *
+ * Kept separate from `AIHubProvider.tsx` so the hooks can import the
+ * context object without pulling in the provider's component tree (and
+ * the JSX dependencies that come with it).
+ *
+ * @see SPECIFICATIONS.md §7.2 — provider + hooks
+ */
+
+import { createContext } from "react";
+
+import type {
+  AgentSummary,
+  AIHubClient,
+  LoginResponse,
+  PatchSessionOptions,
+} from "../client/AIHubClient.js";
+import type { AIHubEffort } from "../client/AIHubClient.js";
+import type {
+  AIHubAuthContext,
+  AIHubFeatureToggles,
+  AIHubMessage,
+  AIHubRole,
+  AIHubState,
+  AIHubToolCallRecord,
+  AIHubUser,
+  Session,
+} from "../types.js";
+
+/**
+ * The shape provided by `<AIHubProvider>` to its descendants. Hook
+ * implementations destructure this; consumers don't see it directly.
+ */
+export interface AIHubContextValue {
+  /** The underlying SDK — consumers can call any method directly. */
+  client: AIHubClient;
+
+  /* ── auth state ─────────────────────────────────────────────────── */
+  /** Currently authenticated user, or null when no valid token is present. */
+  user: AIHubUser | null;
+  /** Echoes `user.role` for convenience; null when unauthenticated. */
+  role: AIHubRole | null;
+  /** Deployment-wide context from `/auth/me`; null when unauthenticated. */
+  deployment: AIHubAuthContext["deployment"] | null;
+  /**
+   * True when the user must call `changePassword` before any other endpoint
+   * accepts the token. Forces the change-password screen to render under
+   * `AuthGate` (Step 8).
+   */
+  mustChangePassword: boolean;
+  /** Initialization state — `true` until the first `/auth/me` resolves. */
+  hydrating: boolean;
+  /**
+   * Logs in via `client.login`. Stores the token + refreshes auth state.
+   * Returns the underlying `LoginResponse` so callers (e.g. the auto-
+   * rendered `<DataClubAIHubLogin />`) can branch on `mustChangePassword`
+   * + read the just-authenticated `user` without waiting for the next
+   * render. Throws `AIHubRequestError` on failure (the caller decides UX).
+   */
+  login: (username: string, password: string) => Promise<LoginResponse>;
+  /**
+   * Clears the local token; calls `client.logout()` best-effort for the
+   * audit log. The state transitions to `user=null, role=null` so consumers
+   * route back to login.
+   */
+  logout: () => Promise<void>;
+  /**
+   * Calls `client.changePassword`; after success, refreshes `/auth/me` so
+   * `user` + `deployment` reflect the now-clearable `is_initial_password`
+   * flag.
+   */
+  changePassword: (
+    currentPassword: string | null,
+    newPassword: string,
+  ) => Promise<void>;
+
+  /* ── chat state (wired in Step 9) ───────────────────────────────── */
+  /**
+   * Active turn's reducer state, driven by SSE events flowing from
+   * `client.streamChat()`. Re-derived from the persisted event log on
+   * reconnect (§7.5).
+   */
+  state: AIHubState;
+  /** Per-message reasoning effort (§7.4). Defaults to `"medium"`. */
+  effort: AIHubEffort;
+  /** Sets the per-message effort. Survives until changed. */
+  setEffort: (next: AIHubEffort) => void;
+  /**
+   * The ai-hub agents catalog visible to the caller (non-archived only,
+   * with caller-scoped `session_count`). Loaded once after authentication;
+   * refreshed via `refreshAgents()`.
+   */
+  agents: AgentSummary[];
+  /** True while the initial `/agents` request is in flight. */
+  agentsLoading: boolean;
+  /** Refetches `/agents` — e.g. after a new session was created. */
+  refreshAgents: () => Promise<void>;
+  /**
+   * The ai-hub agent the user has opened. `null` when on the agents
+   * picker. The sessions list + chat column read from this.
+   */
+  activeAgentId: string | null;
+  /**
+   * Opens an agent (transitions out of the agents picker) or clears the
+   * selection back to it (`null`).
+   */
+  setActiveAgent: (id: string | null) => void;
+  /**
+   * Sessions for the active agent + current user, ordered by
+   * `updated_at DESC`. Empty when no agent is open.
+   */
+  sessions: Session[];
+  /** True while the active agent's `/sessions` request is in flight. */
+  sessionsLoading: boolean;
+  /** Refetches `/sessions` for the active agent. */
+  refreshSessions: () => Promise<void>;
+  /**
+   * Whether the sessions list includes archived rows. Toggled by the
+   * `archived_filter_toggle` at the bottom of the panel.
+   */
+  includeArchivedSessions: boolean;
+  /** Sets the archived filter. */
+  setIncludeArchivedSessions: (next: boolean) => void;
+  /** The opened session id, or `null` if none. */
+  activeSessionId: string | null;
+  /** Opens a session (loads its message history). */
+  setActiveSession: (id: string | null) => void;
+  /**
+   * Creates a session via `POST /sessions` and selects it. `title` is
+   * required (1..80 chars). Rejected client-side on empty / oversize.
+   */
+  createSession: (title: string) => Promise<Session>;
+  /** Rename / archive a session via `PATCH /sessions/{id}`. */
+  patchSession: (id: string, patch: PatchSessionOptions) => Promise<Session>;
+  /**
+   * Messages for the active session. Loaded from
+   * `GET /sessions/{id}/messages` when `activeSessionId` changes; appended
+   * to during streaming. Empty when no session is active.
+   */
+  messages: AIHubMessage[];
+  /** True while the active session's message history is loading. */
+  messagesLoading: boolean;
+  /**
+   * In-progress assistant text — accumulating `assistant_delta`s for the
+   * currently-streaming turn. `null` when no turn is in flight.
+   */
+  streamingAssistantText: string | null;
+  /**
+   * In-progress reasoning text — accumulating `reasoning_delta`s for
+   * the currently-streaming turn. `null` when no reasoning is in
+   * flight. The live assistant bubble renders this via
+   * `<ReasoningView />`.
+   */
+  streamingReasoning: string | null;
+  /**
+   * In-progress tool calls — built up from `tool_call_started` /
+   * `tool_call_input_delta` / `tool_call_result` events. Empty when no
+   * tool is being invoked.
+   */
+  streamingToolCalls: ReadonlyArray<AIHubToolCallRecord>;
+  /**
+   * Sends `text` against the active session, opening an SSE stream. Throws
+   * if no session is active or the request fails before the stream opens.
+   */
+  sendMessage: (text: string) => Promise<void>;
+  /**
+   * Cancels the in-flight turn via `POST /chat/{turn_id}/cancel`.
+   * The server-side handler calls Letta's authoritative
+   * `agents.messages.cancel` API (which rolls back the in-progress
+   * step from the conversation history while preserving completed
+   * steps) and signals our runner to emit `stream_end{cancelled}`.
+   * The client deliberately DOES NOT abort the SSE iterator — it
+   * waits for the genuine terminal event so the post-stream
+   * canonicalize sees Letta's true final state.
+   */
+  stop: () => Promise<void>;
+  /**
+   * True from the moment the user clicks Stop until the in-flight
+   * turn's `stream_end` lands. UI-only flag; the state machine's
+   * `state.status` stays `running` for the brief "Stopping…" window
+   * because the server is server-authoritative for that. Drives the
+   * button label / disabled state in `<MessageInput>`.
+   */
+  isStoppingTurn: boolean;
+  /**
+   * Text to push into the input on the next render. Set by the post-
+   * stream-end branch when a cancel rolled back the user's message
+   * (single-step cancel: Letta deletes the entire turn including the
+   * user message). `<MessageInput>` reads it, populates the textarea,
+   * and clears via `consumePendingDraft()`.
+   */
+  pendingDraft: string | null;
+  /**
+   * Atomically reads + clears `pendingDraft` — used by `<MessageInput>`
+   * after it copies the value into its local textarea state. Returns
+   * the consumed value (or null if none was pending).
+   */
+  consumePendingDraft: () => string | null;
+  /**
+   * Returned by `sendMessage` when the stream fails before any `stream_end`
+   * fires (network drop, unrecoverable error). Plain message for the
+   * `--failed` modifier — Step 10 enriches with a Retry button.
+   */
+  lastTurnError: string | null;
+
+  /* ── theme state (§7.6) ─────────────────────────────────────────── */
+  /** Resolved theme (`light` | `dark`) — computed per §7.6 precedence. */
+  theme: "light" | "dark";
+  /**
+   * Flips the theme. Optimistic; reverts on server error
+   * (`theme_switcher_disabled` → server returned 409).
+   */
+  setTheme: (next: "light" | "dark") => Promise<void>;
+  /**
+   * Mirror of `deployment.theme_switcher_enabled`. When false, the
+   * `AIHub.ThemeSwitcher` primitive renders nothing.
+   */
+  themeSwitcherEnabled: boolean;
+
+  /* ── feature toggles (§8.4, wired in Step 10) ──────────────────── */
+  /**
+   * The deployment-wide UI feature toggles fetched from public
+   * `GET /feature-toggles` on mount. `null` while the request is in
+   * flight; thereafter the wire blob (possibly empty `{}`).
+   *
+   * Consumers should not branch on individual keys directly — use
+   * `useAffordanceFlags()` to compute the resolved flag stack with
+   * precedence ("server toggle > React prop > built-in default").
+   *
+   * @see SPECIFICATIONS.md §8.4
+   */
+  featureToggles: AIHubFeatureToggles | null;
+  /**
+   * Re-fetches the toggles blob. Called by the super-admin Settings
+   * page (Step 12) after a save so the saving super-admin sees the
+   * effect without a page reload.
+   */
+  refreshFeatureToggles: () => Promise<void>;
+}
+
+/**
+ * The React context object. Default value is `null` — every hook checks
+ * for null and throws a "Wrapped in `<AIHubProvider>`?" error in dev so
+ * misconfiguration surfaces immediately instead of cascading null-deref
+ * failures in components.
+ */
+export const aiHubContext = createContext<AIHubContextValue | null>(null);