@alia.onl/sdk 13.2.0 → 15.2.1

package/CHANGELOG.md

@@ -1,5 +1,134 @@
 # @alia.onl/sdk
 
+## 15.2.1
+
+- **The shipped source compiles under `noUnusedLocals`.** The package ships its `.tsx` source, so a
+  consumer's own `tsc` (an app with `noUnusedLocals`/`noUnusedParameters`, such as the Oxy website)
+  type-checks it and failed on eight unused imports in `AliaChatMessageList` (`Pressable` and the
+  reanimated worklet helpers, left behind by the work-log move). They are gone, and the SDK's
+  tsconfig now turns the two flags on so it cannot regress.
+
+## 15.2.0
+
+- **`AliaChatSheetRef.present(turn?)`.** Given a turn (`{ text, images? }`), the conversation opens
+  over the sheet with that message already sent: the "ask Alia about this" button of a profile, a
+  post or a file (the way X opens a conversation with Grok about a post). Without a turn nothing
+  changes. `AliaTurn` is exported.
+
+## 15.0.0
+
+A voice call is a realtime speech-to-speech session through Alia and Kaana, and the composer's
+microphone is transcribed by a Kaana model (Alia ADR 0017). Nothing is recognized by the browser
+or the operating system any more, anywhere in the SDK.
+
+- **Breaking: `useVoiceRoom` is a call over Alia's `GET /v1/voice/session` WebSocket.** It sends
+  the microphone as PCM16 24 kHz frames and plays the answer's PCM16 frames; turn detection and
+  barge-in are the model's, on the server, and tools, memory and the stored transcript are Alia's.
+  New options: `conversationId` (where the transcript is stored; omitted, each call starts a
+  conversation of its own), `agentId`, `voicePreference`, `lang`, `onMessagesSaved` (refresh the
+  thread), `onApprovalRequested`, and the test seams `createAudioEngine` / `openSocket`. Gone:
+  `sendTurn`, `chatModel`, `model`, `endOfUtteranceMs`, `bargeIn`, `synthesisError`, `turnError`,
+  `turnErrorCode`, `warning`, `warningCode`.
+- **Honest states.** `callState` (`VoiceCallState`) is `connecting` → `listening` (only once the
+  session is ready upstream, the microphone delivered a buffer AND Alia acknowledged the first
+  appended audio) → `user-speaking` → `thinking` → `using-tool` → `speaking` (only when the first
+  answer frame is PLAYING) → … → `ended { reason }` or `error { code }`, plus `reconnecting`
+  while a dropped socket resumes within the session's resume window or Alia re-opens the session
+  upstream. `roomState` (now with `reconnecting`) and `agentState` are its coarse projections;
+  `endedReason` says why a call ended — `call-moved-elsewhere` (the person opened a call
+  elsewhere) is a reason, not an error. `endingSoonMs`, `model` (the serving model's name; never
+  the operator) are new.
+- **Barge-in:** when the server hears the person start speaking, the playback queue is flushed and
+  Alia is told how many milliseconds of the answer were actually heard, so the model remembers
+  what was said, not what it generated.
+- **The audio engine** (`createVoiceAudioEngine`, `VoiceAudioEngine`): web is `getUserMedia` with
+  echo cancellation, noise suppression and gain control plus two `AudioWorklet`s (capture to
+  24 kHz PCM16, jitter-buffered playback) in one `AudioContext` — Firefox gets calls. iOS and
+  Android use **`react-native-audio-api`** (new optional peer, `^0.13.6`), capture and playback in
+  one native stack; iOS runs `playAndRecord` in mode `voiceChat` (voice processing). **A host app
+  needs a new native build** with the library's config plugin. On Android the library exposes no
+  `voiceCommunication` input preset yet, so platform echo cancellation is a gate to measure on
+  device (ADR 0017 §4).
+- **Breaking: `useSpeechToText` and `useSTTStore` are replaced by `useDictation` and
+  `useDictationStore`.** Dictation records a clip (`MediaRecorder` on web, Opus/WebM or MP4 on
+  Safari; the `expo-audio` recorder on iOS/Android, m4a sent as `audio/mp4`) and transcribes it with
+  `POST /v1/audio/transcriptions` when the person stops. States: `idle`, `requesting-permission`,
+  `recording` (only once the recorder started; levels are the recorder's), `transcribing`,
+  `error`. The text arrives through `onText`, never partially; a failed transcription keeps the
+  clip for one `retry()`. Clips stop by themselves at five minutes, and `remainingMs` counts the
+  last 30 s. `requestTranscription` and `DictationError` are exported. Dictation works in Firefox
+  now.
+- **`AliaComposer`** dictates with `useDictation`: the transcription is appended to the draft the
+  person has when it arrives, a failure is said with a Retry that re-sends the same clip, and the
+  time left shows over the composer in the last 30 s. New prop `apiUrl`; new label
+  `dictationRemaining`.
+- **Breaking: `VoiceErrorCode` is rewritten.** The recognizer's codes (`speech-*`,
+  `microphone-*`, `recognizer-*`, `no-audio-input`, `turn-failed`, `no-answer`, `not-played`,
+  `synthesis-*`) are gone. It is now Alia's call codes (`not-authenticated`,
+  `credential-not-supported`, `plan-required`, `credits-exhausted`, `agent-unavailable`,
+  `invalid-request`, `resume-unavailable`, `realtime-unavailable`, `realtime-limited`,
+  `realtime-rejected`, `realtime-failed`), the device's (`mic-denied`, `mic-unavailable`,
+  `connection-lost`, `voice-unavailable`) and dictation's (`too-long`,
+  `transcription-unavailable`, `transcription-limited`, `transcription-rejected`,
+  `transcription-failed`). An app with its own translations replaces its keys.
+- **Removed:** `createAliaVoiceTurnSender` and the `VoiceTurn*` types, the device recognizers
+  (`speech-recognition*`, `chooseSpeechRecognizer`), `isInterruption` and the rest of
+  `voice-text`, and the **`expo-speech-recognition` peer** — a host app removes it and its config
+  plugin. Read-aloud (`useTTS`, `/v1/audio/speech`) is unchanged.
+- `VoiceSession` takes `conversationId`, `agentId`, `locale` and `voice`; `VoiceControls` takes
+  `callState` and shows `reconnecting` and `usingTool` (new labels).
+- The `./voice` entry still holds the call: `scripts/check-entry-isolation.mjs` now also proves the
+  root entry never reaches `react-native-audio-api` (nor `expo-speech-recognition`).
+
+## 14.1.0
+
+An "Ask Alia" button can show her live avatar and react to what she is doing.
+
+- **`AliaAvatarIcon`**: a Bloom icon component (`icon={AliaAvatarIcon}`) that draws the live avatar
+  at the icon size under its own `AgentAvatarProvider` on `ALIA_CHARACTER_RUNTIME_URL`, not interactive.
+- **`useAliaActivity()`** returns `'idle' | 'thinking' | 'working' | 'writing'`, the busiest of the
+  turns running in this app (`useAliaChat` now publishes its lifecycle to a shared store) and the
+  server's `alia:activity` events for the signed-in person (one shared `socket.io-client` connection
+  per API origin, none while signed out, closed with the last consumer). New dependency:
+  `socket.io-client`. Needs the API that emits `alia:activity` (an older API simply never sends it:
+  buttons then follow local turns only).
+- The header mark and the buttons read a turn from one function (`turnActivityState`).
+
+## 14.0.0
+
+Read-aloud asks the server every time, and the server answers a clip it already made from storage:
+a message read aloud twice, or a sentence voice mode says again, is synthesized and paid for once.
+
+- **Breaking: `useTTS().readAloud(messageId, text, conversationId?)`** loses its fourth argument,
+  `audioUrl`. A message no longer carries a stored clip of its own: `POST /v1/audio/speech` finds
+  the clip by its text, voice, speed and speech model, for the signed-in person, and answers a
+  stored one at once. There is no "play the stored link, remake it if it has gone" path any more.
+- **Breaking: `ChatMessage.audioUrl` is removed.** `GET /conversations/:id` no longer sends it.
+- `requestSpeechClip`'s `conversationId` + `messageId` now file the clip under that conversation,
+  so deleting or clearing the conversation deletes it. The route still answers 404 for a message
+  the person does not hold, and `requestId` is present only when the clip was made by that request.
+
+A voice call says "Listening…" only while something listens.
+
+- **`useVoiceRoom` stays `connecting` until the recognizer has started** (`roomState` is
+  `'connected'` and `agentState` `'listening'` from the first session's start, not from
+  `connect()`), and a session that does not start within 8 s ends the call as
+  `recognizer-not-started`.
+- **An `aborted` nobody asked for is a failure.** Chrome runs one microphone recognition per
+  browser and a new one aborts the live one, in any tab; the engines now report that as the
+  failure code `interrupted` (only the abort the caller asked for stays silent), and a call cut
+  off three times in a row ends as `recognizer-aborted` instead of restarting forever. The web
+  engine serializes its own sessions, so a page never aborts itself.
+- **The call watches itself while it listens:** voice-level sound for 5 s with no word back ends
+  it as `recognizer-unresponsive`; five sessions in a row that end without listening end it with
+  their error's code; a microphone silent for 10 s raises **`warning` / `warningCode`**
+  (`no-audio-input`) without ending the call. Recognizer errors are logged as a structured
+  `console.warn`, never with the transcript.
+- **`VoiceErrorCode` gains** `recognizer-not-started`, `recognizer-unresponsive`,
+  `recognizer-aborted` and `no-audio-input` (an app with its own translations adds them);
+  `VoiceControls` takes a `notice` it shows in place of "Listening…". Dictation reports an
+  interrupted session as `recognizer-aborted` too.
+
 ## 13.1.1
 
 - **The avatar flights load the runtime too.** 13.1.0 mounted the character runtime provider inside

