@data-club/ai-hub 0.0.3 → 0.0.5

package/src/auth/texts.ts

@@ -304,6 +304,26 @@ export interface AIHubChatTexts {
   /* ── Language switcher (header, beside the user avatar) ─────────── */
   /** `aria-label` / tooltip on the language-switcher button. */
   languageSwitcherAriaLabel: string;
+
+  /* ── Turn-status indicator (§10.4 — `●` dot + label) ───────────── */
+  /** Idle / ready (no turn in flight). */
+  turnStatusReady: string;
+  /** `running` + `model_text` (or unknown phase) — assistant text streaming. */
+  turnStatusGenerating: string;
+  /** `running` + `model_reasoning`. */
+  turnStatusReasoning: string;
+  /** `running` + `model_tool_input` — assembling a tool call. */
+  turnStatusPreparingTool: string;
+  /** `running` + `tool_executing`. */
+  turnStatusRunningTool: string;
+  /** `running` + `waiting_provider` — rate-limited / recovering. */
+  turnStatusWaitingRateLimit: string;
+  /** Terminal `failed`. */
+  turnStatusFailed: string;
+  /** Terminal `cancelled` (before the auto-clear to ready). */
+  turnStatusCancelled: string;
+  /** Terminal `done` (the brief flash before settling to ready). */
+  turnStatusDone: string;
 }
 
 /**
@@ -794,6 +814,16 @@ export interface AIHubAdminTexts {
   settingsLanguageLockedHelper: string;
   settingsSaveLanguageButton: string;
 
+  /* Agents section. */
+  settingsAgentsSectionHeading: string;
+  settingsAgentsDefaultLabel: string;
+  /** First `<option>` — no default agent (show the picker). */
+  settingsAgentsDefaultNone: string;
+  settingsAgentsDefaultHelper: string;
+  settingsAgentsSwitcherEnabledLabel: string;
+  settingsAgentsSwitcherEnabledHelper: string;
+  settingsSaveAgentsButton: string;
+
   /* Feature toggles section. */
   settingsTogglesSectionHeading: string;
   settingsTogglesGroupSessions: string;
