@data-club/ai-hub 0.0.1

package/src/components/ReasoningSelector/index.tsx

@@ -0,0 +1,268 @@
+/**
+ * `<ReasoningSelector />` — capability-driven per-session reasoning UI.
+ *
+ * Renders a dynamic set of dropdowns based on the active session's
+ * `capabilities` (computed server-side from the agent's model handle):
+ *
+ *  - **Anthropic / Bedrock** models → one "Effort" dropdown
+ *     (`low | medium | high | xhigh | max`).
+ *  - **OpenAI / OpenRouter** models → two independent dropdowns:
+ *     "Reasoning" (`none | minimal | low | medium | high | xhigh`)
+ *     and "Verbosity" (`low | medium | high`).
+ *  - **Google AI / Vertex** models → numeric "Thinking budget" input.
+ *  - **Models with no reasoning surface** (Z.AI, etc.) → renders nothing.
+ *
+ * Schema-driven: the dropdown enums come from the server's capability map,
+ * which in turn mirrors Letta's per-provider `*ModelSettings` shape. When
+ * Letta adds new values (e.g. a sixth effort tier), the server publishes
+ * them and the dropdown picks them up automatically — no UI changes needed.
+ *
+ * Wire flow: on change, calls `client.patchSessionReasoning(...)` which
+ * PATCHes the session row. The next `POST /chat` reads the new value and
+ * applies it to the agent's `model_settings` before opening the stream
+ * (see `chat.ts` pre-turn sync).
+ *
+ * Exported under `AIHub.ReasoningSelector`.
+ *
+ * @see SPECIFICATIONS.md §7.4 — reasoning effort surface
+ * @see packages/ai-hub-server/src/letta/modelSettings.ts — capability map
+ *      + `buildModelSettings()` (the wire-shape construction)
+ */
+
+import { useEffect, useState, type ChangeEvent, type ReactNode } from "react";
+
+import { useAIHub } from "../../context/useAIHub.js";
+import type { Session } from "../../types.js";
+
+/** BEM class names emitted by `<ReasoningSelector />`. */
+export interface ReasoningSelectorClassNames {
+  /** The wrapper around the entire selector (may render 0..N child dropdowns). */
+  root: string;
+  /** Each individual `<label>` row. */
+  field: string;
+  /** Each label's text. */
+  label: string;
+  /** Each `<select>` element. */
+  select: string;
+  /** The numeric `<input>` (thinking budget). */
+  input: string;
+}
+
+const DEFAULT_CLASS_NAMES: ReasoningSelectorClassNames = Object.freeze({
+  root: "data-club-ai-hub__reasoning-selector",
+  field: "data-club-ai-hub__reasoning-selector__field",
+  label: "data-club-ai-hub__reasoning-selector__label",
+  select: "data-club-ai-hub__reasoning-selector__select",
+  input: "data-club-ai-hub__reasoning-selector__input",
+}) as ReasoningSelectorClassNames;
+
+/** Props for `<ReasoningSelector />`. */
+export interface ReasoningSelectorProps {
+  /** Disable all inputs (e.g. while a turn is streaming). Default false. */
+  disabled?: boolean;
+  /**
+   * Optional label overrides. When omitted, sensible English defaults
+   * apply (`"Reasoning"`, `"Verbosity"`, `"Thinking budget"`).
+   *
+   * The reasoning dropdown uses one label (`reasoning`) regardless of
+   * whether the agent's model uses Anthropic-style `effort` or
+   * OpenAI-style `reasoning_effort` on the wire — from the user's
+   * perspective it's the same "how hard should the model think" knob.
+   */
+  labels?: {
+    reasoning?: string;
+    verbosity?: string;
+    thinkingBudget?: string;
+    /** Empty-state placeholder option (e.g. "Default"). */
+    defaultPlaceholder?: string;
+  };
+  /** Extra class merged onto the root. */
+  className?: string;
+  /** Per-element class overrides. */
+  classNames?: Partial<ReasoningSelectorClassNames>;
+}
+
+/**
+ * Capitalizes an enum value for the dropdown label — `"xhigh" → "X-High"`,
+ * `"max" → "Max"`. Keeps the wire enum honest and labels readable.
+ */
+function labelize(value: string): string {
+  if (value === "xhigh") return "Extra High";
+  if (value === "none") return "Off";
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}
+
+/**
+ * Renders the capability-driven reasoning selector. Returns `null` when
+ * the active session's model has no reasoning surface.
+ *
+ * @param props - see `ReasoningSelectorProps`.
+ */
+export function ReasoningSelector(
+  props: ReasoningSelectorProps,
+): ReactNode {
+  const { client, activeSessionId, state } = useAIHub();
+  const cls = { ...DEFAULT_CLASS_NAMES, ...(props.classNames ?? {}) };
+  const rootClass = props.className ? `${cls.root} ${props.className}` : cls.root;
+
+  // Per-component fetch: capabilities come from `GET /sessions/:id` (not
+  // the list endpoint). Re-fetched whenever the active session changes.
+  const [session, setSession] = useState<Session | null>(null);
+  const [saving, setSaving] = useState(false);
+
+  useEffect(() => {
+    let cancelled = false;
+    if (!activeSessionId) {
+      setSession(null);
+      return;
+    }
+    void (async () => {
+      try {
+        const s = await client.getSession(activeSessionId);
+        if (!cancelled) setSession(s);
+      } catch {
+        if (!cancelled) setSession(null);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [activeSessionId, client]);
+
+  if (!session) return null;
+  const caps = session.capabilities;
+  if (!caps) return null;
+
+  const hasAnyControl =
+    caps.effort !== undefined ||
+    caps.reasoning_effort !== undefined ||
+    caps.verbosity !== undefined ||
+    caps.thinking_budget !== undefined;
+  if (!hasAnyControl) return null;
+
+  const labels = {
+    reasoning: props.labels?.reasoning ?? "Reasoning",
+    verbosity: props.labels?.verbosity ?? "Verbosity",
+    thinkingBudget: props.labels?.thinkingBudget ?? "Thinking budget",
+    defaultPlaceholder: props.labels?.defaultPlaceholder ?? "Default",
+  };
+
+  // Disabled when caller says so OR when a turn is streaming — keeps the
+  // user from changing settings mid-turn (the PATCH would race the
+  // pre-turn sync).
+  const disabled = (props.disabled ?? false) || state.status === "running";
+
+  async function persistPatch(
+    field: "effort" | "verbosity" | "thinkingBudget",
+    value: string | number | null,
+  ): Promise<void> {
+    if (!activeSessionId) return;
+    setSaving(true);
+    try {
+      const patch: Parameters<typeof client.patchSessionReasoning>[1] = {};
+      if (field === "effort") patch.effort = value as string | null;
+      else if (field === "verbosity") patch.verbosity = value as string | null;
+      else patch.thinkingBudget = value as number | null;
+      const updated = await client.patchSessionReasoning(activeSessionId, patch);
+      setSession(updated);
+    } catch {
+      // Soft-fail: leave the existing state. A toast / banner could be
+      // added later; matching pattern with patchSession (which also
+      // doesn't surface errors to users).
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  function handleEffortChange(e: ChangeEvent<HTMLSelectElement>): void {
+    const v = e.target.value;
+    void persistPatch("effort", v === "" ? null : v);
+  }
+  function handleVerbosityChange(e: ChangeEvent<HTMLSelectElement>): void {
+    const v = e.target.value;
+    void persistPatch("verbosity", v === "" ? null : v);
+  }
+  function handleBudgetChange(e: ChangeEvent<HTMLInputElement>): void {
+    const v = e.target.value;
+    void persistPatch("thinkingBudget", v === "" ? null : Number(v));
+  }
+
+  const currentEffort = session.reasoning?.effort ?? "";
+  const currentVerbosity = session.reasoning?.verbosity ?? "";
+  const currentBudget = session.reasoning?.thinking_budget ?? "";
+
+  // Anthropic uses `effort`, OpenAI uses `reasoning_effort` — same control
+  // shape (dropdown), different field on the wire. Server stores either
+  // in `session.reasoning.effort` (we don't split into two columns —
+  // it's contextual to the agent's model). The UI label is unified —
+  // both render as "Reasoning" so the user sees one consistent control.
+  const effortCap = caps.effort ?? caps.reasoning_effort;
+  const effortLabel = labels.reasoning;
+
+  return (
+    <div
+      className={rootClass}
+      data-testid="reasoning-selector"
+      data-saving={saving ? "true" : undefined}
+    >
+      {effortCap !== undefined && (
+        <label className={cls.field}>
+          <span className={cls.label}>{effortLabel}</span>
+          <select
+            className={cls.select}
+            value={currentEffort}
+            onChange={handleEffortChange}
+            disabled={disabled || saving}
+            data-testid="reasoning-selector-effort"
+            aria-label={effortLabel}
+          >
+            <option value="">{labels.defaultPlaceholder}</option>
+            {effortCap.enum.map((v) => (
+              <option key={v} value={v}>
+                {labelize(v)}
+              </option>
+            ))}
+          </select>
+        </label>
+      )}
+      {caps.verbosity !== undefined && (
+        <label className={cls.field}>
+          <span className={cls.label}>{labels.verbosity}</span>
+          <select
+            className={cls.select}
+            value={currentVerbosity}
+            onChange={handleVerbosityChange}
+            disabled={disabled || saving}
+            data-testid="reasoning-selector-verbosity"
+            aria-label={labels.verbosity}
+          >
+            <option value="">{labels.defaultPlaceholder}</option>
+            {caps.verbosity.enum.map((v) => (
+              <option key={v} value={v}>
+                {labelize(v)}
+              </option>
+            ))}
+          </select>
+        </label>
+      )}
+      {caps.thinking_budget !== undefined && (
+        <label className={cls.field}>
+          <span className={cls.label}>{labels.thinkingBudget}</span>
+          <input
+            type="number"
+            className={cls.input}
+            value={currentBudget}
+            min={caps.thinking_budget.min}
+            max={caps.thinking_budget.max}
+            step={256}
+            onChange={handleBudgetChange}
+            disabled={disabled || saving}
+            data-testid="reasoning-selector-budget"
+            aria-label={labels.thinkingBudget}
+            placeholder={labels.defaultPlaceholder}
+          />
+        </label>
+      )}
+    </div>
+  );
+}

package/src/components/ReasoningView/index.tsx

@@ -0,0 +1,183 @@
+/**
+ * `<ReasoningView />` — collapsible reasoning block inside an assistant
+ * bubble.
+ *
+ * Default-collapsed (the spec calls this out — reasoning is for "I want
+ * to inspect this" UX, not "I want to read it inline by default").
+ * Header shows the duration when known; body is rendered in monospace.
+ *
+ * Step 10 only renders reasoning when:
+ *
+ * - the turn was sent with a non-`none` effort (i.e. the assistant
+ *   actually produced a reasoning block), AND
+ * - `reasoningVisible` (resolved) is true.
+ *
+ * The decision about whether reasoning is *present* lives upstream in
+ * `MessageList` — this primitive just renders whatever block content +
+ * timing it's given.
+ *
+ * Exported under `AIHub.ReasoningView` (re-exported via the namespace).
+ *
+ * @see SPECIFICATIONS.md §7.3 — showReasoning prop
+ * @see ui-sketches/03-chat.md — reasoning_block --collapsed / --expanded
+ */
+
+import { useState, type ReactNode } from "react";
+
+import {
+  resolveAIHubTexts,
+  type AIHubTexts,
+  type DeepPartial,
+} from "../../auth/texts.js";
+
+/** BEM class names emitted by `<ReasoningView />`. */
+export interface ReasoningViewClassNames {
+  /** Outer block. */
+  root: string;
+  /** Modifier — `--collapsed`. */
+  rootCollapsed: string;
+  /** Modifier — `--expanded`. */
+  rootExpanded: string;
+  /** Header element (always present). */
+  header: string;
+  /** Title text inside the header. */
+  title: string;
+  /** Expand/collapse toggle button. */
+  toggle: string;
+  /** Body element (only mounted when expanded). */
+  body: string;
+}
+
+const DEFAULT_CLASS_NAMES: ReasoningViewClassNames = Object.freeze({
+  root: "data-club-ai-hub__reasoning-block",
+  rootCollapsed: "data-club-ai-hub__reasoning-block--collapsed",
+  rootExpanded: "data-club-ai-hub__reasoning-block--expanded",
+  header: "data-club-ai-hub__reasoning-block__header",
+  title: "data-club-ai-hub__reasoning-block__title",
+  toggle: "data-club-ai-hub__reasoning-block__toggle",
+  body: "data-club-ai-hub__reasoning-block__body",
+}) as ReasoningViewClassNames;
+
+/** Props for `<ReasoningView />`. */
+export interface ReasoningViewProps {
+  /** The reasoning text (possibly empty while deltas are still arriving). */
+  content: string;
+  /** Wall-clock duration in seconds, when known. */
+  durationSeconds?: number;
+  /**
+   * When true, the block is still streaming — placeholder text is
+   * shown instead of an empty body and the duration is omitted.
+   */
+  streaming?: boolean;
+  /**
+   * Override the initial expanded state. Default false (collapsed). When
+   * `streaming` is true the initial state is also false — the user opts
+   * in to watch the reasoning live.
+   *
+   * Ignored when `expanded` is passed (controlled mode).
+   */
+  defaultExpanded?: boolean;
+  /**
+   * Controlled expanded state. When set, `<ReasoningView />` defers all
+   * expand/collapse decisions to the parent — `onToggle` fires on toggle
+   * clicks and the parent decides whether the next render should pass
+   * `true` or `false`. Used by `<MessageList />` to enforce the
+   * accordion + auto-expand-while-streaming rules across all blocks in
+   * the conversation. When omitted, the component falls back to internal
+   * `useState` for backward compatibility (the original uncontrolled
+   * behavior, default-collapsed with a per-instance toggle).
+   */
+  expanded?: boolean;
+  /**
+   * Toggle handler for the controlled mode. Fires when the user clicks
+   * the expand/collapse button. The parent inspects its own accordion
+   * state to compute the next `expanded` prop. Ignored in uncontrolled
+   * mode (the internal `useState` toggles itself).
+   */
+  onToggle?: () => void;
+  /** Wrapper-supplied i18n. */
+  texts?: DeepPartial<AIHubTexts>;
+  /** Extra class merged onto the root. */
+  className?: string;
+  /** Per-element class overrides. */
+  classNames?: Partial<ReasoningViewClassNames>;
+}
+
+/**
+ * Renders the reasoning block.
+ *
+ * @param props - see `ReasoningViewProps`.
+ * @returns the rendered block.
+ */
+export function ReasoningView(props: ReasoningViewProps): ReactNode {
+  const texts = resolveAIHubTexts(props.texts);
+  const cls = { ...DEFAULT_CLASS_NAMES, ...(props.classNames ?? {}) };
+  const [uncontrolledExpanded, setUncontrolledExpanded] = useState(
+    props.defaultExpanded ?? false,
+  );
+  const isControlled = props.expanded !== undefined;
+  const expanded = isControlled ? (props.expanded as boolean) : uncontrolledExpanded;
+  const handleToggle = isControlled
+    ? props.onToggle ?? (() => {})
+    : () => setUncontrolledExpanded((e) => !e);
+
+  const seconds = props.durationSeconds ?? 0;
+  // Pick the WITH-duration template only when we actually have a
+  // duration to show. Historical bubbles (loaded via `getSessionMessages`)
+  // don't carry a duration today, so they render the no-duration variant
+  // ("🧠 Reasoning") rather than the awkward "🧠 Reasoning  (…s)" we'd
+  // get from running the placeholder substitution against zero.
+  const hasDuration = seconds > 0;
+  let headerText: string;
+  if (hasDuration) {
+    const template = expanded
+      ? texts.chat.reasoningExpandedHeader
+      : texts.chat.reasoningCollapsedHeader;
+    headerText = template.replace("{seconds}", seconds.toFixed(1));
+  } else {
+    headerText = expanded
+      ? texts.chat.reasoningExpandedHeaderNoDuration
+      : texts.chat.reasoningCollapsedHeaderNoDuration;
+  }
+
+  const rootClass = [
+    cls.root,
+    expanded ? cls.rootExpanded : cls.rootCollapsed,
+    props.className,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  return (
+    <div
+      className={rootClass}
+      data-testid="reasoning-view"
+      data-expanded={expanded ? "true" : "false"}
+    >
+      <div className={cls.header}>
+        <span className={cls.title}>{headerText}</span>
+        <button
+          type="button"
+          className={cls.toggle}
+          onClick={handleToggle}
+          aria-expanded={expanded}
+          aria-label={
+            expanded
+              ? texts.chat.reasoningCollapseAriaLabel
+              : texts.chat.reasoningExpandAriaLabel
+          }
+          data-testid="reasoning-view-toggle"
+        >
+          {expanded ? "▼" : "▶"}
+        </button>
+      </div>
+      {expanded ? (
+        <div className={cls.body} data-testid="reasoning-view-body">
+          {props.streaming && props.content.trim().length === 0
+            ? texts.chat.reasoningThinkingPlaceholder
+            : props.content}
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/components/ScrollToPresentButton/index.tsx

@@ -0,0 +1,85 @@
+/**
+ * `<ScrollToPresentButton />` — floating "↓ Jump to latest" button that
+ * appears when the user has scrolled away from the bottom of the
+ * message list during a running turn.
+ *
+ * The §10.4 predicate is `status === "running" && userScrolledAwayFromBottom`.
+ * The `status` half is computed via `chatAffordances`; the
+ * `userScrolledAwayFromBottom` half is local to the message list. This
+ * primitive accepts both as props so the predicate logic stays out of
+ * the primitive (which would otherwise need to reach into a scroll
+ * ref it doesn't own).
+ *
+ * Rendering also requires `scrollToPresentVisible` (server toggle ∧
+ * React prop) — the parent does that AND-merge upstream before
+ * passing `visible` here.
+ *
+ * Exported under `AIHub.ScrollToPresentButton`.
+ *
+ * @see SPECIFICATIONS.md §10.4 — scroll-to-present predicate
+ * @see ui-sketches/03-chat.md — scroll_to_present_button
+ */
+
+import { type ReactNode } from "react";
+
+import {
+  resolveAIHubTexts,
+  type AIHubTexts,
+  type DeepPartial,
+} from "../../auth/texts.js";
+
+/** BEM class names emitted by `<ScrollToPresentButton />`. */
+export interface ScrollToPresentButtonClassNames {
+  /** Outer button element. */
+  root: string;
+}
+
+const DEFAULT_CLASS_NAMES: ScrollToPresentButtonClassNames = Object.freeze({
+  root: "data-club-ai-hub__scroll-to-present-button",
+}) as ScrollToPresentButtonClassNames;
+
+/** Props for `<ScrollToPresentButton />`. */
+export interface ScrollToPresentButtonProps {
+  /**
+   * Whether to render. Caller computes the predicate via
+   * `chatAffordances(state).scrollToPresentVisible &&
+   * userScrolledAwayFromBottom && scrollToPresentVisibleFlag`.
+   * Passing `false` returns `null`.
+   */
+  visible: boolean;
+  /** Click handler — typically scrolls the message list container. */
+  onClick: () => void;
+  /** Wrapper-supplied i18n. */
+  texts?: DeepPartial<AIHubTexts>;
+  /** Extra class merged onto the root. */
+  className?: string;
+  /** Per-element class overrides. */
+  classNames?: Partial<ScrollToPresentButtonClassNames>;
+}
+
+/**
+ * Renders the button.
+ *
+ * @param props - see `ScrollToPresentButtonProps`.
+ * @returns the rendered button, or `null` when hidden.
+ */
+export function ScrollToPresentButton(
+  props: ScrollToPresentButtonProps,
+): ReactNode {
+  if (!props.visible) return null;
+  const texts = resolveAIHubTexts(props.texts);
+  const cls = { ...DEFAULT_CLASS_NAMES, ...(props.classNames ?? {}) };
+  const rootClass = props.className
+    ? `${cls.root} ${props.className}`
+    : cls.root;
+  return (
+    <button
+      type="button"
+      className={rootClass}
+      onClick={props.onClick}
+      data-testid="scroll-to-present-button"
+    >
+      {texts.chat.scrollToPresentButton}
+    </button>
+  );
+}