package/README.md

@@ -53,31 +53,39 @@ Two entry points:
 
 ## Speech
 
-Dictation (`useSpeechToText`) and the voice call (`useVoiceRoom`) recognize
-speech **on the device**: the Web Speech API in browsers that have it (Chromium
-and Safari — not Firefox, where `useSpeechToText().isSupported` is `false`), and
-[`expo-speech-recognition`](https://github.com/jamsch/expo-speech-recognition)
-on iOS and Android. No audio is sent to Alia; whether the platform's recognizer
-uses a network service of its own is the platform's (Chrome's does).
-
-On native, add `expo-speech-recognition` (a peer dependency, like `expo-audio`:
-the root entry's mic button reaches it) and its config plugin to your app, then
-make a new native build:
+Nothing is recognized on the device. Speech is recognized by Kaana, through
+Alia (Alia ADR 0017):
+
+- **Dictation** (`useDictation`, the composer's mic) records a clip — the
+  browser's `MediaRecorder`, or the `expo-audio` recorder on iOS and Android —
+  and, when the person stops, sends it to `POST /v1/audio/transcriptions`.
+  The text arrives once, never partially. Five minutes per clip. Free on every
+  Alia plan.
+- **A voice call** (`useVoiceRoom`, `VoiceSession`) is a realtime
+  speech-to-speech session: a WebSocket to Alia's `GET /v1/voice/session`
+  carrying PCM16 24 kHz audio both ways. Turn detection and barge-in are the
+  model's; tools run in Alia; the transcript is stored in the conversation.
+  Voice calls need a paid Alia plan and use credits per minute.
+
+Audio reaches Alia, Kaana and the model's provider; Alia logs no audio and no
+transcript content.
+
+On iOS and Android a call needs
+[`react-native-audio-api`](https://github.com/software-mansion/react-native-audio-api)
+(an optional peer of `@alia.onl/sdk/voice`; the root entry never reaches it)
+and its config plugin, then a new native build:
 
 ```json
-["expo-speech-recognition", {
-  "microphonePermission": "Allow $(PRODUCT_NAME) to hear what you dictate and say in voice calls.",
-  "speechRecognitionPermission": "Allow $(PRODUCT_NAME) to turn your speech into text."
+["react-native-audio-api", {
+  "iosMicrophonePermission": "Allow $(PRODUCT_NAME) to hear what you dictate and say in voice calls.",
+  "iosBackgroundMode": false,
+  "androidForegroundService": false,
+  "androidPermissions": ["android.permission.RECORD_AUDIO"]
 }]
 ```
 
-A voice call is a turn loop, not a realtime session: it listens until the
-person pauses, sends what they said through the ordinary chat path
-(`POST /v1/chat/completions` with `responseMode: "voice"`, or your own
-`sendTurn`), and speaks the answer sentence by sentence through
-`POST /v1/audio/speech` in the product voice (`male` / `female`). Talking over
-the answer interrupts it. Pass `lang` to both hooks to follow your app's
-language.
+Dictation needs only `expo-audio` (already a peer). Pass `lang` to both hooks
+(`speechLanguage` to `AliaComposer`) to follow your app's language.
 
 ## Use
 
@@ -112,6 +120,30 @@ components render. Those events are the product runtime's, not part of the Oxy
 generic inference contract, and this package is written against them on
 purpose: it is a **product** client.
 
+## An "Ask Alia" button with her live avatar
+
+```tsx
+import { AliaAvatarIcon, useAliaActivity } from '@alia.onl/sdk';
+
+<Button icon={AliaAvatarIcon} onPress={openAlia}>Ask Alia</Button>;
+const state = useAliaActivity(); // 'idle' | 'thinking' | 'working' | 'writing'
+```
+
+`AliaAvatarIcon` is a Bloom icon component (`BloomIconComponent`): pass it as `icon` /
+`leadingIcon`. It draws the live 3D avatar at the icon size under its own
+`AgentAvatarProvider` (`ALIA_CHARACTER_RUNTIME_URL`), and plays what Alia is doing.
+
+`useAliaActivity()` is the busiest of two sources, so a button reacts even with the sheet closed:
+
+- a turn running in this app: every `useAliaChat` publishes its lifecycle to a shared store;
+- her runs for the signed-in person elsewhere (background work, another device): the API's
+  `alia:activity` event on the person's `user:<id>` room, over ONE Socket.IO connection per
+  API origin, opened with the Oxy session's token only while someone is signed in and a
+  consumer is mounted, closed with the last one. A run that goes quiet for 90 s is treated as over.
+
+`socket.io-client` is a regular dependency, not a peer: the SDK owns this connection and an
+app should not have to install a transport to use a button.
+
 ## The composer
 
 The sheet, the screen and the Alia app share one composer, `AliaComposer`: Bloom's

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@alia.onl/sdk",
-  "version": "13.2.0",
-  "description": "Alia AI chat SDK — reusable chat UI, voice, and streaming components for Oxy apps",
+  "version": "15.2.1",
+  "description": "Alia AI chat SDK — reusable chat UI, voice calls, dictation and streaming components for Oxy apps",
   "main": "src/index.ts",
   "react-native": "src/index.ts",
   "source": "src/index.ts",
@@ -32,6 +32,7 @@
   "dependencies": {
     "clsx": "^2.1.1",
     "react-native-markdown-display": "^7.0.2",
+    "socket.io-client": "^4.8.3",
     "tailwind-merge": "^3.7.0",
     "zustand": "^5.0.15"
   },
@@ -57,7 +58,7 @@
     "nativewind": "^5.0.0-preview.3",
     "expo-clipboard": "^57.0.0",
     "expo-file-system": "^57.0.0",
-    "expo-speech-recognition": "^57.1.0"
+    "react-native-audio-api": "^0.13.6"
   },
   "peerDependenciesMeta": {
     "nativewind": {
@@ -65,6 +66,9 @@
     },
     "expo-clipboard": {
       "optional": true
+    },
+    "react-native-audio-api": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -72,6 +76,6 @@
     "react-test-renderer": "19.2.3",
     "typescript": "^5.9.3",
     "vitest": "^4.1.10",
-    "expo-speech-recognition": "~57.1.0"
+    "react-native-audio-api": "0.13.6"
   }
 }

package/src/components/AliaAvatarIcon.tsx

@@ -0,0 +1,30 @@
+import { AgentAvatarProvider } from '@oxy.so/bloom/agent-avatar';
+import type { BloomIconComponent } from '@oxy.so/bloom/icons';
+import { useAliaActivity } from '../hooks/useAliaActivity';
+import { ALIA_CHARACTER_RUNTIME_URL } from '../lib/character-runtime';
+import { AliaAvatar } from './AliaAvatar';
+
+const DEFAULT_SIZE = 20;
+
+/**
+ * Alia's live avatar as a Bloom icon: pass it as `icon` / `leadingIcon` to a Bloom `Button` and
+ * the button shows her, reacting as she thinks, works and writes (`useAliaActivity`) — also while
+ * the chat sheet is closed.
+ *
+ * ```tsx
+ * <Button icon={AliaAvatarIcon} onPress={openAlia}>Ask Alia</Button>
+ * ```
+ *
+ * It mounts its own `AgentAvatarProvider` on `ALIA_CHARACTER_RUNTIME_URL`: an avatar outside the
+ * chat's provider would ask the host for `/bloom-character/runtime.mjs` and get its HTML. The
+ * colour (`fill`) is ignored — the likeness is painted — and it is never interactive, so the
+ * button keeps the press. Reduced motion is Bloom's engine's to honour.
+ */
+export const AliaAvatarIcon: BloomIconComponent = ({ width, height }) => {
+  const state = useAliaActivity();
+  return (
+    <AgentAvatarProvider runtimeUrl={ALIA_CHARACTER_RUNTIME_URL}>
+      <AliaAvatar size={width ?? height ?? DEFAULT_SIZE} state={state} />
+    </AgentAvatarProvider>
+  );
+};

package/src/components/AliaChatContent.tsx

@@ -2,7 +2,7 @@
  * Shared chat content component used by both AliaChatSheet and AliaChatScreen.
  *
  * Owns the text chat; voice is an injected capability (`voiceSession`) so that
- * nothing here reaches `livekit-client` at module-evaluation time. Containers
+ * nothing here reaches the call or its audio engine at module-evaluation time. Containers
  * only handle layout chrome (sheet modal, full-screen SafeAreaView). The
  * breadcrumb header is Bloom's `AiChatContainer`, the one the app's conversation uses.
  */
@@ -10,6 +10,7 @@
 import React, { Suspense, useState, useCallback, useEffect, useMemo, useRef } from 'react';
 import { View, type TextInput } from 'react-native';
 import type { SharedValue } from 'react-native-reanimated';
+import { turnActivityState } from '../lib/turn-state';
 import { useAliaChat, type UseAliaChatOptions } from '../hooks/useAliaChat';
 import { useTTS } from '../hooks/useTTS';
 import { useFocusWhenPresented } from '../hooks/useFocusWhenPresented';
@@ -377,12 +378,7 @@ function AliaChatContentBody({
       if (voiceAgentState === 'thinking') return 'thinking';
       return 'idle';
     }
-    if (!isStreaming) return 'idle';
-    const lastMsg = messages[messages.length - 1];
-    if (lastMsg?.role === 'assistant' && lastMsg.toolInvocations?.some((t) => t.state === 'call'))
-      return 'working';
-    if (lastMsg?.thinking) return 'thinking';
-    return 'writing';
+    return turnActivityState(messages, isStreaming);
   }, [messages, isStreaming, isVoiceActive, voiceAgentState]);
 
   const { user } = useOxy();