@@ -973,6 +1003,16 @@ export const defaultAIHubTexts: AIHubTexts = Object.freeze({
     openLettaAdeMenuItem: "Open Letta ADE",
     /* Language switcher. */
     languageSwitcherAriaLabel: "Change language",
+    /* Turn-status indicator. */
+    turnStatusReady: "Ready",
+    turnStatusGenerating: "Generating…",
+    turnStatusReasoning: "Reasoning…",
+    turnStatusPreparingTool: "Preparing tool call…",
+    turnStatusRunningTool: "Running tool…",
+    turnStatusWaitingRateLimit: "Waiting (rate limit)…",
+    turnStatusFailed: "Failed",
+    turnStatusCancelled: "Cancelled",
+    turnStatusDone: "Done",
   }),
   admin: Object.freeze({
     /* Shell. */
@@ -1250,6 +1290,15 @@ export const defaultAIHubTexts: AIHubTexts = Object.freeze({
     settingsLanguageLockedHelper:
       "When on, the language switcher is hidden and every user sees the default language. When off, users can pick their own language and their choice is remembered on their device.",
     settingsSaveLanguageButton: "Save language",
+    settingsAgentsSectionHeading: "Agents",
+    settingsAgentsDefaultLabel: "Default agent",
+    settingsAgentsDefaultNone: "No default — show the agent list",
+    settingsAgentsDefaultHelper:
+      "When set, users open straight into this agent instead of the picker. A deployment with a single agent always opens that one regardless of this setting.",
+    settingsAgentsSwitcherEnabledLabel: "Allow users to switch agents",
+    settingsAgentsSwitcherEnabledHelper:
+      "When off, the “← Agents” back link is hidden so users stay on their agent. It is also hidden whenever only one agent exists.",
+    settingsSaveAgentsButton: "Save agents",
     settingsTogglesSectionHeading: "UI feature toggles",
     settingsTogglesGroupSessions: "Sessions panel",
     settingsTogglesGroupInput: "Input",

package/src/client/AIHubClient.ts

@@ -583,6 +583,13 @@ export interface AdminSettingsView {
     default: AIHubLanguage;
     user_locked: boolean;
   };
+  /** Agent-picker settings, stored as separate columns server-side. */
+  agents: {
+    /** Default ai-hub agent id auto-opened on load, or `null` for the picker. */
+    default_id: string | null;
+    /** Whether users may switch agents (the "← Agents" back link). */
+    switcher_enabled: boolean;
+  };
   /** The flat §8.4 feature-toggles blob. */
   feature_toggles: AIHubFeatureToggles;
   /** ISO-8601 of the last signing-key rotation. `null` until first rotation. */
@@ -611,6 +618,12 @@ export interface PatchAdminSettingsBody {
     default?: AIHubLanguage;
     userLocked?: boolean;
   };
+  /** Agent-picker partial — either or both fields. */
+  agents?: {
+    /** Agent id to default to; `null` / `""` clears (→ show the picker). */
+    defaultId?: string | null;
+    switcherEnabled?: boolean;
+  };
 }
 
 /** Response from `rotateAdminMetricsToken` — the new token returned **once**. */
@@ -1505,6 +1518,16 @@ export class AIHubClient {
       }
       wire.language = languageWire;
     }
+    if (body.agents !== undefined) {
+      const agentsWire: Record<string, unknown> = {};
+      if (body.agents.defaultId !== undefined) {
+        agentsWire.default_id = body.agents.defaultId;
+      }
+      if (body.agents.switcherEnabled !== undefined) {
+        agentsWire.switcher_enabled = body.agents.switcherEnabled;
+      }
+      wire.agents = agentsWire;
+    }
     return this.requestJson<AdminSettingsView>("PATCH", "/admin/settings", {
       body: wire,
     });

package/src/components/ChatShell/index.tsx

@@ -13,7 +13,7 @@
  * @see ui-sketches/00-shell.md, ui-sketches/03-chat.md
  */
 
-import { useEffect, useMemo, type ReactNode } from "react";
+import { useEffect, useMemo, useRef, type ReactNode } from "react";
 
 import {
   type AIHubTexts,
@@ -21,6 +21,7 @@ import {
 } from "../../auth/texts.js";
 import { useResolvedTexts } from "../../context/useAIHubTexts.js";
 import { useAIHub } from "../../context/useAIHub.js";
+import { useAIHubAuth } from "../../context/useAIHubAuth.js";
 import {
   resolveAffordanceFlags,
   type AIHubAffordanceFlags,
@@ -171,9 +172,13 @@ export function ChatShell(props: ChatShellProps): ReactNode {
     setActiveSession,
     featureToggles,
   } = useAIHub();
+  const { deployment } = useAIHubAuth();
   const texts = useResolvedTexts(props.texts);
   const productName = props.productName ?? "ai-hub";
   const showAgentsPicker = props.showAgentsPicker ?? true;
+  // §7.x agent-picker deployment config: when switching is off the "← Agents"
+  // back link is hidden; a single-agent deployment hides it too (see below).
+  const agentSwitcherEnabled = deployment?.agent_switcher_enabled ?? true;
   const sessionsPanelPosition = props.sessionsPanelPosition ?? "left";
   const sessionsPanelWidthPercent = props.sessionsPanelWidthPercent ?? 25;
 
@@ -214,6 +219,31 @@ export function ChatShell(props: ChatShellProps): ReactNode {
     }
   }, [autoSelectOnlyAgent, agents, setActiveAgent]);
 
+  // Deployment default agent (multi-agent deployments): open it once on first
+  // agents-load instead of showing the picker. A deep-link `initialAgentId`
+  // wins (handled by its own effect above). Guarded by a ref so that, when
+  // switching is enabled, clicking "← Agents" genuinely returns to the picker
+  // rather than snapping straight back to the default.
+  const appliedDefaultAgentRef = useRef(false);
+  useEffect(() => {
+    if (appliedDefaultAgentRef.current) return;
+    if (props.initialAgentId) return;
+    if (agentsLoading || agents.length <= 1) return;
+    appliedDefaultAgentRef.current = true;
+    if (activeAgentId) return;
+    const defaultId = deployment?.default_agent_id ?? null;
+    if (defaultId && agents.some((a) => a.id === defaultId)) {
+      setActiveAgent(defaultId);
+    }
+  }, [
+    agents,
+    agentsLoading,
+    activeAgentId,
+    props.initialAgentId,
+    deployment,
+    setActiveAgent,
+  ]);
+
   const inPicker = showAgentsPicker && !activeAgentId;
 
   const rootClass = props.className
@@ -259,7 +289,9 @@ export function ChatShell(props: ChatShellProps): ReactNode {
               />
             ) : null}
             <MainColumn
-              showBackToAgents={showAgentsPicker}
+              showBackToAgents={
+                showAgentsPicker && agentSwitcherEnabled && agents.length > 1
+              }
               showTurnStatus={flags.turnStatusVisible}
               {...(props.texts !== undefined ? { texts: props.texts } : {})}
               {...(props.customHeaderContent !== undefined

package/src/components/DataClubAIHubAdmin/SettingsPage.tsx

@@ -27,7 +27,10 @@
 import { useEffect, useState, type ReactNode } from "react";
 
 import type { AIHubAdminTexts, AIHubLanguage } from "../../auth/texts.js";
-import type { AdminSettingsView } from "../../client/AIHubClient.js";
+import type {
+  AdminAgentView,
+  AdminSettingsView,
+} from "../../client/AIHubClient.js";
 import { useAIHub } from "../../context/useAIHub.js";
 import { useAIHubAuth } from "../../context/useAIHubAuth.js";
 import {
@@ -188,6 +191,11 @@ export function AdminSettingsPage(props: AdminSettingsPageProps): ReactNode {
             texts={props.texts}
             onSaved={handleSectionSaved}
           />
+          <AgentsSection
+            settings={settings}
+            texts={props.texts}
+            onSaved={handleSectionSaved}
+          />
           <FeatureTogglesSection
             settings={settings}
             texts={props.texts}
@@ -646,6 +654,142 @@ function LanguageSection(props: LanguageSectionProps): ReactNode {
   );
 }
 
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Section: Agents                                                            */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+interface AgentsSectionProps extends SectionProps {
+  onSaved: (next: AdminSettingsView) => void;
+}
+
+function AgentsSection(props: AgentsSectionProps): ReactNode {
+  const { client } = useAIHub();
+  const [defaultAgentId, setDefaultAgentId] = useState<string>(
+    props.settings.agents.default_id ?? "",
+  );
+  const [switcherEnabled, setSwitcherEnabled] = useState(
+    props.settings.agents.switcher_enabled,
+  );
+  // Non-archived agents to populate the default-agent <select>.
+  const [agents, setAgents] = useState<AdminAgentView[] | null>(null);
+  const [saving, setSaving] = useState(false);
+  const [flash, setFlash] = useState<{ tone: "success" | "error"; text: string } | null>(
+    null,
+  );
+
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      try {
+        const rows = await client.listAdminAgents();
+        if (cancelled) return;
+        setAgents(rows.filter((a) => !a.is_archived));
+      } catch {
+        if (!cancelled) setAgents([]);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [client]);
+
+  async function handleSave(event: React.FormEvent): Promise<void> {
+    event.preventDefault();
+    setSaving(true);
+    setFlash(null);
+    try {
+      const next = await client.patchAdminSettings({
+        agents: { defaultId: defaultAgentId, switcherEnabled },
+      });
+      props.onSaved(next);
+      setFlash({ tone: "success", text: props.texts.settingsSaveSuccessFlash });
+    } catch (err) {
+      setFlash({
+        tone: "error",
+        text:
+          err instanceof Error && err.message.length > 0
+            ? err.message
+            : props.texts.settingsSaveGenericError,
+      });
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  return (
+    <section
+      className="data-club-ai-hub-admin__settings-section"
+      data-testid="admin-settings-agents-section"
+    >
+      <h2 className="data-club-ai-hub-admin__settings-section-heading">
+        {props.texts.settingsAgentsSectionHeading}
+      </h2>
+      <form onSubmit={(event) => void handleSave(event)} noValidate>
+        <label
+          className="data-club-ai-hub-admin__form-label"
+          htmlFor="admin-settings-default-agent"
+        >
+          {props.texts.settingsAgentsDefaultLabel}
+        </label>
+        <select
+          id="admin-settings-default-agent"
+          className="data-club-ai-hub-admin__form-input"
+          data-testid="admin-settings-default-agent"
+          value={defaultAgentId}
+          onChange={(event) => setDefaultAgentId(event.target.value)}
+          disabled={saving || agents === null}
+        >
+          <option value="">{props.texts.settingsAgentsDefaultNone}</option>
+          {(agents ?? []).map((agent) => (
+            <option key={agent.id} value={agent.id}>
+              {agent.display_name}
+            </option>
+          ))}
+        </select>
+        <p className="data-club-ai-hub-admin__form-helper">
+          {props.texts.settingsAgentsDefaultHelper}
+        </p>
+        <label className="data-club-ai-hub-admin__checkbox">
+          <input
+            type="checkbox"
+            data-testid="admin-settings-agent-switcher-enabled"
+            checked={switcherEnabled}
+            onChange={(event) => setSwitcherEnabled(event.target.checked)}
+            disabled={saving}
+          />
+          <span>{props.texts.settingsAgentsSwitcherEnabledLabel}</span>
+        </label>
+        <p className="data-club-ai-hub-admin__form-helper">
+          {props.texts.settingsAgentsSwitcherEnabledHelper}
+        </p>
+        {flash !== null ? (
+          <div
+            className={
+              flash.tone === "success"
+                ? "data-club-ai-hub-admin__flash data-club-ai-hub-admin__flash--success"
+                : "data-club-ai-hub-admin__flash data-club-ai-hub-admin__flash--error"
+            }
+            data-testid="admin-settings-agents-flash"
+            role={flash.tone === "error" ? "alert" : "status"}
+          >
+            {flash.text}
+          </div>
+        ) : null}
+        <button
+          type="submit"
+          className="data-club-ai-hub-admin__button data-club-ai-hub-admin__button--primary"
+          data-testid="admin-settings-agents-save"
+          disabled={saving}
+        >
+          {saving
+            ? props.texts.settingsSaveSavingButton
+            : props.texts.settingsSaveAgentsButton}
+        </button>
+      </form>
+    </section>
+  );
+}
+
 /* ────────────────────────────────────────────────────────────────────────── */
 /*  Section: Feature toggles                                                   */
 /* ────────────────────────────────────────────────────────────────────────── */

package/src/components/TurnStatusIndicator/index.tsx

@@ -173,6 +173,7 @@ export function TurnStatusIndicator(
   }, [state.status, state.phase]);
 
   const visual = turnStatusVisual(effective.status, effective.phase);
+  const label = ctx.texts.chat[visual.labelKey];
   const rootClass = props.className
     ? `${cls.root} ${props.className}`
     : cls.root;
@@ -196,7 +197,7 @@ export function TurnStatusIndicator(
     >
       <span className={dotClass} aria-hidden="true" />
       <span className={cls.label} data-testid="turn-status-label">
-        {visual.label}
+        {label}
       </span>
     </div>
   );

package/src/state/affordances.ts

@@ -254,14 +254,36 @@ export function chatAffordances(state: AIHubState): AIHubChatAffordances {
  * `useEffect` + a short timer.
  */
 export interface AIHubTurnStatusVisual {
-  /** Short human-readable label rendered next to the dot. */
+  /**
+   * Short human-readable label rendered next to the dot. **English** — this
+   * is the fallback for consumers that read `turnStatusVisual` directly. The
+   * `<TurnStatusIndicator />` primitive renders the localized
+   * `texts.chat[labelKey]` instead.
+   */
   label: string;
+  /**
+   * The `AIHubChatTexts` key for the localized label. Each value must name an
+   * existing `turnStatus*` key in the chat texts.
+   */
+  labelKey: TurnStatusLabelKey;
   /** 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;
 }
 
+/** The `turnStatus*` keys in `AIHubChatTexts` a status can resolve to. */
+export type TurnStatusLabelKey =
+  | "turnStatusReady"
+  | "turnStatusGenerating"
+  | "turnStatusReasoning"
+  | "turnStatusPreparingTool"
+  | "turnStatusRunningTool"
+  | "turnStatusWaitingRateLimit"
+  | "turnStatusFailed"
+  | "turnStatusCancelled"
+  | "turnStatusDone";
+
 /**
  * Computes the §10.4 turn-status indicator's `(label, dot, pulse)` from
  * a `(status, phase)` pair.
@@ -281,20 +303,22 @@ export function turnStatusVisual(
   if (status === "running") {
     switch (phase) {
       case "model_text":
-        return { label: "Generating…", dot: "running", pulse: true };
+        return { label: "Generating…", labelKey: "turnStatusGenerating", dot: "running", pulse: true };
       case "model_reasoning":
-        return { label: "Reasoning…", dot: "running", pulse: true };
+        return { label: "Reasoning…", labelKey: "turnStatusReasoning", dot: "running", pulse: true };
       case "model_tool_input":
         return {
           label: "Preparing tool call…",
+          labelKey: "turnStatusPreparingTool",
           dot: "running",
           pulse: true,
         };
       case "tool_executing":
-        return { label: "Running tool…", dot: "running", pulse: true };
+        return { label: "Running tool…", labelKey: "turnStatusRunningTool", dot: "running", pulse: true };
       case "waiting_provider":
         return {
           label: "Waiting (rate limit)…",
+          labelKey: "turnStatusWaitingRateLimit",
           dot: "warning",
           pulse: true,
         };
@@ -302,20 +326,20 @@ export function turnStatusVisual(
         // 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 };
+        return { label: "Ready", labelKey: "turnStatusReady", dot: "idle", pulse: false };
       case null:
-        return { label: "Generating…", dot: "running", pulse: true };
+        return { label: "Generating…", labelKey: "turnStatusGenerating", dot: "running", pulse: true };
     }
   }
   if (status === "failed") {
-    return { label: "Failed", dot: "error", pulse: false };
+    return { label: "Failed", labelKey: "turnStatusFailed", dot: "error", pulse: false };
   }
   if (status === "cancelled") {
-    return { label: "Cancelled", dot: "idle", pulse: false };
+    return { label: "Cancelled", labelKey: "turnStatusCancelled", dot: "idle", pulse: false };
   }
   if (status === "done") {
-    return { label: "Done", dot: "idle", pulse: false };
+    return { label: "Done", labelKey: "turnStatusDone", dot: "idle", pulse: false };
   }
   // idle
-  return { label: "Ready", dot: "idle", pulse: false };
+  return { label: "Ready", labelKey: "turnStatusReady", dot: "idle", pulse: false };
 }

package/src/types.ts

@@ -112,6 +112,17 @@ export interface AIHubDeployment {
    * per-device choice.
    */
   user_language_locked: boolean;
+  /**
+   * ai-hub agent id auto-opened on load (skipping the agents picker). `null` =
+   * no default → the picker is shown. Ignored when only one agent exists (that
+   * one always opens). A dangling id falls back to the picker.
+   */
+  default_agent_id: string | null;
+  /**
+   * When `false`, users can't switch agents — the "← Agents" back link is
+   * hidden. (Also hidden whenever only one agent exists, regardless of this.)
+   */
+  agent_switcher_enabled: boolean;
   /**
    * Browser-facing URL of the self-hosted Letta ADE — only present when the
    * caller's role is `power_user` or higher. Absent for `user`-role callers.