@data-club/ai-hub 0.0.1

package/src/context/AIHubProvider.tsx

@@ -0,0 +1,1084 @@
+/**
+ * `<AIHubProvider>` — root of every ai-hub React tree.
+ *
+ * Owns:
+ *
+ * - The shared `AIHubClient` instance (consumers call SDK methods through
+ *   `useAIHub().client`).
+ * - The JWT lifecycle: read from `tokenStorage` on mount, attempt `/auth/me`
+ *   to hydrate `user` + `deployment`; clear on logout; clear and route
+ *   back to login on any 401 from the server (§6.7 — no silent refresh).
+ * - The resolved theme: client-side precedence per §7.6, FOUC-avoided via
+ *   a cached value in `localStorage` applied on first paint.
+ * - Per-message reasoning effort state.
+ * - **Step 9 — chat state:** agents catalog, active agent, sessions list,
+ *   active session, message history, in-flight turn state (driven by the
+ *   §10 reducer over SSE events from `client.streamChat`), `sendMessage`,
+ *   `stop`. The state-aware affordance gates (TPM banner, theme switcher,
+ *   tool-call card, reasoning view) layer on top in Step 10.
+ *
+ * @see SPECIFICATIONS.md §7.2 — provider props
+ * @see SPECIFICATIONS.md §7.5 — state on the client
+ * @see SPECIFICATIONS.md §7.6 — theme resolution
+ * @see SPECIFICATIONS.md §6.7 — auth model
+ */
+
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+
+import {
+  AIHubClient,
+  AIHubRequestError,
+  type AgentSummary,
+  type PatchSessionOptions,
+} from "../client/AIHubClient.js";
+import type { AIHubEffort } from "../client/AIHubClient.js";
+import type { TokenStorageMode, TokenStorage } from "../client/tokenStorage.js";
+import {
+  initialAIHubState,
+  reduceAIHubState,
+} from "../state/stateReducer.js";
+import type {
+  AIHubAuthContext,
+  AIHubDeployment,
+  AIHubError,
+  AIHubFeatureToggles,
+  AIHubMessage,
+  AIHubRole,
+  AIHubState,
+  AIHubToolCallRecord,
+  AIHubUser,
+  Session,
+} from "../types.js";
+
+import { aiHubContext, type AIHubContextValue } from "./AIHubContext.js";
+import {
+  readCachedTheme,
+  resolveTheme,
+  writeCachedTheme,
+  type ResolvedTheme,
+} from "./theme.js";
+
+/**
+ * When the post-stream canonicalize refetches messages from the server,
+ * we merge the optimistic-streaming `reasoning` + `tool_calls` we
+ * captured during the turn into the canonical assistant message that
+ * carries the same id. This handles two cases:
+ *
+ * 1. **Race window.** Letta's `tool_return_message` commit can lag the
+ *    SSE `tool_call_result` event by a few ms; if our refetch hits in
+ *    that window the projector sees the tool_call but no return, so
+ *    the canonical row's `tool_calls` is missing or stale.
+ * 2. **Older server build.** Operators upgrading mid-session may still
+ *    be running a server without the §10.x aggregating projector. The
+ *    canonical row carries no `reasoning` / `tool_calls` at all.
+ *
+ * Either way, the optimistic data we already showed during streaming
+ * is correct; merging it onto the canonical row keeps it visible.
+ *
+ * @param canonical - the freshly-refetched list from
+ *   `client.getSessionMessages`.
+ * @param optimistic - the message list we held in state before the
+ *   refetch (post-streaming accumulation).
+ * @returns a new list, same identity / shape as `canonical`, with the
+ *   missing affordance fields filled in from `optimistic` when present.
+ */
+function mergeOptimisticAffordances(
+  canonical: ReadonlyArray<AIHubMessage>,
+  optimistic: ReadonlyArray<AIHubMessage>,
+): AIHubMessage[] {
+  const optimisticById = new Map<string, AIHubMessage>();
+  for (const m of optimistic) {
+    if (m.role === "assistant" && (m.reasoning || m.tool_calls?.length || m.usage)) {
+      optimisticById.set(m.id, m);
+    }
+  }
+  return canonical.map((c) => {
+    if (c.role !== "assistant") return c;
+    const o = optimisticById.get(c.id);
+    if (!o) return c;
+    const next: AIHubMessage = { ...c };
+    if (!next.reasoning && o.reasoning) {
+      next.reasoning = o.reasoning;
+    }
+    if ((!next.tool_calls || next.tool_calls.length === 0) && o.tool_calls?.length) {
+      next.tool_calls = o.tool_calls;
+    }
+    // Usage rides through too — if the canonical refetch happens
+    // before the server stamped `message_usage` (small race window),
+    // the live `usage` event we already handled keeps the badge
+    // rendered until the next refresh confirms it.
+    if (!next.usage && o.usage) {
+      next.usage = o.usage;
+    }
+    return next;
+  });
+}
+
+/**
+ * Public props on `<AIHubProvider>`.
+ *
+ * `defaultTheme` is overridden by the deployment's `theme_default` once
+ * `/auth/me` resolves (server config wins — same rule as the §8.4 toggles).
+ */
+export interface AIHubProviderProps {
+  /**
+   * Base URL the ai-hub-server routes are mounted at. Typically
+   * `/api/ai-hub` in a per-customer wrapper.
+   */
+  baseUrl: string;
+  /** Custom `fetch`; defaults to `globalThis.fetch`. */
+  fetch?: typeof fetch;
+  /** Token storage mode or custom adapter. Defaults to `"localStorage"`. */
+  tokenStorage?: TokenStorageMode | TokenStorage;
+  /**
+   * Pre-built `AIHubClient`. When set, `baseUrl` / `fetch` / `tokenStorage`
+   * are ignored. Useful for tests that need to stub the SDK without going
+   * through the provider's lifecycle.
+   */
+  client?: AIHubClient;
+  /**
+   * Notification hook for top-level errors. Fired for transport and
+   * surfaced stream errors; not fired for normal stream `done` /
+   * `cancelled`. The provider does not render its own error UI.
+   */
+  onError?: (err: AIHubError) => void;
+  /**
+   * Fallback theme used when no `/auth/me` has resolved yet and the cache
+   * is empty. Server config (`theme_default`) wins after hydration.
+   */
+  defaultTheme?: ResolvedTheme;
+  /** The tree under the provider. */
+  children: ReactNode;
+}
+
+/**
+ * The provider component. Single instance per ai-hub mount — multiple
+ * mounts on the same page each manage their own auth state (this is the
+ * shape `defineWebComponent` ships).
+ *
+ * @param props - the provider props.
+ */
+export function AIHubProvider(props: AIHubProviderProps): ReactNode {
+  const {
+    baseUrl,
+    children,
+    client: clientProp,
+    defaultTheme = "light",
+    fetch: fetchProp,
+    onError,
+    tokenStorage = "localStorage",
+  } = props;
+
+  // ── client ───────────────────────────────────────────────────────────
+  const unauthorizedRef = useRef<(() => void) | null>(null);
+  const client = useMemo(() => {
+    if (clientProp) return clientProp;
+    return new AIHubClient({
+      baseUrl,
+      ...(fetchProp ? { fetch: fetchProp } : {}),
+      tokenStorage,
+      onUnauthorized: () => unauthorizedRef.current?.(),
+    });
+  }, [baseUrl, clientProp, fetchProp, tokenStorage]);
+
+  // ── auth state ──────────────────────────────────────────────────────
+  const [user, setUser] = useState<AIHubUser | null>(null);
+  const [deployment, setDeployment] = useState<AIHubDeployment | null>(null);
+  // Server feature toggles fetched from public GET /feature-toggles on mount
+  // (§8.4). `null` while the request is in flight; thereafter `{}` (empty
+  // blob — no overrides) or the typed blob. The provider does not block
+  // rendering on this — the §8.4 precedence ("server toggle > React prop >
+  // built-in default") falls through to the prop default until the fetch
+  // resolves, which keeps the FOUC story honest.
+  const [featureToggles, setFeatureToggles] =
+    useState<AIHubFeatureToggles | null>(null);
+  const [mustChangePassword, setMustChangePassword] = useState(false);
+  const [hydrating, setHydrating] = useState(true);
+
+  // ── effort (§7.4) + theme (§7.6) ────────────────────────────────────
+  const [effort, setEffort] = useState<AIHubEffort>("medium");
+  const [theme, setThemeState] = useState<ResolvedTheme>(() => {
+    return readCachedTheme() ?? defaultTheme;
+  });
+
+  // ── chat state (Step 9) ─────────────────────────────────────────────
+  const [agents, setAgents] = useState<AgentSummary[]>([]);
+  const [agentsLoading, setAgentsLoading] = useState(false);
+  const [activeAgentId, setActiveAgentIdState] = useState<string | null>(null);
+  const [sessions, setSessions] = useState<Session[]>([]);
+  const [sessionsLoading, setSessionsLoading] = useState(false);
+  const [includeArchivedSessions, setIncludeArchivedSessions] = useState(false);
+  const [activeSessionId, setActiveSessionIdState] = useState<string | null>(
+    null,
+  );
+  const [messages, setMessages] = useState<AIHubMessage[]>([]);
+  const [messagesLoading, setMessagesLoading] = useState(false);
+  const [streamState, setStreamState] = useState<AIHubState>(() =>
+    initialAIHubState(),
+  );
+  const [streamingAssistantText, setStreamingAssistantText] = useState<
+    string | null
+  >(null);
+  // Reasoning text accumulating during the current turn, when the user
+  // sent a non-`none` effort and the agent emitted `reasoning_delta`
+  // events. Cleared on `stream_end` (the canonicalized assistant
+  // message will carry the final reasoning).
+  const [streamingReasoning, setStreamingReasoning] = useState<string | null>(
+    null,
+  );
+  // Tool calls accumulating during the current turn. Map keyed by
+  // `tool_call_id`; one entry per call. Cleared on `stream_end`.
+  const [streamingToolCalls, setStreamingToolCalls] = useState<
+    ReadonlyArray<AIHubToolCallRecord>
+  >([]);
+  const [lastTurnError, setLastTurnError] = useState<string | null>(null);
+  // True from `stop()` invocation until the matching `stream_end` lands.
+  // The state machine's `state.status` stays `running` for the brief
+  // server-side cancel window — `isStoppingTurn` is the client-only flag
+  // that drives the "Stopping…" button label and keeps the input
+  // disabled until the genuine terminal event arrives.
+  const [isStoppingTurn, setIsStoppingTurn] = useState(false);
+  // Text to push into `<MessageInput>` on the next render. Populated by
+  // the post-stream-end branch when a cancel rolled back the user's
+  // message (single-step cancel: Letta deletes the entire turn from
+  // history — the user's typed text would be lost without this).
+  const [pendingDraft, setPendingDraft] = useState<string | null>(null);
+
+  // The turn currently being streamed: AbortController + cached turn id
+  // (read off `stream_start`) so `stop()` can fire the explicit cancel
+  // endpoint *and* abort the SSE iterator at the same time. We carry both
+  // in a ref so updates don't trigger re-renders mid-stream.
+  const streamRef = useRef<{
+    controller: AbortController;
+    turnId: string | null;
+  } | null>(null);
+
+  // Mirror of `activeSessionId` for use inside long-running async
+  // callbacks (the streamChat loop closes over `sessionId` from the
+  // moment `sendMessage` was called; we use this ref to detect whether
+  // the user has switched sessions in the meantime before applying the
+  // post-stream canonicalize).
+  const activeSessionIdRef = useRef<string | null>(null);
+
+  // Mirror of `messages` used by `sendMessage` to snapshot the message
+  // count BEFORE the optimistic user-bubble append. After stream_end
+  // the post-stream branch compares the canonical message count to this
+  // baseline: if `canonical.length <= baseline` the cancelled turn was
+  // rolled back entirely (single-step cancel — Letta deletes the user
+  // message too), and the user's typed text is pushed into `pendingDraft`
+  // so `<MessageInput>` can prefill it. State refs can lag a render
+  // behind the value but `sendMessage` reads it synchronously at the top.
+  const messagesRef = useRef<AIHubMessage[]>([]);
+  messagesRef.current = messages;
+
+  /**
+   * Resets every chat-state slot. Called on logout and on
+   * unauthenticated → authenticated transitions so a previous user's
+   * artifacts don't leak into the next session.
+   */
+  const resetChatState = useCallback((): void => {
+    streamRef.current?.controller.abort();
+    streamRef.current = null;
+    setAgents([]);
+    setActiveAgentIdState(null);
+    setSessions([]);
+    setIncludeArchivedSessions(false);
+    setActiveSessionIdState(null);
+    setMessages([]);
+    setStreamState(initialAIHubState());
+    setStreamingAssistantText(null);
+    setLastTurnError(null);
+  }, []);
+
+  unauthorizedRef.current = () => {
+    setUser(null);
+    setDeployment(null);
+    setMustChangePassword(false);
+    resetChatState();
+  };
+
+  // Keep the ref in sync so the post-stream canonicalize sees the
+  // current value (it closes over a stale `activeSessionId` otherwise).
+  activeSessionIdRef.current = activeSessionId;
+
+  // ── hydrate on mount ────────────────────────────────────────────────
+  useEffect(() => {
+    let cancelled = false;
+    const token = client.getToken();
+    if (!token) {
+      setHydrating(false);
+      return;
+    }
+    void (async () => {
+      try {
+        const context: AIHubAuthContext = await client.me();
+        if (cancelled) return;
+        setUser(context.user);
+        setDeployment(context.deployment);
+        setMustChangePassword(false);
+      } catch (err) {
+        if (cancelled) return;
+        if (err instanceof AIHubRequestError && err.code !== "unauthorized") {
+          onError?.({
+            code: err.code,
+            message: err.message,
+            ...(err.status !== undefined ? { status: err.status } : {}),
+            ...(err.request_id !== undefined ? { request_id: err.request_id } : {}),
+          });
+        }
+      } finally {
+        if (!cancelled) setHydrating(false);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [client, onError]);
+
+  // ── load deployment-wide feature toggles on mount ───────────────────
+  // The endpoint is public (no auth) so we fetch as soon as the provider
+  // mounts — even before login lands — so the chat shell can apply the
+  // §8.4 precedence rules on first paint. Errors are logged via
+  // `onError` but never block rendering (we fall through to React-prop
+  // defaults).
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      try {
+        const toggles = await client.getFeatureToggles();
+        if (cancelled) return;
+        setFeatureToggles(toggles);
+      } catch (err) {
+        if (cancelled) return;
+        if (err instanceof AIHubRequestError) {
+          onError?.({
+            code: err.code,
+            message: err.message,
+            ...(err.status !== undefined ? { status: err.status } : {}),
+          });
+        }
+        // Fall through with an empty blob so every prop default applies.
+        setFeatureToggles({});
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [client, onError]);
+
+  // ── reconcile resolved theme whenever inputs change ────────────────
+  useEffect(() => {
+    if (!deployment) return;
+    const resolved = resolveTheme(user, deployment, defaultTheme);
+    setThemeState(resolved);
+    writeCachedTheme(resolved);
+  }, [user, deployment, defaultTheme]);
+
+  // ── load /agents whenever an authenticated user becomes available ───
+  const refreshAgents = useCallback(async (): Promise<void> => {
+    setAgentsLoading(true);
+    try {
+      const list = await client.listAgents();
+      setAgents(list);
+    } catch (err) {
+      if (err instanceof AIHubRequestError) {
+        onError?.({
+          code: err.code,
+          message: err.message,
+          ...(err.status !== undefined ? { status: err.status } : {}),
+        });
+      }
+      setAgents([]);
+    } finally {
+      setAgentsLoading(false);
+    }
+  }, [client, onError]);
+
+  useEffect(() => {
+    if (!user || mustChangePassword) return;
+    void refreshAgents();
+  }, [user, mustChangePassword, refreshAgents]);
+
+  // ── load /sessions whenever an agent is opened ──────────────────────
+  const refreshSessions = useCallback(async (): Promise<void> => {
+    if (!activeAgentId) {
+      setSessions([]);
+      return;
+    }
+    setSessionsLoading(true);
+    try {
+      const list = await client.listSessions({
+        agentId: activeAgentId,
+        includeArchived: includeArchivedSessions,
+      });
+      setSessions(list);
+    } catch (err) {
+      if (err instanceof AIHubRequestError) {
+        onError?.({
+          code: err.code,
+          message: err.message,
+          ...(err.status !== undefined ? { status: err.status } : {}),
+        });
+      }
+      setSessions([]);
+    } finally {
+      setSessionsLoading(false);
+    }
+  }, [activeAgentId, client, includeArchivedSessions, onError]);
+
+  useEffect(() => {
+    if (!activeAgentId) {
+      setSessions([]);
+      return;
+    }
+    void refreshSessions();
+  }, [activeAgentId, includeArchivedSessions, refreshSessions]);
+
+  // ── load /sessions/{id}/messages whenever a session is opened ──────
+  //
+  // Note: `setActiveSession` / `createSession` already clear `messages`
+  // and set `messagesLoading=true` synchronously in the same batch as
+  // the id flip, so the previous session's bubbles never flash during
+  // this fetch. We don't repeat those resets here — only the fetch +
+  // the loading-flag flip on completion are this effect's job.
+  useEffect(() => {
+    if (!activeSessionId) {
+      setMessages([]);
+      setMessagesLoading(false);
+      return;
+    }
+    let cancelled = false;
+    setMessagesLoading(true);
+    void (async () => {
+      try {
+        const list = await client.getSessionMessages(activeSessionId);
+        if (cancelled) return;
+        setMessages(list);
+      } catch (err) {
+        if (cancelled) return;
+        if (err instanceof AIHubRequestError) {
+          onError?.({
+            code: err.code,
+            message: err.message,
+            ...(err.status !== undefined ? { status: err.status } : {}),
+          });
+        }
+        setMessages([]);
+      } finally {
+        if (!cancelled) setMessagesLoading(false);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [activeSessionId, client, onError]);
+
+  // ── action callbacks (auth + theme) ────────────────────────────────
+  const login: AIHubContextValue["login"] = async (username, password) => {
+    const result = await client.login(username, password);
+    setMustChangePassword(result.mustChangePassword);
+    setUser(result.user);
+    setDeployment(result.deployment ?? null);
+    return result;
+  };
+
+  const logout: AIHubContextValue["logout"] = async () => {
+    try {
+      await client.logout();
+    } finally {
+      setUser(null);
+      setDeployment(null);
+      setMustChangePassword(false);
+      resetChatState();
+    }
+  };
+
+  const changePassword: AIHubContextValue["changePassword"] = async (
+    currentPassword,
+    newPassword,
+  ) => {
+    await client.changePassword(currentPassword, newPassword);
+    const context = await client.me();
+    setUser(context.user);
+    setDeployment(context.deployment);
+    setMustChangePassword(false);
+  };
+
+  const setTheme: AIHubContextValue["setTheme"] = async (next) => {
+    const previous = theme;
+    setThemeState(next);
+    writeCachedTheme(next);
+    try {
+      const context = await client.updatePreferences({ theme: next });
+      setUser(context.user);
+      setDeployment(context.deployment);
+    } catch (err) {
+      setThemeState(previous);
+      writeCachedTheme(previous);
+      throw err;
+    }
+  };
+
+  // ── chat actions ───────────────────────────────────────────────────
+  const setActiveAgent: AIHubContextValue["setActiveAgent"] = (id) => {
+    streamRef.current?.controller.abort();
+    streamRef.current = null;
+    setActiveAgentIdState(id);
+    setActiveSessionIdState(null);
+    setMessages([]);
+    setStreamingAssistantText(null);
+    setLastTurnError(null);
+    setIsStoppingTurn(false);
+    setPendingDraft(null);
+    setStreamState(initialAIHubState());
+  };
+
+  const setActiveSession: AIHubContextValue["setActiveSession"] = (id) => {
+    if (id === activeSessionId) return;
+    streamRef.current?.controller.abort();
+    streamRef.current = null;
+    setActiveSessionIdState(id);
+    // Clear messages synchronously in the same setState batch as the id
+    // change — otherwise the previous session's bubbles flash for the
+    // duration of the next session's `/sessions/:id/messages` fetch.
+    setMessages([]);
+    setMessagesLoading(id !== null);
+    setStreamingAssistantText(null);
+    setLastTurnError(null);
+    setIsStoppingTurn(false);
+    setPendingDraft(null);
+    setStreamState(initialAIHubState());
+  };
+
+  const createSession: AIHubContextValue["createSession"] = async (title) => {
+    if (!activeAgentId) {
+      throw new AIHubRequestError(
+        "validation",
+        "Open an agent before creating a session.",
+      );
+    }
+    const session = await client.createSession({
+      agentId: activeAgentId,
+      title,
+    });
+    // Prepend so the new row appears at the top of the list (server orders
+    // by updated_at DESC).
+    setSessions((prev) => [session, ...prev.filter((s) => s.id !== session.id)]);
+    // Same synchronous-clear story as `setActiveSession` — otherwise the
+    // previous session's bubbles flash during the brand-new session's
+    // (empty) history fetch.
+    streamRef.current?.controller.abort();
+    streamRef.current = null;
+    setActiveSessionIdState(session.id);
+    setMessages([]);
+    setMessagesLoading(true);
+    setStreamingAssistantText(null);
+    setLastTurnError(null);
+    setStreamState(initialAIHubState());
+    // Refresh the agents catalog so the picker's per-caller session_count
+    // reflects the new row on the next visit. Best-effort — failure isn't
+    // fatal.
+    void refreshAgents();
+    return session;
+  };
+
+  const patchSession: AIHubContextValue["patchSession"] = async (id, patch) => {
+    const updated = await client.patchSession(id, patch);
+    setSessions((prev) => {
+      const next = prev.map((s) => (s.id === id ? updated : s));
+      // If the row was archived and the filter is off, drop it from view.
+      if (
+        patch.isArchived === true &&
+        !includeArchivedSessions
+      ) {
+        return next.filter((s) => !s.is_archived);
+      }
+      return next;
+    });
+    if (patch.isArchived === true && id === activeSessionId) {
+      setActiveSessionIdState(null);
+    }
+    return updated;
+  };
+
+  const sendMessage: AIHubContextValue["sendMessage"] = async (text) => {
+    const sessionId = activeSessionId;
+    if (!sessionId) {
+      throw new AIHubRequestError(
+        "validation",
+        "Open a session before sending a message.",
+      );
+    }
+    if (typeof text !== "string" || text.length === 0) {
+      throw new AIHubRequestError("validation", "Cannot send an empty message.");
+    }
+    // Optimistically append the user's message so the bubble shows up
+    // immediately. The server doesn't echo user messages on the stream —
+    // they're already in the conversation by the time we ask Letta to
+    // produce a reply. Stream-end refetches `getSessionMessages` and
+    // replaces the array with Letta's canonical history, so this
+    // pending-* id is short-lived; we dedupe defensively anyway.
+    const optimisticUser: AIHubMessage = {
+      id: `pending-${Date.now()}`,
+      role: "user",
+      content: text,
+      created_at: new Date().toISOString(),
+    };
+    setMessages((prev) => {
+      if (prev.some((m) => m.id === optimisticUser.id)) return prev;
+      return [...prev, optimisticUser];
+    });
+    setStreamingAssistantText("");
+    setLastTurnError(null);
+
+    const controller = new AbortController();
+    streamRef.current = { controller, turnId: null };
+
+    let accumulated = "";
+    // Streaming reasoning + tool-call accumulators — kept locally
+    // (closure-scoped) so we can flush them into the canonicalized
+    // message at end-of-stream OR clear them on cancel/error. Both
+    // mirror to React state so the live bubble renders while the turn
+    // runs.
+    let accumulatedReasoning = "";
+    const toolCallsByCallId = new Map<
+      string,
+      {
+        tool_name: string;
+        input: string;
+        status: "success" | "error";
+        output: string | null;
+        error: string | null;
+      }
+    >();
+    function snapshotToolCalls(): ReadonlyArray<AIHubToolCallRecord> {
+      const out: AIHubToolCallRecord[] = [];
+      for (const [callId, info] of toolCallsByCallId.entries()) {
+        out.push({
+          tool_call_id: callId,
+          tool_name: info.tool_name,
+          input: info.input,
+          status: info.status,
+          output: info.output,
+          error: info.error,
+        });
+      }
+      return out;
+    }
+    setStreamingReasoning(null);
+    setStreamingToolCalls([]);
+    // Track outcome signals collected during the stream. Used after the
+    // loop to decide whether to:
+    //   - canonicalize against Letta's history (replace optimistic
+    //     state with the real one)
+    //   - leave the optimistic state in place + surface an error
+    //   - leave the optimistic state in place + stay silent (user
+    //     cancelled — they didn't ask for an error)
+    let sawAssistantOutput = false;
+    let sawError = false;
+    let endReason: "done" | "cancelled" | "error" | null = null;
+    try {
+      const iter = client.streamChat(
+        { sessionId, userMessage: text, effort },
+        { signal: controller.signal },
+      );
+      for await (const event of iter) {
+        // Drive the §10 reducer (turn state).
+        setStreamState((prev) => reduceAIHubState(prev, event));
+        if (event.event === "stream_start") {
+          if (streamRef.current) {
+            streamRef.current.turnId = event.data.turn_id;
+          }
+        } else if (event.event === "assistant_delta") {
+          accumulated += event.data.delta;
+          setStreamingAssistantText(accumulated);
+          sawAssistantOutput = true;
+        } else if (event.event === "reasoning_delta") {
+          accumulatedReasoning += event.data.delta;
+          setStreamingReasoning(accumulatedReasoning);
+        } else if (event.event === "tool_call_started") {
+          const callId = event.data.tool_call_id;
+          if (!toolCallsByCallId.has(callId)) {
+            toolCallsByCallId.set(callId, {
+              tool_name: event.data.tool_name,
+              input: "",
+              status: "success",
+              output: null,
+              error: null,
+            });
+            setStreamingToolCalls(snapshotToolCalls());
+          }
+        } else if (event.event === "tool_call_input_delta") {
+          const info = toolCallsByCallId.get(event.data.tool_call_id);
+          if (info) {
+            info.input += event.data.partial_json;
+            setStreamingToolCalls(snapshotToolCalls());
+          }
+        } else if (event.event === "tool_call_dispatched") {
+          // Phase transition is handled by the reducer; we don't need to
+          // touch the accumulator (the input is already captured via
+          // tool_call_input_delta — `event.data.input` may be empty per
+          // the server's translator).
+        } else if (event.event === "tool_call_result") {
+          const info = toolCallsByCallId.get(event.data.tool_call_id);
+          if (info) {
+            if ("output" in event.data) {
+              info.status = "success";
+              info.output =
+                typeof event.data.output === "string"
+                  ? event.data.output
+                  : JSON.stringify(event.data.output, null, 2);
+              info.error = null;
+            } else if ("error" in event.data) {
+              info.status = "error";
+              info.error =
+                typeof event.data.error === "string"
+                  ? event.data.error
+                  : JSON.stringify(event.data.error, null, 2);
+              info.output = null;
+            }
+            setStreamingToolCalls(snapshotToolCalls());
+          }
+        } else if (event.event === "assistant_message_complete") {
+          // Dedupe — if `assistant_message_complete` fires twice for the
+          // same id (server quirk, hot-reload, SSE reconnect), append
+          // only the first occurrence. Enrich the final message with
+          // the streaming-accumulated reasoning + tool calls so the
+          // historical bubble carries the same data the live bubble
+          // showed (the server's `/sessions/:id/messages` projector
+          // also returns these fields, but we don't wait for a refetch).
+          const finalMsg: AIHubMessage = { ...event.data.message };
+          if (accumulatedReasoning.length > 0 && !finalMsg.reasoning) {
+            finalMsg.reasoning = accumulatedReasoning;
+          }
+          const calls = snapshotToolCalls();
+          if (calls.length > 0 && !finalMsg.tool_calls) {
+            finalMsg.tool_calls = [...calls];
+          }
+          setMessages((prev) =>
+            prev.some((m) => m.id === finalMsg.id) ? prev : [...prev, finalMsg],
+          );
+          accumulated = "";
+          accumulatedReasoning = "";
+          toolCallsByCallId.clear();
+          setStreamingAssistantText(null);
+          setStreamingReasoning(null);
+          setStreamingToolCalls([]);
+          sawAssistantOutput = true;
+        } else if (event.event === "usage") {
+          // Live usage stamp — the runner emits this right before
+          // `stream_end{done}` carrying the cache-hit/write counts for
+          // the turn. We attach it to the matching assistant bubble so
+          // `<CacheBadge />` appears immediately (without waiting for
+          // the post-stream `/messages` refetch). The refetch path
+          // also stamps the same `usage` from the persisted
+          // `message_usage` row, so refresh + history retrieval show
+          // the badge too.
+          const targetId = event.data.letta_message_id;
+          if (typeof targetId === "string") {
+            const usage = {
+              input: event.data.input ?? null,
+              output: event.data.output ?? null,
+              cache_read: event.data.cache_read ?? null,
+              cache_write: event.data.cache_write ?? null,
+              reasoning: event.data.reasoning ?? null,
+              context: event.data.context ?? null,
+              total: event.data.total ?? null,
+            };
+            setMessages((prev) =>
+              prev.map((m) => (m.id === targetId ? { ...m, usage } : m)),
+            );
+          }
+        } else if (event.event === "error") {
+          setLastTurnError(event.data.message);
+          sawError = true;
+        } else if (event.event === "stream_end") {
+          // Terminal — record the reason and clear the streaming
+          // accumulator. The final assistant message arrived via
+          // `assistant_message_complete` in a healthy stream; in
+          // `cancelled` / `error` outcomes the accumulator may carry
+          // partial text the UI still wants to show, so we flush it
+          // into a synthetic message before clearing.
+          endReason = event.data.reason;
+          if (accumulated.length > 0) {
+            const partialId = `partial-${streamRef.current?.turnId ?? Date.now()}`;
+            const partialMsg: AIHubMessage = {
+              id: partialId,
+              role: "assistant",
+              content: accumulated,
+              created_at: new Date().toISOString(),
+            };
+            if (accumulatedReasoning.length > 0) {
+              partialMsg.reasoning = accumulatedReasoning;
+            }
+            const calls = snapshotToolCalls();
+            if (calls.length > 0) {
+              partialMsg.tool_calls = [...calls];
+            }
+            setMessages((prev) => [...prev, partialMsg]);
+            accumulated = "";
+            sawAssistantOutput = true;
+          }
+          accumulatedReasoning = "";
+          toolCallsByCallId.clear();
+          setStreamingAssistantText(null);
+          setStreamingReasoning(null);
+          setStreamingToolCalls([]);
+        }
+      }
+    } catch (err) {
+      // Aborts (from `stop()` or a session switch) are not errors. We
+      // record the outcome explicitly so the post-stream logic below
+      // can canonicalize Letta's history (the server may have persisted
+      // a partial response before the cancel landed). Anything else is
+      // a genuine transport failure.
+      if (controller.signal.aborted) {
+        endReason = "cancelled";
+        setStreamingAssistantText(null);
+        setStreamingReasoning(null);
+        setStreamingToolCalls([]);
+        accumulatedReasoning = "";
+        toolCallsByCallId.clear();
+        // Transition state out of `running` so the input re-enables
+        // immediately. The reducer normally drives this off the server's
+        // `(status, phase)` snapshot on `stream_end`, but the abort
+        // severed the connection before that event arrived.
+        setStreamState((s) => ({ ...s, status: "cancelled", phase: null }));
+      } else {
+        const msg =
+          err instanceof Error ? err.message : "Stream failed.";
+        setLastTurnError(msg);
+        setStreamingAssistantText(null);
+        setStreamingReasoning(null);
+        setStreamingToolCalls([]);
+        accumulatedReasoning = "";
+        toolCallsByCallId.clear();
+        if (err instanceof AIHubRequestError) {
+          onError?.({
+            code: err.code,
+            message: err.message,
+            ...(err.status !== undefined ? { status: err.status } : {}),
+          });
+        }
+      }
+    } finally {
+      if (streamRef.current?.controller === controller) {
+        streamRef.current = null;
+      }
+    }
+
+    // Post-stream housekeeping — three branches, gated on the outcome
+    // recorded during the loop / catch:
+    //
+    // - `cancelled`  — user pressed Stop (or switched sessions). Don't
+    //                  show an error; canonicalize so any partial
+    //                  response the agent finished generating before
+    //                  the cancel landed shows up properly.
+    // - `error`      — server emitted an explicit error event during
+    //                  the turn. `lastTurnError` already carries the
+    //                  specific message; don't canonicalize (the
+    //                  server's history may be empty / partial and
+    //                  overwriting `messages` would erase the
+    //                  optimistic user bubble).
+    // - `done` / unknown — happy path OR "stream ended cleanly without
+    //                  producing assistant output" (e.g. an upstream
+    //                  agent-configuration problem returning an empty
+    //                  completion). Canonicalize on real output;
+    //                  otherwise surface a generic user-facing error
+    //                  pointing at the administrator.
+    if (endReason === "cancelled") {
+      try {
+        const canonical = await client.getSessionMessages(sessionId);
+        if (activeSessionIdRef.current === sessionId) {
+          const merged = mergeOptimisticAffordances(
+            canonical,
+            messagesRef.current,
+          );
+          setMessages(merged);
+          // Rollback detection: when Letta's authoritative cancel
+          // rolled back the in-progress step AND there were no
+          // previously-committed steps, the user's message disappears
+          // from history entirely (single-step cancel — empirically
+          // verified). Test by content (the rolled-back optimistic
+          // message had `content === text`; if no canonical user
+          // message carries that content, it was rolled back). The
+          // earlier `length <= baseline` check was right in the happy
+          // case but missed scenarios where the session already had
+          // sibling rows (e.g. memory_metadata) whose count made the
+          // comparison wobbly.
+          const trimmed = text.trim();
+          const userMessagePreserved = canonical.some(
+            (m) => m.role === "user" && m.content.trim() === trimmed,
+          );
+          if (!userMessagePreserved) {
+            setPendingDraft(text);
+          }
+        }
+      } catch {
+        // Canonical refetch failed (network blip while the user was
+        // cancelling). Restore the typed text so they can retry; we'd
+        // rather over-restore than lose the input.
+        setPendingDraft(text);
+      }
+      setIsStoppingTurn(false);
+    } else if (sawError) {
+      /* `lastTurnError` already set in the loop — do nothing */
+      setIsStoppingTurn(false);
+    } else if (!sawAssistantOutput) {
+      // The stream finished but produced nothing renderable. Surface a
+      // user-facing error — kept generic on purpose (no upstream
+      // implementation names; users are pointed at the operator).
+      setLastTurnError(
+        "The agent didn't produce a response. Contact your administrator if this persists.",
+      );
+      setIsStoppingTurn(false);
+    } else if (!controller.signal.aborted) {
+      try {
+        const canonical = await client.getSessionMessages(sessionId);
+        if (activeSessionIdRef.current === sessionId) {
+          // Merge optimistic reasoning + tool_calls into the canonical
+          // list: the streaming accumulators captured rich data the
+          // server's projector might not yet (Letta's cross-row
+          // aggregation has a small window where the
+          // tool_return_message hasn't been committed yet, or the
+          // operator is running an older server build without the
+          // §10.x projector). Preserves the affordances either way.
+          const merged = mergeOptimisticAffordances(
+            canonical,
+            messagesRef.current,
+          );
+          setMessages(merged);
+        }
+      } catch {
+        /* keep optimistic state; user can refresh */
+      }
+      setIsStoppingTurn(false);
+    } else {
+      setIsStoppingTurn(false);
+    }
+  };
+
+  const stop: AIHubContextValue["stop"] = async () => {
+    const active = streamRef.current;
+    if (!active) return;
+    const { turnId } = active;
+    // The right design here is the OPPOSITE of "abort the iterator":
+    // we want the server's authoritative cancel (Letta's
+    // `agents.messages.cancel`, fired by `/chat/:id/cancel`) to wind
+    // the run down server-side, then deliver `stream_end{cancelled}`
+    // naturally on the SSE stream. The post-stream-end branch in
+    // `sendMessage` then canonicalizes against Letta's history — which
+    // correctly shows the rolled-back state (in-progress step gone;
+    // completed steps preserved).
+    //
+    // Aborting the iterator here would race the cancel: the connection
+    // closes before the server can deliver `stream_end{cancelled}`,
+    // and we'd lose the chance to capture the canonical end-state
+    // through the established post-stream path.
+    //
+    // The UX gap (network round-trip to fire the cancel + Letta
+    // processing time, typically ~300ms) is covered by
+    // `isStoppingTurn` — `<MessageInput>` shows "Stopping…" and keeps
+    // the input disabled. We don't need a hard-abort timeout for the
+    // common case; even a slow Letta cancel resolves in low seconds.
+    // If the cancel POST itself fails the runner's local AbortSignal
+    // (fired server-side as fallback) still produces `stream_end`.
+    setIsStoppingTurn(true);
+    if (turnId) {
+      try {
+        await client.cancelTurn(turnId);
+      } catch {
+        // Ignored — the server's `/cancel` handler also fires the
+        // local registry abort, so the runner will emit `stream_end`
+        // even if our POST hit a transient failure.
+      }
+    }
+  };
+
+  const themeSwitcherEnabled = deployment?.theme_switcher_enabled ?? true;
+  const role: AIHubRole | null = user?.role ?? null;
+
+  // Refresh the feature toggles on demand — used after the super-admin
+  // settings page saves a toggle change (Step 12), so the calling
+  // super_admin sees the effect without a page reload.
+  const refreshFeatureToggles = useCallback(async (): Promise<void> => {
+    try {
+      const toggles = await client.getFeatureToggles();
+      setFeatureToggles(toggles);
+    } catch (err) {
+      if (err instanceof AIHubRequestError) {
+        onError?.({
+          code: err.code,
+          message: err.message,
+          ...(err.status !== undefined ? { status: err.status } : {}),
+        });
+      }
+    }
+  }, [client, onError]);
+
+  const value: AIHubContextValue = {
+    client,
+    user,
+    role,
+    deployment,
+    mustChangePassword,
+    hydrating,
+    login,
+    logout,
+    changePassword,
+    state: streamState,
+    effort,
+    setEffort,
+    theme,
+    setTheme,
+    themeSwitcherEnabled,
+    agents,
+    agentsLoading,
+    refreshAgents,
+    activeAgentId,
+    setActiveAgent,
+    sessions,
+    sessionsLoading,
+    refreshSessions,
+    includeArchivedSessions,
+    setIncludeArchivedSessions,
+    activeSessionId,
+    setActiveSession,
+    createSession,
+    patchSession,
+    messages,
+    messagesLoading,
+    streamingAssistantText,
+    streamingReasoning,
+    streamingToolCalls,
+    sendMessage,
+    stop,
+    isStoppingTurn,
+    pendingDraft,
+    consumePendingDraft: () => {
+      const draft = pendingDraft;
+      if (draft !== null) setPendingDraft(null);
+      return draft;
+    },
+    lastTurnError,
+    featureToggles,
+    refreshFeatureToggles,
+  };
+
+  return (
+    <aiHubContext.Provider value={value}>
+      <div className="data-club-ai-hub" data-theme={theme}>
+        {children}
+      </div>
+    </aiHubContext.Provider>
+  );
+}
+// `PatchSessionOptions` is re-exported elsewhere; keep the import live.
+export type { PatchSessionOptions };