@alia.onl/sdk 5.1.0 → 7.0.0

package/src/components/ui/chat-text-input.tsx

@@ -21,6 +21,7 @@ declare module "react-native" {
 }
 
 type ChatTextInputProps = React.ComponentPropsWithoutRef<typeof TextInput> & {
+  unstyled?: boolean;
   noFocus?: boolean;
   onEnterPress?: () => void;
   onCompletionKey?: (key: string) => boolean;
@@ -36,6 +37,7 @@ type ChatTextInputProps = React.ComponentPropsWithoutRef<typeof TextInput> & {
 const ChatTextInput = React.forwardRef<TextInput, ChatTextInputProps>(
   ({
     className,
+    unstyled = false,
     noFocus = false,
     onEnterPress,
     onCompletionKey,
@@ -54,6 +56,28 @@ const ChatTextInput = React.forwardRef<TextInput, ChatTextInputProps>(
     const inputRef = React.useRef<TextInput>(null);
     const wrapperRef = React.useRef<View>(null);
 
+    // react-native-css observes `style` by reference. Memoizing the composed
+    // value prevents its own state update from manufacturing another changed
+    // style prop and recursively re-rendering this TextInput on native.
+    const inputStyle = React.useMemo(() => [
+      style,
+      !fillContainer && props.multiline && !disableAutoHeight && ({
+        minHeight,
+        maxHeight,
+        ...(Platform.OS === 'web'
+          ? { overflow: 'auto' as const, fieldSizing: 'content' }
+          : {}),
+      } as TextStyle & { fieldSizing?: string }),
+      fillContainer && { flex: 1, height: '100%' as const },
+    ], [
+      disableAutoHeight,
+      fillContainer,
+      maxHeight,
+      minHeight,
+      props.multiline,
+      style,
+    ]);
+
     React.useImperativeHandle(ref, () => inputRef.current as TextInput);
 
     // Attach paste event listener (web only)
@@ -135,7 +159,8 @@ const ChatTextInput = React.forwardRef<TextInput, ChatTextInputProps>(
         <TextInput
           ref={inputRef}
           className={cn(
-            "native:text-md native:leading-[1.25] rounded-xl border border-input bg-background px-3.5 text-base text-foreground file:border-0 file:bg-transparent file:font-medium placeholder:text-muted-foreground web:flex web:w-full web:py-2 lg:text-sm",
+            "native:text-md native:leading-[1.25] text-base text-foreground file:border-0 file:bg-transparent file:font-medium placeholder:text-muted-foreground web:flex web:w-full web:py-2 lg:text-sm",
+            !unstyled && "rounded-xl border border-input bg-background px-3.5",
             "web:ring-offset-background web:focus-visible:outline-none web:focus-visible:ring-2 web:focus-visible:ring-ring web:focus-visible:ring-offset-2",
             !fillContainer && !props.multiline && "h-9",
             fillContainer && "h-full",
@@ -147,16 +172,7 @@ const ChatTextInput = React.forwardRef<TextInput, ChatTextInputProps>(
           onKeyPress={handleKeyPress}
           onContentSizeChange={handleContentSizeChange}
           scrollEnabled={fillContainer || props.multiline}
-          style={[
-            style,
-            !fillContainer && props.multiline && !disableAutoHeight && ({
-              minHeight,
-              maxHeight,
-              overflow: 'auto',
-              ...(Platform.OS === 'web' ? { fieldSizing: 'content' } : {}),
-            } as TextStyle & { overflow: 'auto'; fieldSizing?: string }),
-            fillContainer && { flex: 1, height: '100%' },
-          ]}
+          style={inputStyle}
           {...props}
         />
       </View>

package/src/components/ui/prompt-input/textarea.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { View } from "react-native";
+import { StyleSheet, View } from "react-native";
 import { cn } from "../../../lib/utils";
 import { ChatTextInput } from "../chat-text-input";
 import { usePromptInput } from "./context";
@@ -28,6 +28,11 @@ export function PromptInputTextarea({
     handleCompletionKey,
   } = usePromptInput();
 
+  const inputStyle = React.useMemo(
+    () => [style, styles.borderless, isFullscreen && styles.fullscreen],
+    [isFullscreen, style],
+  );
+
   const textInput = (
     <ChatTextInput
       ref={textareaRef}
@@ -42,12 +47,14 @@ export function PromptInputTextarea({
       maxHeight={isFullscreen ? 10000 : maxHeight}
       onImagePaste={onImagePaste}
       fillContainer={isFullscreen}
+      unstyled
       className={cn(
-        "w-full border-0 bg-transparent text-foreground shadow-none",
+        "w-full border-0 bg-transparent text-foreground web:shadow-none",
         isFullscreen ? "px-4 pt-4" : "min-h-[44px] py-3",
         className
       )}
-      style={[style, isFullscreen && { paddingBottom: 100 }]}
+      style={inputStyle}
+      underlineColorAndroid="transparent"
       placeholder={placeholder}
       multiline
       editable={!disabled}
@@ -62,3 +69,12 @@ export function PromptInputTextarea({
 
   return textInput;
 }
+
+const styles = StyleSheet.create({
+  borderless: {
+    borderWidth: 0,
+  },
+  fullscreen: {
+    paddingBottom: 100,
+  },
+});

package/src/hooks/useAliaChat.ts

@@ -2,13 +2,22 @@ import React, { useState, useRef, useCallback, useEffect } from 'react';
 import { useOxy } from '@oxyhq/services';
 import type { ChatMessage, ToolInvocation } from '../types';
 import { getTextFromContent } from '../lib/content-utils';
+import { resolveModelId } from '../lib/catalogue';
+import { PREFERRED_CHAT_MODEL_ID } from '../lib/config';
 
 const API_URL = process.env.EXPO_PUBLIC_ALIA_API_URL ?? 'https://api.alia.onl';
 
 export interface UseAliaChatOptions {
   /** Alia API base URL (default: EXPO_PUBLIC_ALIA_API_URL or https://api.alia.onl) */
   apiUrl?: string;
-  /** Alia model to use (default: 'alia-v1') */
+  /**
+   * Alia model to use.
+   *
+   * Optional, and checked against `GET /catalogue` before a request carries it:
+   * an identifier the server no longer offers is replaced rather than sent, so a
+   * retirement does not turn into a 400 inside a consumer's app. Omitted, the
+   * build's `PREFERRED_CHAT_MODEL_ID` is what gets checked.
+   */
   model?: string;
   /** App context injected as system message so Alia knows which app the user is in */
   clientContext?: string;
@@ -43,7 +52,7 @@ function generateId(): string {
 export function useAliaChat(options: UseAliaChatOptions = {}): UseAliaChatReturn {
   const {
     apiUrl = API_URL,
-    model = 'alia-v1',
+    model = PREFERRED_CHAT_MODEL_ID,
     clientContext,
     accessToken: accessTokenProp,
   } = options;
@@ -214,6 +223,40 @@ export function useAliaChat(options: UseAliaChatOptions = {}): UseAliaChatReturn
       toolInvocationsRef.current = [];
 
       try {
+        /**
+         * This SDK stays on `/v1/chat/completions`, and that is a decision
+         * rather than an oversight — epic #139 workstream 6.
+         *
+         * Every other first-party Alia client moved to the product runtime at
+         * `POST /alia/chat`, which serves the identical handler. This one cannot
+         * follow, for two reasons that are independent of each other.
+         *
+         * **CORS.** `/v1` is the only surface with the public wildcard policy;
+         * everything else falls to the Oxy allowlist
+         * (`packages/api/src/index.ts`). Measured 2026-08-19 against the running
+         * service: an `OPTIONS /alia/chat` preflight from
+         * `https://alia.onl` and `https://console.alia.onl` is answered with a
+         * matching `access-control-allow-origin`, and one from an unlisted
+         * origin comes back with NO such header, so a browser blocks the
+         * request. `OPTIONS /v1/chat/completions` answers `*` for all three.
+         * This package is installed by apps on origins Alia does not enumerate,
+         * so the product surface would refuse them. Widening the allowlist is
+         * not the repair: the narrow policy is what makes `/alia/chat` a product
+         * surface, and it is one of the three recorded differences in
+         * `packages/api/src/routes/__tests__/v1-compatibility-surface.test.ts`.
+         *
+         * **Raw source.** `@alia.onl/sdk` publishes `src/`, so consumers' own
+         * Metro and tsc compile this line and it changes what every installed
+         * copy sends on its NEXT build — not on a release this repository
+         * controls. `docs/migration/compatibility-window.md` records the same
+         * property for the aliases: installed copies resume sending whatever
+         * their source says the moment the service is reachable.
+         *
+         * The consequence is recorded rather than hidden: `/v1/chat/completions`
+         * cannot reach its removal gate while this SDK is a consumer, so
+         * migrating it is a browser-CORS decision on the product surface, taken
+         * with the SDK's consumers enumerated.
+         */
         const response = await fetch(`${apiUrl}/v1/chat/completions`, {
           method: 'POST',
           headers: {
@@ -221,7 +264,11 @@ export function useAliaChat(options: UseAliaChatOptions = {}): UseAliaChatReturn
             Authorization: `Bearer ${token}`,
           },
           body: JSON.stringify({
-            model,
+            // Resolved HERE rather than at render: this is the moment a request
+            // is about to name a model, and it is the only moment at which
+            // sending a retired identifier would actually cost anything. A
+            // catalogue that cannot be read leaves the choice alone.
+            model: await resolveModelId(apiUrl, model, token, PREFERRED_CHAT_MODEL_ID),
             messages: apiMessages,
             stream: true,
           }),

package/src/hooks/useTTS.ts

@@ -11,6 +11,7 @@ import {
 import { useOxy } from '@oxyhq/services';
 import { errorMessage } from '../lib/utils';
 import { create } from 'zustand';
+import { PREFERRED_VOICE_MODEL_ID } from '../lib/config';
 
 const API_URL = process.env.EXPO_PUBLIC_ALIA_API_URL ?? 'https://api.alia.onl';
 
@@ -21,6 +22,15 @@ export interface UseTTSOptions {
   accessToken?: string;
   voice?: 'male' | 'female';
   tone?: 'brief' | 'chill' | 'default';
+  /**
+   * Speech model. Defaults to the build's `PREFERRED_VOICE_MODEL_ID`.
+   *
+   * Not checked against `GET /catalogue`: that surface describes what a chat
+   * picker may offer and its resolver filters to `chat_visible` entries, so
+   * passing a voice identifier through it would substitute a chat model that
+   * cannot speak. See `lib/config.ts`.
+   */
+  model?: string;
 }
 
 // ============== INLINE TTS STORE ==============
@@ -52,6 +62,7 @@ const useTTSStore = create<TTSStore>((set) => ({
 export function useTTS(options: UseTTSOptions = {}) {
   const apiUrl = options.apiUrl || API_URL;
   const voicePref = options.voice ?? 'female';
+  const voiceModel = options.model ?? PREFERRED_VOICE_MODEL_ID;
   const tonePref = options.tone ?? 'default';
 
   const { oxyServices } = useOxy();
@@ -120,7 +131,21 @@ export function useTTS(options: UseTTSOptions = {}) {
     reset();
   }, [reset, releasePlayer]);
 
-  const playFromUrl = useCallback((audioUrl: string, _messageId: string) => {
+  /**
+   * Play a stored clip.
+   *
+   * `onUnplayable` is how a caller says "I can make this again". Stored audio
+   * is not permanent — `tts/` objects age out — and a link to something that is
+   * gone fails in the player, not at the request, so the only place to notice
+   * is here. Without a fallback the failure is reported; with one, the caller
+   * gets to rebuild rather than the person getting an error about a button they
+   * pressed twice.
+   */
+  const playFromUrl = useCallback((
+    audioUrl: string,
+    _messageId: string,
+    onUnplayable?: () => void,
+  ) => {
     releasePlayer();
 
     (async () => {
@@ -132,6 +157,10 @@ export function useTTS(options: UseTTSOptions = {}) {
         player.addListener('playbackStatusUpdate', (status: AudioStatus) => {
           if (status.error) {
             releasePlayer();
+            if (onUnplayable) {
+              onUnplayable();
+              return;
+            }
             setError(status.error);
             return;
           }
@@ -144,6 +173,10 @@ export function useTTS(options: UseTTSOptions = {}) {
         player.play();
         setPlaybackState('playing');
       } catch {
+        if (onUnplayable) {
+          onUnplayable();
+          return;
+        }
         setError('Audio playback not available');
       }
     })();
@@ -183,44 +216,64 @@ export function useTTS(options: UseTTSOptions = {}) {
       setActiveMessage(messageId);
       setPlaybackState('loading');
 
-      // If cached audioUrl exists, play directly
-      if (audioUrl) {
-        playFromUrl(audioUrl, messageId);
-        return;
-      }
+      /**
+       * Ask the server to make it, and play what comes back.
+       *
+       * Hoisted out of the cached branch below so a clip that has aged out of
+       * storage can fall back to it. `playFromUrl` is called WITHOUT a fallback
+       * here: a freshly made clip that will not play is a real failure, and
+       * retrying it would be a loop.
+       */
+      const synthesize = async () => {
+        const token = getToken();
+        if (!token) {
+          throw new Error('Not authenticated');
+        }
 
-      // Call backend TTS API
-      const token = getToken();
-      if (!token) {
-        throw new Error('Not authenticated');
-      }
+        const response = await fetch(`${apiUrl}/v1/audio/speech`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${token}`,
+          },
+          body: JSON.stringify({
+            model: voiceModel,
+            input: text,
+            voice: getTTSVoice(),
+            speed: getTTSSpeed(),
+            conversationId,
+            messageId,
+          }),
+        });
 
-      const response = await fetch(`${apiUrl}/v1/audio/speech`, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          Authorization: `Bearer ${token}`,
-        },
-        body: JSON.stringify({
-          model: 'alia-v1-voice',
-          input: text,
-          voice: getTTSVoice(),
-          speed: getTTSSpeed(),
-          conversationId,
-          messageId,
-        }),
-      });
-
-      if (!response.ok) {
-        if (response.status === 504) {
-          throw new Error('Request timed out — please try again');
+        if (!response.ok) {
+          if (response.status === 504) {
+            throw new Error('Request timed out — please try again');
+          }
+          const errData = await response.json().catch(() => ({}));
+          throw new Error(errData.error?.message || errData.error || 'TTS failed');
         }
-        const errData = await response.json().catch(() => ({}));
-        throw new Error(errData.error?.message || errData.error || 'TTS failed');
+
+        const data = await response.json();
+        playFromUrl(data.audioUrl, messageId);
+      };
+
+      /**
+       * A stored clip plays straight away, and is remade if it has gone.
+       *
+       * The row keeps its key long after a `tts/` object ages out of storage,
+       * so the link is signed, valid, and points at nothing — a failure only
+       * the player ever sees. Remaking it is cheaper than keeping every clip
+       * forever, and the person notices nothing.
+       */
+      if (audioUrl) {
+        playFromUrl(audioUrl, messageId, () => {
+          void synthesize().catch((e: unknown) => setError(errorMessage(e, 'Failed to read aloud')));
+        });
+        return;
       }
 
-      const data = await response.json();
-      playFromUrl(data.audioUrl, messageId);
+      await synthesize();
     } catch (e: unknown) {
       console.error('[TTS] Error:', e);
       setError(errorMessage(e, 'Failed to read aloud'));

package/src/hooks/useVoiceRoom.ts

@@ -20,6 +20,7 @@ import {
 import { useOxy } from '@oxyhq/services';
 import { errorMessage } from '../lib/utils';
 import type { RoomState, AgentState, VoiceMessage, VoiceToolInvocation } from '../types';
+import { PREFERRED_VOICE_MODEL_ID } from '../lib/config';
 
 const API_URL = process.env.EXPO_PUBLIC_ALIA_API_URL ?? 'https://api.alia.onl';
 
@@ -33,6 +34,23 @@ export interface UseVoiceRoomOptions {
   apiUrl?: string;
   voicePreference?: 'male' | 'female';
   accessToken?: string;
+  /**
+   * Voice session model. Defaults to the build's `PREFERRED_VOICE_MODEL_ID`.
+   *
+   * Not checked against `GET /catalogue`, for the reason given in
+   * `lib/config.ts`: the chat resolver filters to `chat_visible` entries and
+   * would substitute something that cannot hold a voice session.
+   */
+  model?: string;
+  /**
+   * The agent this session belongs to, when it is a thread with one.
+   *
+   * Without it the session is ordinary Alia: the API composes the generic
+   * prompt and the identity guard says the model's name, so an agent's voice
+   * answers as Alia. It is the caller's to supply because only the screen knows
+   * whose thread is open.
+   */
+  agentId?: string;
 }
 
 // ============== TITLE TAG UTILITIES ==============
@@ -105,6 +123,8 @@ function micDeviceErrorMessage(name: string): string | null {
 export function useVoiceRoom(options: UseVoiceRoomOptions = {}) {
   const apiUrl = options.apiUrl || API_URL;
   const voicePref = options.voicePreference ?? 'female';
+  const voiceModel = options.model ?? PREFERRED_VOICE_MODEL_ID;
+  const agentId = options.agentId;
 
   const [roomState, setRoomState] = useState<RoomState>('disconnected');
   const [agentState, setAgentState] = useState<AgentState>('idle');
@@ -329,8 +349,12 @@ export function useVoiceRoom(options: UseVoiceRoomOptions = {}) {
           Authorization: `Bearer ${token}`,
         },
         body: JSON.stringify({
-          model: 'alia-v1-voice',
+          model: voiceModel,
           voice: voicePref === 'male' ? 'echo' : 'nova',
+          // Omitted rather than sent as undefined: the API branches on the key
+          // being a string, and a session with no agent must look exactly as it
+          // did before this existed.
+          ...(agentId ? { agentId } : {}),
         }),
       });
 
@@ -408,7 +432,7 @@ export function useVoiceRoom(options: UseVoiceRoomOptions = {}) {
       setRoomState('error');
       cleanup();
     }
-  }, [getToken, cleanup, handleDataMessage, apiUrl, voicePref]);
+  }, [getToken, cleanup, handleDataMessage, apiUrl, voicePref, voiceModel, agentId]);
 
   // ============== DISCONNECT ==============
 

package/src/index.ts

@@ -9,8 +9,8 @@ export { AliaChatScreen } from './components/AliaChatScreen';
 export type { AliaChatScreenProps } from './components/AliaChatScreen';
 
 // ── Chat UI components ──
-export { AliaMark } from './components/AliaMark';
-export type { AliaMarkProps, AliaMarkState } from './components/AliaMark';
+export { IdentityMark } from './components/IdentityMark';
+export type { IdentityMarkProps, IdentityMarkState } from './components/IdentityMark';
 export { ThinkingIndicator } from './components/ThinkingIndicator';
 export { AliaMarkdown } from './components/Markdown';
 export type { AliaMarkdownProps } from './components/Markdown';
@@ -29,6 +29,19 @@ export type { UseTTSOptions } from './hooks/useTTS';
 export { useSpeechToText, useSTTStore } from './hooks/useSpeechToText';
 export type { UseSTTOptions } from './hooks/useSpeechToText';
 
+// ── Model catalogue (GET /catalogue) ──
+// Exported so a consumer building its own picker reads the surface the SDK
+// reads, rather than hardcoding an identifier the way this package used to.
+export {
+  fetchCatalogue,
+  parseCatalogue,
+  resolveSelection,
+  resolveModelId,
+  clearCatalogueCache,
+} from './lib/catalogue';
+export type { CatalogueEntry, CatalogueEntryKind, ModelSelection } from './lib/catalogue';
+export { PREFERRED_CHAT_MODEL_ID, PREFERRED_VOICE_MODEL_ID } from './lib/config';
+
 // ── Types ──
 export type {
   ChatMessage,

package/src/lib/catalogue.ts

@@ -0,0 +1,209 @@
+/**
+ * The model catalogue, as the SDK consumes it (`GET /catalogue`, epic #139
+ * workstream 5).
+ *
+ * Every surface used to hardcode an `alia-*` identifier as its default —
+ * `useAliaChat` sent `alia-v1`, `useTTS` and `useVoiceRoom` sent `alia-v1-voice`
+ * — which meant a retired identifier became a 400 in a consumer's app with
+ * nothing the consumer could do about it, since the string was baked into the
+ * package they installed. This module is how the SDK asks the server what it
+ * offers instead.
+ *
+ * ## Deliberately not React, and deliberately not react-query
+ *
+ * `packages/app` reads the same surface through `useCatalogue`, a react-query
+ * hook. The SDK cannot copy that: it declares `@tanstack/react-query` as a
+ * dependency but imports it in **zero** modules today — measured — so a consumer
+ * mounting `<AliaChatSheet>` is not required to have a `QueryClientProvider`
+ * anywhere above it. Introducing one here would turn "the model default came
+ * from the server" into a breaking change for every consumer, which is a bad
+ * trade for a fallback.
+ *
+ * Resolution therefore happens where it matters — inside `send`, at the moment a
+ * request is about to name a model — rather than at render. A module-level cache
+ * keeps that from becoming a fetch per message.
+ *
+ * ## The parsing rules are the app's, because the contract is the same one
+ *
+ * Two rules, both about not inventing (see `packages/app/lib/hooks/use-catalogue.ts`,
+ * which states them at length):
+ *
+ *  - An entry whose `object` is neither known value is DROPPED. Defaulting it to
+ *    either kind would break ADR 0003 invariant 1 in one direction or the other.
+ *  - A response whose entries all fail to parse THROWS rather than reading as an
+ *    empty catalogue, because "no models" and "we could not read the models"
+ *    look identical to every caller below and one of them means "offer nothing".
+ *
+ * This file is a second implementation of that contract rather than a shared
+ * one, and that is forced rather than chosen: `@alia.onl/sdk` ships as raw
+ * source, so it cannot depend on an unpublished workspace package — a consumer's
+ * Metro would fail to resolve it. The three Node-side clients (Codea, Cowork,
+ * the CLI) share one instead.
+ */
+
+/** A product-owned policy that picks a model per request, or a reference to one named model. */
+export type CatalogueEntryKind = 'routing_profile' | 'model';
+
+export interface CatalogueEntry {
+  readonly id: string;
+  readonly kind: CatalogueEntryKind;
+  readonly displayName: string;
+  readonly description: string;
+  /** Product policy: whether a chat picker surfaces this entry. */
+  readonly chatVisible: boolean;
+  /** The server states this as a claim; an entry that omits it is not called unavailable. */
+  readonly unavailable: boolean;
+}
+
+type JsonObject = Record<string, unknown>;
+
+function asObject(value: unknown): JsonObject | null {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as JsonObject)
+    : null;
+}
+
+function asText(value: unknown): string | null {
+  return typeof value === 'string' ? value : null;
+}
+
+function parseEntry(value: unknown): CatalogueEntry | null {
+  const raw = asObject(value);
+  if (raw === null) return null;
+
+  const id = asText(raw.id);
+  const displayName = asText(raw.display_name);
+  if (id === null || displayName === null) return null;
+
+  if (raw.object !== 'model' && raw.object !== 'routing_profile') return null;
+  const availability = asObject(raw.availability) ?? {};
+
+  return {
+    id,
+    kind: raw.object,
+    displayName,
+    description: asText(raw.description) ?? '',
+    chatVisible: raw.chat_visible === true,
+    unavailable: availability.status === 'unavailable',
+  };
+}
+
+/** Turn a catalogue response into entries, or throw. */
+export function parseCatalogue(payload: unknown): CatalogueEntry[] {
+  const body = asObject(payload);
+  const data = body === null ? null : body.data;
+  if (!Array.isArray(data)) throw new Error('The model catalogue response could not be read.');
+
+  const entries: CatalogueEntry[] = [];
+  for (const value of data) {
+    const entry = parseEntry(value);
+    if (entry !== null) entries.push(entry);
+  }
+  if (data.length > 0 && entries.length === 0) {
+    throw new Error('The model catalogue response could not be read.');
+  }
+  return entries;
+}
+
+export interface ModelSelection {
+  /** What the caller asked for, which is what a picker keeps showing as chosen. */
+  readonly requestedId: string;
+  /** What a request should carry. Differs from `requestedId` only when replaced. */
+  readonly effectiveId: string;
+  /** `replaced` when the requested identifier is not one the catalogue offers. */
+  readonly source: 'requested' | 'replaced';
+}
+
+/**
+ * Resolve a requested identifier against the catalogue.
+ *
+ * The same three deliberate non-behaviours as the app's `resolveSelection`:
+ *
+ *  - **No catalogue — not loaded, or the request failed — leaves the choice
+ *    alone.** Replacing on missing data changes the model under the user on any
+ *    slow cold start, which is the same wrong answer as a retirement.
+ *  - **An entry reported UNAVAILABLE is still honoured.** That is a health
+ *    signal about the models behind an entry and the server already falls back
+ *    among them; picking a different one is a product decision nobody made.
+ *  - **`preferredId` is never trusted.** It is a build-time value, so it is
+ *    checked against the catalogue like any other and falls through when the
+ *    catalogue does not offer it.
+ */
+export function resolveSelection(
+  requestedId: string,
+  entries: readonly CatalogueEntry[] | undefined,
+  preferredId?: string,
+): ModelSelection {
+  if (entries === undefined) {
+    return { requestedId, effectiveId: requestedId, source: 'requested' };
+  }
+
+  const offered = entries.filter((entry) => entry.chatVisible);
+  if (offered.some((entry) => entry.id === requestedId)) {
+    return { requestedId, effectiveId: requestedId, source: 'requested' };
+  }
+
+  const replacement =
+    (preferredId === undefined
+      ? undefined
+      : offered.find((entry) => entry.id === preferredId)) ??
+    offered.find((entry) => !entry.unavailable) ??
+    offered[0];
+  if (replacement === undefined) {
+    return { requestedId, effectiveId: requestedId, source: 'requested' };
+  }
+  return { requestedId, effectiveId: replacement.id, source: 'replaced' };
+}
+
+/**
+ * The catalogue for one API base URL, fetched at most once per URL.
+ *
+ * The promise is cached rather than the result, so concurrent callers share one
+ * request. A REJECTED promise is evicted, because caching a failure would make a
+ * single cold-start network blip permanent for the life of the process.
+ */
+const inFlight = new Map<string, Promise<CatalogueEntry[]>>();
+
+export function fetchCatalogue(apiUrl: string, accessToken?: string): Promise<CatalogueEntry[]> {
+  const cached = inFlight.get(apiUrl);
+  if (cached !== undefined) return cached;
+
+  const request = (async () => {
+    const response = await fetch(`${apiUrl}/catalogue`, {
+      headers: accessToken === undefined ? {} : { Authorization: `Bearer ${accessToken}` },
+    });
+    if (!response.ok) throw new Error(`The model catalogue request failed (${response.status}).`);
+    return parseCatalogue(await response.json());
+  })();
+
+  inFlight.set(apiUrl, request);
+  request.catch(() => inFlight.delete(apiUrl));
+  return request;
+}
+
+/** Drop the cache. Exported for consumers that switch API base URL or sign a different user in. */
+export function clearCatalogueCache(): void {
+  inFlight.clear();
+}
+
+/**
+ * The identifier a request should carry, given what the caller asked for.
+ *
+ * Never throws: a catalogue that cannot be read leaves the requested identifier
+ * alone, which is the same answer as "the catalogue has not loaded yet". A
+ * consumer that wants to KNOW the catalogue is unreadable calls
+ * {@link fetchCatalogue} directly.
+ */
+export async function resolveModelId(
+  apiUrl: string,
+  requestedId: string,
+  accessToken?: string,
+  preferredId?: string,
+): Promise<string> {
+  try {
+    const entries = await fetchCatalogue(apiUrl, accessToken);
+    return resolveSelection(requestedId, entries, preferredId).effectiveId;
+  } catch {
+    return requestedId;
+  }
+}