@data-club/ai-hub 0.0.1

package/src/state/affordances.ts

@@ -0,0 +1,321 @@
+/**
+ * Affordance helpers — the pure-function half of Step 10.
+ *
+ * Two concerns live here:
+ *
+ * 1. **§8.4 precedence resolution.** `resolveAffordanceFlags()` composes
+ *    the three layers — server toggles (highest), React prop overrides,
+ *    built-in defaults — into one flat record of booleans. The monolith
+ *    `<DataClubAIHub />` calls this once and passes the resolved flags
+ *    down to layout / affordance primitives, so each primitive doesn't
+ *    have to re-implement the merge.
+ *
+ * 2. **§10.4 predicate table.** `chatAffordances()` is a pure function of
+ *    `(status, phase)` returning the predicate booleans the table calls
+ *    for ("Stop button visible", "Input disabled", "TPM banner",
+ *    "Streaming dots", etc.). Primitives consume the returned record
+ *    directly so the same predicates are tested in one place and never
+ *    drift between e.g. the stop button and the streaming-cursor
+ *    indicator.
+ *
+ * Neither function reads context — both are testable in isolation against
+ * the cross-package SSE fixtures. The provider's React surface is
+ * `useAIHub().featureToggles` (raw) + the helpers here.
+ *
+ * @see SPECIFICATIONS.md §8.4 — feature toggles
+ * @see SPECIFICATIONS.md §10.4 — affordances bound to (status, phase)
+ */
+
+import type {
+  AIHubFeatureToggles,
+  AIHubState,
+  RunningPhase,
+  TurnStatus,
+} from "../types.js";
+
+/**
+ * The flat, resolved (after-precedence) affordance flag record.
+ *
+ * Field names are camelCase here (React-side); the wire shape is
+ * snake_case (`AIHubFeatureToggles`). The mapping between the two is
+ * locked down by `resolveAffordanceFlags` below.
+ */
+export interface AIHubAffordanceFlags {
+  /** Whether the sessions panel renders at all. Default true. */
+  sessionsPanelEnabled: boolean;
+  /** Whether the sessions-panel handle is draggable. Default true. */
+  sessionsPanelResizable: boolean;
+  /** Whether the sessions panel can be collapsed. Default true. */
+  sessionsPanelCollapsible: boolean;
+  /** Whether the "+ New chat" button renders on the panel. Default true. */
+  createSessionButtonEnabled: boolean;
+  /** Whether the input area renders (read-only when false). Default true. */
+  userInputEnabled: boolean;
+  /** Whether the stop button is exposed while a turn is running. Default true. */
+  stopButtonEnabled: boolean;
+  /** Whether tool-call cards render in assistant bubbles. Default true. */
+  toolCallsVisible: boolean;
+  /** Whether reasoning blocks render in assistant bubbles. Default true. */
+  reasoningVisible: boolean;
+  /** Whether system messages render in the list. Default true. */
+  systemMessagesVisible: boolean;
+  /** Whether the TPM-recovery banner renders during waiting_provider. Default true. */
+  tpmNoticeVisible: boolean;
+  /** Whether the effort dropdown renders in the input toolbar. Default true. */
+  effortControlVisible: boolean;
+  /** Whether the scroll-to-present button renders when the user scrolled up. Default true. */
+  scrollToPresentVisible: boolean;
+  /** Whether the turn-status indicator renders in the chat header. Default true. */
+  turnStatusVisible: boolean;
+}
+
+/** Built-in defaults — applied when neither server nor React prop sets a value. */
+export const DEFAULT_AFFORDANCE_FLAGS: AIHubAffordanceFlags = Object.freeze({
+  sessionsPanelEnabled: true,
+  sessionsPanelResizable: true,
+  sessionsPanelCollapsible: true,
+  createSessionButtonEnabled: true,
+  userInputEnabled: true,
+  stopButtonEnabled: true,
+  toolCallsVisible: true,
+  reasoningVisible: true,
+  systemMessagesVisible: true,
+  tpmNoticeVisible: true,
+  effortControlVisible: true,
+  scrollToPresentVisible: true,
+  turnStatusVisible: true,
+}) as AIHubAffordanceFlags;
+
+/**
+ * Per-flag mapping from the wire key (`AIHubFeatureToggles`) to the
+ * camelCase field on `AIHubAffordanceFlags`. Exported so tests can
+ * iterate the §8.4 mapping without duplicating it in the test file.
+ */
+export const FEATURE_TOGGLE_KEY_MAP: ReadonlyArray<
+  readonly [keyof AIHubFeatureToggles, keyof AIHubAffordanceFlags]
+> = Object.freeze([
+  ["sessions_panel_enabled", "sessionsPanelEnabled"],
+  ["sessions_panel_resizable", "sessionsPanelResizable"],
+  ["sessions_panel_collapsible", "sessionsPanelCollapsible"],
+  ["create_session_button_enabled", "createSessionButtonEnabled"],
+  ["user_input_enabled", "userInputEnabled"],
+  ["stop_button_enabled", "stopButtonEnabled"],
+  ["tool_calls_visible", "toolCallsVisible"],
+  ["reasoning_visible", "reasoningVisible"],
+  ["system_messages_visible", "systemMessagesVisible"],
+  ["tpm_notice_visible", "tpmNoticeVisible"],
+  ["effort_control_visible", "effortControlVisible"],
+  ["scroll_to_present_visible", "scrollToPresentVisible"],
+  ["turn_status_visible", "turnStatusVisible"],
+]);
+
+/**
+ * Resolves the precedence stack for one toggle.
+ *
+ * **Server toggle > React prop > built-in default.** Documented in §8.4
+ * and enforced by this function alone — every caller that wants the
+ * effective state must go through here.
+ *
+ * @param serverValue - the server-set value (`undefined` when the
+ *   super_admin hasn't set this toggle explicitly).
+ * @param propValue - the React-prop override (`undefined` when the
+ *   wrapper didn't supply one).
+ * @param defaultValue - the built-in default for this flag.
+ * @returns the effective boolean.
+ */
+function resolveOne(
+  serverValue: boolean | undefined,
+  propValue: boolean | undefined,
+  defaultValue: boolean,
+): boolean {
+  if (typeof serverValue === "boolean") return serverValue;
+  if (typeof propValue === "boolean") return propValue;
+  return defaultValue;
+}
+
+/**
+ * Composes the three layers into a flat resolved record of all 13
+ * affordance booleans.
+ *
+ * Per §8.4: server toggle wins; falling through, the React prop wins;
+ * falling through that, the built-in default wins. Adding a new toggle
+ * requires updating `FEATURE_TOGGLE_KEY_MAP` + the schema in
+ * `routes/admin/settings.ts` + the field on `AIHubFeatureToggles` — the
+ * compile-time exhaustiveness check on the for-loop will surface any
+ * missed addition.
+ *
+ * @param serverToggles - the wire blob from `GET /feature-toggles`
+ *   (`null` while the request is in flight; treat as an empty blob).
+ * @param propOverrides - React-prop overrides keyed by the camelCase
+ *   field name (`AIHubAffordanceFlags`). All fields optional.
+ * @returns the fully-resolved record. Every field is a boolean.
+ */
+export function resolveAffordanceFlags(
+  serverToggles: AIHubFeatureToggles | null,
+  propOverrides: Partial<AIHubAffordanceFlags>,
+): AIHubAffordanceFlags {
+  const out = { ...DEFAULT_AFFORDANCE_FLAGS };
+  const server = serverToggles ?? {};
+  for (const [wireKey, fieldKey] of FEATURE_TOGGLE_KEY_MAP) {
+    out[fieldKey] = resolveOne(
+      server[wireKey],
+      propOverrides[fieldKey],
+      DEFAULT_AFFORDANCE_FLAGS[fieldKey],
+    );
+  }
+  return out;
+}
+
+/**
+ * The §10.4 predicate table — pure function of `(status, phase)` (lifted
+ * from `AIHubState`). Each field maps to one row of the table; primitives
+ * consume the booleans directly so the same predicate is sourced from one
+ * place.
+ *
+ * Some predicates depend on transient affordance flags (e.g. the stop
+ * button is suppressed when `stopButtonEnabled === false` from server
+ * config). For those the caller AND-merges the predicate result with the
+ * flag — keeping this function pure (no closure over flags) avoids
+ * coupling the §8.4 layer to the §10.4 layer.
+ */
+export interface AIHubChatAffordances {
+  /** §10.4 row "Stop button visible" — predicate only; ignore stopButtonEnabled here. */
+  stopButtonVisible: boolean;
+  /** §10.4 row "Input disabled". */
+  inputDisabled: boolean;
+  /**
+   * §10.4 row "Scroll-to-present button" — true when the *predicate* fires,
+   * which is `status === "running"`. The component additionally requires
+   * `userScrolledAwayFromBottom`, which is local state, not table state.
+   */
+  scrollToPresentVisible: boolean;
+  /** §10.4 row "Streaming dots" — `running && phase === model_text`. */
+  streamingDots: boolean;
+  /** §10.4 row "Reasoning spinner / panel" — `running && phase === model_reasoning`. */
+  reasoningSpinner: boolean;
+  /**
+   * §10.4 row "Tool-call card 'preparing'" — `phase === model_tool_input`.
+   * Note: spec says the predicate is just `phase === model_tool_input`,
+   * not `status === running` — `phase` is only meaningful when `status ===
+   * running` anyway, so the AND is implicit.
+   */
+  toolCallPreparing: boolean;
+  /** §10.4 row "Tool-call card 'running' with spinner" — `phase === tool_executing`. */
+  toolCallRunning: boolean;
+  /** §10.4 row "TPM banner with countdown" — `phase === waiting_provider`. */
+  tpmBannerVisible: boolean;
+  /** §10.4 row "'Stopped' stamp" — `status === cancelled`. */
+  cancelledStamp: boolean;
+  /** §10.4 row "Retry button on assistant turn" — `status === failed`. */
+  retryButtonVisible: boolean;
+}
+
+/**
+ * Computes the §10.4 predicate booleans for a given chat state.
+ *
+ * Pure function — `(state) => predicates`. Used by every affordance-aware
+ * component (`MessageInput`, `MessageList`, `ScrollToPresentButton`,
+ * `TurnStatusIndicator`, …) so the table lives in exactly one place.
+ *
+ * @param state - the current `AIHubState` from the reducer.
+ * @returns the predicate record.
+ */
+export function chatAffordances(state: AIHubState): AIHubChatAffordances {
+  const isRunning = state.status === "running";
+  return {
+    stopButtonVisible: isRunning,
+    inputDisabled: isRunning,
+    scrollToPresentVisible: isRunning,
+    streamingDots: isRunning && state.phase === "model_text",
+    reasoningSpinner: isRunning && state.phase === "model_reasoning",
+    toolCallPreparing: isRunning && state.phase === "model_tool_input",
+    toolCallRunning: isRunning && state.phase === "tool_executing",
+    tpmBannerVisible: isRunning && state.phase === "waiting_provider",
+    cancelledStamp: state.status === "cancelled",
+    retryButtonVisible: state.status === "failed",
+  };
+}
+
+/**
+ * The §10.4 turn-status indicator table — pure function of `(status,
+ * phase)` returning the user-visible label + the dot variant the
+ * `TurnStatusIndicator` primitive renders.
+ *
+ * Three dot variants exist:
+ *
+ * - `"idle"` — gray, static
+ * - `"running"` — accent, pulsing
+ * - `"warning"` — warning yellow, pulsing (rate-limit wait)
+ * - `"error"` — error red, static
+ *
+ * Mapping is exactly the table from §10.4. The transient flashes ("Done"
+ * before settling to "Ready", "Cancelled" before settling to "Ready")
+ * are not encoded here — those are handled in the component via
+ * `useEffect` + a short timer.
+ */
+export interface AIHubTurnStatusVisual {
+  /** Short human-readable label rendered next to the dot. */
+  label: string;
+  /** Dot variant — drives the BEM modifier on the dot element. */
+  dot: "idle" | "running" | "warning" | "error";
+  /** Whether the dot pulses (suppressed under `prefers-reduced-motion`). */
+  pulse: boolean;
+}
+
+/**
+ * Computes the §10.4 turn-status indicator's `(label, dot, pulse)` from
+ * a `(status, phase)` pair.
+ *
+ * Pure. Drives the BEM modifier on the dot + the label text inside the
+ * indicator. The "Done" flash and the "Cancelled → Ready" auto-clear
+ * timings are local to the component.
+ *
+ * @param status - the turn status.
+ * @param phase - the running phase (only meaningful when status === running).
+ * @returns the visual triple.
+ */
+export function turnStatusVisual(
+  status: TurnStatus,
+  phase: RunningPhase | null,
+): AIHubTurnStatusVisual {
+  if (status === "running") {
+    switch (phase) {
+      case "model_text":
+        return { label: "Generating…", dot: "running", pulse: true };
+      case "model_reasoning":
+        return { label: "Reasoning…", dot: "running", pulse: true };
+      case "model_tool_input":
+        return {
+          label: "Preparing tool call…",
+          dot: "running",
+          pulse: true,
+        };
+      case "tool_executing":
+        return { label: "Running tool…", dot: "running", pulse: true };
+      case "waiting_provider":
+        return {
+          label: "Waiting (rate limit)…",
+          dot: "warning",
+          pulse: true,
+        };
+      case "awaiting_user":
+        // Not exercised by the predicate table (the spec doesn't surface
+        // a label for awaiting_user); fall back to "Ready" so the dot
+        // doesn't strobe.
+        return { label: "Ready", dot: "idle", pulse: false };
+      case null:
+        return { label: "Generating…", dot: "running", pulse: true };
+    }
+  }
+  if (status === "failed") {
+    return { label: "Failed", dot: "error", pulse: false };
+  }
+  if (status === "cancelled") {
+    return { label: "Cancelled", dot: "idle", pulse: false };
+  }
+  if (status === "done") {
+    return { label: "Done", dot: "idle", pulse: false };
+  }
+  // idle
+  return { label: "Ready", dot: "idle", pulse: false };
+}