@@ -443,6 +439,7 @@ function AliaChatContentBody({
       </Suspense>
     ) : (
       <AliaComposer
+        apiUrl={apiUrl}
         inputRef={composerRef}
         disableKeyboardAvoidance
         onKeyPress={suggestions.onKeyPress}

package/src/components/AliaChatMessageList.tsx

@@ -1,13 +1,6 @@
 import React, { useRef, useEffect, useState, useCallback, useMemo } from 'react';
-import { View, Pressable, Platform } from 'react-native';
-import Animated, {
-  useSharedValue,
-  useAnimatedStyle,
-  withRepeat,
-  withTiming,
-  withSequence,
-  cancelAnimation,
-} from 'react-native-reanimated';
+import { View, Platform } from 'react-native';
+import Animated from 'react-native-reanimated';
 import { Textarea } from '@oxy.so/bloom/textarea';
 import { TaskList } from '@oxy.so/bloom/task-list';
 import { Text } from '@oxy.so/bloom/typography';
@@ -41,7 +34,6 @@ import { AskedQuestions } from './QuestionCard';
 import { askedQuestions, isQuestionInvocation } from '../lib/questions';
 import { extractCitationSources, linkifyCitations } from '../lib/citations';
 import { chatMessageEnter } from '../animations';
-import { getToolLabel, getToolActiveLabel, getResearchActiveLabel } from '../lib/tool-registry';
 import { getTextFromContent, getImagesFromContent } from '../lib/content-utils';
 import type { ChatMessage } from '../types';
 

package/src/components/AliaChatScreen.tsx

@@ -14,7 +14,7 @@
  *
  * Voice is opt-in — pass `voiceSession={VoiceSession}` from
  * `@alia.onl/sdk/voice` to offer calls. Without it the screen is text-only and
- * `livekit-client` never enters the bundle.
+ * `react-native-audio-api` never enters the bundle.
  */
 
 import React, { useCallback } from 'react';

package/src/components/AliaChatSheet.tsx

@@ -49,7 +49,7 @@ export interface AliaChatSheetProps {
   isDarkMode?: boolean;
   /**
    * Voice capability — pass `VoiceSession` from `@alia.onl/sdk/voice` to offer
-   * voice calls. Omitted, the sheet is text-only and `livekit-client` never
+   * voice calls. Omitted, the sheet is text-only and `react-native-audio-api` never
    * enters the bundle.
    */
   voiceSession?: VoiceSessionComponent;
@@ -64,7 +64,12 @@ export interface AliaChatSheetProps {
 }
 
 export interface AliaChatSheetRef {
-  present: () => void;
+  /**
+   * Opens the sheet. Given a `turn`, the conversation opens over it with that message already
+   * sent (an "ask Alia about this" button: a profile, a post, a file); without one, the sheet
+   * opens on its welcome, with the composer focused.
+   */
+  present: (turn?: AliaTurn) => void;
   dismiss: () => void;
 }
 
@@ -137,8 +142,14 @@ export const AliaChatSheet = forwardRef<AliaChatSheetRef, AliaChatSheetProps>(
 
     useImperativeHandle(
       ref,
-      () => ({ present: () => mainRef.current?.present(), dismiss: handleDismiss }),
-      [handleDismiss],
+      () => ({
+        present: (turn) => {
+          mainRef.current?.present();
+          if (turn) startConversation(turn);
+        },
+        dismiss: handleDismiss,
+      }),
+      [handleDismiss, startConversation],
     );
 
     // Closing the main sheet (a drag, backdrop press, Back or Escape) closes what is stacked on it.

package/src/components/AliaComposer.tsx

@@ -20,8 +20,9 @@ import {
   type ComposerPanelPermissionOption,
 } from '@oxy.so/bloom/composer-panel';
 import { toast } from '@oxy.so/bloom/toast';
+import { Text } from '@oxy.so/bloom/typography';
 import { useAttachmentIntake } from '../hooks/useAttachmentIntake';
-import { useSpeechToText } from '../hooks/useSpeechToText';
+import { useDictation } from '../hooks/useDictation';
 import type { Completion } from '../lib/suggestions';
 import { composerTiles, intakeError } from '../lib/attachment-tiles';
 import type { IntakeKind } from '../lib/attachment-intake';
@@ -121,6 +122,8 @@ export interface AliaComposerProps<T extends AliaSuggestion = AliaSuggestion> {
   inputRef?: RefObject<TextInput | null>;
   /** Dictation's language, a BCP-47 tag; omitted, the platform's own. */
   speechLanguage?: string;
+  /** Alia's API, which transcribes dictation; omitted, `EXPO_PUBLIC_ALIA_API_URL` or production. */
+  apiUrl?: string;
   /** Where a refused file or a failed dictation is said; omitted, Bloom's toast. */
   onError?: (message: string) => void;
   /** The composer's copy, over whatever labels are already in reach. */
@@ -153,6 +156,7 @@ function AliaComposerBody<T extends AliaSuggestion>({
   disableKeyboardAvoidance = false,
   inputRef,
   speechLanguage,
+  apiUrl,
   onError,
 }: Omit<AliaComposerProps<T>, 'labels'>) {
   const labels = useLabels();
@@ -221,25 +225,52 @@ function AliaComposerBody<T extends AliaSuggestion>({
     [intake, removeAttachment],
   );
 
-  const stt = useSpeechToText({ lang: speechLanguage });
+  // The draft at the moment the transcription lands, not when the mic was pressed.
+  const draftRef = useRef(value);
+  draftRef.current = value;
+  const insertDictation = useCallback(
+    (text: string) => {
+      const draft = draftRef.current;
+      onValueChange(draft === '' ? text : `${draft} ${text}`);
+    },
+    [onValueChange],
+  );
+  const dictation = useDictation({
+    lang: speechLanguage,
+    ...(apiUrl === undefined ? {} : { apiUrl }),
+    onText: insertDictation,
+  });
   // Said once per failure: a host re-rendering with new labels is not a new failure.
-  const sayVoiceError = useRef((code: VoiceErrorCode) => report(labels.voiceError(code)));
-  sayVoiceError.current = (code) => report(labels.voiceError(code));
+  const sayVoiceError = useRef<(code: VoiceErrorCode, retry: (() => void) | null) => void>(
+    () => undefined,
+  );
+  sayVoiceError.current = (code, retry) => {
+    const message = labels.voiceError(code);
+    if (onError || retry === null) report(message);
+    else toast.error(message, { action: { label: labels.composerRetry, onClick: retry } });
+  };
+  const {
+    errorCode: dictationError,
+    canRetry: dictationCanRetry,
+    retry: retryDictation,
+  } = dictation;
   useEffect(() => {
-    if (stt.errorCode !== null) sayVoiceError.current(stt.errorCode);
-  }, [stt.errorCode]);
+    if (dictationError !== null)
+      sayVoiceError.current(dictationError, dictationCanRetry ? () => void retryDictation() : null);
+  }, [dictationError, dictationCanRetry, retryDictation]);
 
   const handleListeningChange = useCallback(
     async (next: boolean) => {
       if (next) {
-        if (!disabled && !busy && !stt.isTranscribing) stt.startRecording();
+        if (!disabled && !busy && !dictation.isTranscribing) void dictation.start();
         return;
       }
-      const text = await stt.stopAndTranscribe();
-      if (text !== null) onValueChange(value === '' ? text : `${value} ${text}`);
+      await dictation.stop();
     },
-    [disabled, busy, stt, value, onValueChange],
+    [disabled, busy, dictation],
   );
+  const remainingSeconds =
+    dictation.remainingMs === null ? null : Math.ceil(dictation.remainingMs / 1000);
 
   const hasContent = value.trim() !== '' || attachments.length > 0;
   const panelLabels = useMemo(
@@ -262,6 +293,15 @@ function AliaComposerBody<T extends AliaSuggestion>({
     // The transcript's column (Bloom's `AgentChat`: 768 at most, centred), so
     // the composer and the conversation share one edge.
     <View id={hostId} className="w-full max-w-[768px] self-center">
+      {remainingSeconds !== null ? (
+        <Text
+          className="mb-1 self-center text-sm text-text-secondary"
+          accessibilityLiveRegion="polite"
+          aria-live="polite"
+        >
+          {labels.dictationRemaining(remainingSeconds)}
+        </Text>
+      ) : null}
       <ComposerPanel
         value={value}
         onValueChange={onValueChange}
@@ -276,7 +316,13 @@ function AliaComposerBody<T extends AliaSuggestion>({
         permissions={modes ?? NO_MODES}
         permission={mode}
         onPermissionChange={onModeChange}
-        voiceState={stt.isTranscribing ? 'transcribing' : stt.isRecording ? 'recording' : 'idle'}
+        voiceState={
+          dictation.isTranscribing
+            ? 'transcribing'
+            : dictation.isRecording || dictation.state === 'requesting-permission'
+              ? 'recording'
+              : 'idle'
+        }
         onVoiceStateChange={(next) => void handleListeningChange(next === 'recording')}
         attachments={tiles}
         onRemoveAttachment={removeTile}

package/src/components/voice/VoiceControls.tsx

@@ -8,15 +8,17 @@ import { Loading } from '@oxy.so/bloom/loading';
 import { Text } from '@oxy.so/bloom/typography';
 import { VoiceControls as BloomVoiceControls, type VoiceState } from '@oxy.so/bloom/voice';
 import { View } from 'react-native';
-import type { RoomState, AgentState } from '../../types';
+import type { RoomState, AgentState, VoiceCallState } from '../../types';
 
 /** Every word the bar shows or announces. An app in another language passes its own. */
 export interface VoiceControlsLabels {
   connecting: string;
+  reconnecting: string;
   connected: string;
   listening: string;
   muted: string;
   thinking: string;
+  usingTool: string;
   speaking: string;
   mute: string;
   unmute: string;
@@ -25,10 +27,12 @@ export interface VoiceControlsLabels {
 
 export const VOICE_CONTROLS_LABELS: VoiceControlsLabels = {
   connecting: 'Connecting...',
+  reconnecting: 'Reconnecting...',
   connected: 'Connected',
   listening: 'Listening...',
   muted: 'Muted',
   thinking: 'Thinking...',
+  usingTool: 'Working on it...',
   speaking: 'Speaking...',
   mute: 'Mute',
   unmute: 'Unmute',
@@ -41,6 +45,16 @@ export interface VoiceControlsProps {
   isMuted: boolean;
   onToggleMute: () => void;
   onEnd: () => void;
+  /**
+   * Something the person should know while the call listens — e.g. that the
+   * call is about to reach its time limit. Shown in place of "Listening…".
+   */
+  notice?: string | null;
+  /**
+   * The call's full state, when the host has it: a tool running reads as such
+   * rather than as "Thinking…".
+   */
+  callState?: VoiceCallState;
   /** Overrides for any of {@link VOICE_CONTROLS_LABELS}. */
   labels?: Partial<VoiceControlsLabels>;
 }
@@ -49,11 +63,15 @@ function getStatusText(
   roomState: RoomState,
   agentState: AgentState,
   isMuted: boolean,
+  notice: string | null,
   labels: VoiceControlsLabels,
+  callState: VoiceCallState | undefined,
 ): string {
   if (roomState === 'connecting') return labels.connecting;
+  if (roomState === 'reconnecting') return labels.reconnecting;
   if (roomState === 'connected') {
-    if (agentState === 'listening') return isMuted ? labels.muted : labels.listening;
+    if (agentState === 'listening') return isMuted ? labels.muted : (notice ?? labels.listening);
+    if (callState?.kind === 'using-tool') return labels.usingTool;
     if (agentState === 'thinking') return labels.thinking;
     if (agentState === 'speaking') return labels.speaking;
     return labels.connected;
@@ -74,10 +92,12 @@ export function VoiceControls({
   isMuted,
   onToggleMute,
   onEnd,
+  notice = null,
+  callState,
   labels: labelOverrides,
 }: VoiceControlsProps) {
   const labels = { ...VOICE_CONTROLS_LABELS, ...labelOverrides };
-  const statusText = getStatusText(roomState, agentState, isMuted, labels);
+  const statusText = getStatusText(roomState, agentState, isMuted, notice, labels, callState);
 
   return (
     <View className="items-center gap-4 pb-6 pt-4">
@@ -102,7 +122,11 @@ export function VoiceControls({
         />
       ) : null}
 
-      {roomState === 'connecting' ? <Loading accessibilityLabel={labels.connecting} /> : null}
+      {roomState === 'connecting' || roomState === 'reconnecting' ? (
+        <Loading
+          accessibilityLabel={roomState === 'connecting' ? labels.connecting : labels.reconnecting}
+        />
+      ) : null}
     </View>
   );
 }