package/src/state/stateReducer.ts

@@ -0,0 +1,131 @@
+/**
+ * Client-side state reducer for `AIHubState`.
+ *
+ * The ai-hub server is the authoritative source of state (§6.6, §10). Every
+ * SSE event carries a `state: { status, phase }` snapshot at emission time
+ * (§9); the client's job is to trust that snapshot and enrich it with the
+ * cross-event fields the UI needs to render — `last_seq` (for the resumption
+ * cursor), `turn_id` (from `stream_start`), `session_id`, and `tpm_retry_at`
+ * (the countdown deadline read from the latest `system_notice {tpm_wait}`).
+ *
+ * Because the server emits the `(status, phase)` directly on every event, the
+ * reducer does **not** re-derive the transitions from §10.2 — it just lifts
+ * the snapshot. The §10.2 arrows are tested via the cross-package SSE
+ * fixtures (`packages/ai-hub-server/__tests__/fixtures/sse/*.json`): each
+ * fixture replays the bytes the server emits and the reducer's per-event
+ * output is asserted to match the expected `(status, phase)` for that arrow.
+ *
+ * @see SPECIFICATIONS.md §6.6 — server-authoritative state
+ * @see SPECIFICATIONS.md §7.5 — state on the client
+ * @see SPECIFICATIONS.md §9   — wire protocol
+ * @see SPECIFICATIONS.md §10  — state machine
+ */
+
+import type { AIHubEvent, AIHubState } from "../types.js";
+
+/**
+ * The reducer's starting state, before any event has been seen.
+ *
+ * `last_seq: -1` is the convention used as the `from_seq` cursor on the
+ * resumption endpoint (`/chat/{turn_id}/events?from_seq=N`) — the server
+ * matches with `seq > N`, so `-1` replays every event from `seq: 0`
+ * forward (`server/routes/chat.ts`).
+ *
+ * @returns the initial state.
+ */
+export function initialAIHubState(): AIHubState {
+  return {
+    status: "idle",
+    phase: null,
+    last_seq: -1,
+    turn_id: null,
+    session_id: null,
+    tpm_retry_at: null,
+  };
+}
+
+/**
+ * Reduces one `AIHubEvent` into the next `AIHubState`.
+ *
+ * Pure. Re-runnable. The provider replays the same event sequence on
+ * reconnect-by-replay and lands on the same state every time — that's the
+ * load-bearing property the resumption flow depends on.
+ *
+ * Behavioural notes (each maps to a §10.2 arrow or §10.3 rule, and is locked
+ * down by the SSE fixtures consumed in `__tests__/state/stateReducer.test.ts`):
+ *
+ * - `stream_start` → captures `turn_id` + `session_id`; clears any leftover
+ *   `tpm_retry_at` from a previous turn (defensive; a fresh turn should
+ *   never inherit one).
+ * - `system_notice {code: "tpm_wait"}` → stores `retry_at` so the TPM banner
+ *   (Step 10) can render its countdown. The `(status, phase)` snapshot on
+ *   the event is already `running / waiting_provider` per §10.2.
+ * - `system_notice {code: "resumed"}` → clears `tpm_retry_at`. Snapshot is
+ *   back to `running / model_text` (or whatever the recovery resumes into).
+ * - `error` → server already emitted `(status: failed, phase: null)`; the
+ *   reducer just lifts it and clears `tpm_retry_at` so a Retry button
+ *   doesn't render a stale countdown.
+ * - `stream_end` → terminal `(status, phase)` is already on the snapshot;
+ *   `tpm_retry_at` is cleared for the same reason as `error`.
+ * - All other events → `(status, phase)` + `last_seq` are lifted from the
+ *   snapshot; nothing else changes. The §10.3 tool-error-vs-agent-error
+ *   rule is honored entirely by the server's snapshot (a `tool_call_result`
+ *   with an `error` field carries `phase: model_text` and `status: running`;
+ *   only an `error` event carries `status: failed`).
+ *
+ * @param state - the previous `AIHubState`.
+ * @param event - the next event from the SSE stream.
+ * @returns the next `AIHubState`.
+ *
+ * @see SPECIFICATIONS.md §10.2 — transitions
+ * @see SPECIFICATIONS.md §10.3 — tool error vs. agent error
+ */
+export function reduceAIHubState(
+  state: AIHubState,
+  event: AIHubEvent,
+): AIHubState {
+  // Lift the snapshot + advance the resumption cursor. Every branch below
+  // refines this base value.
+  const next: AIHubState = {
+    ...state,
+    status: event.state.status,
+    phase: event.state.phase,
+    last_seq: event.seq,
+  };
+
+  switch (event.event) {
+    case "stream_start":
+      next.turn_id = event.data.turn_id;
+      next.session_id = event.data.session_id;
+      next.tpm_retry_at = null;
+      return next;
+
+    case "system_notice":
+      if (event.data.code === "tpm_wait") {
+        // `retry_at` is optional on the wire; absent → no countdown, the
+        // banner renders without a timer. We still keep the `waiting_provider`
+        // phase from the snapshot so the affordance flips.
+        next.tpm_retry_at = event.data.retry_at ?? null;
+      } else if (event.data.code === "resumed") {
+        next.tpm_retry_at = null;
+      }
+      return next;
+
+    case "error":
+    case "stream_end":
+      next.tpm_retry_at = null;
+      return next;
+
+    case "heartbeat":
+    case "assistant_delta":
+    case "reasoning_delta":
+    case "assistant_message_complete":
+    case "tool_call_started":
+    case "tool_call_input_delta":
+    case "tool_call_dispatched":
+    case "tool_call_progress":
+    case "tool_call_result":
+    case "usage":
+      return next;
+  }
+}

package/src/stories/EffortControl.stories.tsx

@@ -0,0 +1,63 @@
+/**
+ * Stories for `<EffortControl />` — reasoning-effort dropdown.
+ *
+ * @see SPECIFICATIONS.md §7.4 — reasoning effort
+ */
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { EffortControl } from "../components/EffortControl/index.js";
+import type { AIHubEffort } from "../client/AIHubClient.js";
+
+import { MockProvider } from "./_mockProvider.js";
+
+function withEffort(effort: AIHubEffort) {
+  return (Story: () => React.ReactNode) => (
+    <MockProvider opts={{ effort }}>
+      <Story />
+    </MockProvider>
+  );
+}
+
+const meta: Meta<typeof EffortControl> = {
+  title: "Affordances/EffortControl",
+  component: EffortControl,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Reasoning-effort dropdown mirroring Letta's ADE enum (None | Minimal | Low | Medium | High | Extra High). Per-message; persists in provider state until changed.",
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof EffortControl>;
+
+export const DefaultMedium: Story = {
+  decorators: [withEffort("medium")],
+};
+
+export const SetToNone: Story = {
+  decorators: [withEffort("none")],
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "`none` is the off-state for reasoning; there is no separate reasoning toggle.",
+      },
+    },
+  },
+};
+
+export const Disabled: Story = {
+  decorators: [withEffort("medium")],
+  args: { disabled: true },
+  parameters: {
+    docs: {
+      description: {
+        story: "Disabled while a turn is streaming.",
+      },
+    },
+  },
+};