@alia.onl/sdk 15.8.0 → 19.1.0

package/src/hooks/useVoiceLauncher.ts

@@ -0,0 +1,180 @@
+/**
+ * The host side of a voice call, shared by every surface that offers one.
+ *
+ * It owns whether a call is open, the state it reports back (for the ambient
+ * wave, the sound effects and the transcript), the gate before one opens (plan,
+ * credits, sign-in: the host answers, the SDK tells the person), and the end of
+ * a call that is no longer the screen's — another screen on show, another
+ * conversation, another account. `sessionProps` is everything `VoiceSession`
+ * needs; the sheet, `AliaChatScreen` and the Alia app all spread it.
+ *
+ * Nothing here imports the call or its audio engine.
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { toast } from '@oxy.so/bloom/toast';
+import { useLabels, type VoiceBlockReason } from '../lib/labels';
+import { isRequestFor, useVoiceCallRequests } from '../lib/voice-call-request';
+import type { VoiceNotice, VoiceSessionProps, VoiceSessionState } from '../types';
+
+export interface UseVoiceLauncherOptions {
+  /** Alia API base URL. */
+  apiUrl?: string;
+  /** The conversation open on this screen, which is where the call lives. */
+  conversationId?: string;
+  /**
+   * Called after the gate, when no conversation is open: creates (and shows) the one the call
+   * will live in and returns its id, or `undefined` when it could not be made (the call then
+   * does not open). Every call has a conversation, so its transcript has a home. The call opens
+   * on the screen that shows that conversation: this one, or the one the host navigates to.
+   */
+  resolveConversation?: () => Promise<string | undefined>;
+  /** Whose call it would be. A live call ends when the account, or the open conversation, changes. */
+  accountId?: string | null;
+  /** The agent the call talks to; omitted, Alia. */
+  agentId?: string;
+  /** Language spoken (BCP-47); omitted, the platform's. */
+  locale?: string;
+  /** Which of the product's two voices answers. */
+  voice?: 'male' | 'female';
+  /** Alia stored messages of the call in the conversation: refresh the thread. */
+  onMessagesSaved?: VoiceSessionProps['onMessagesSaved'];
+  /**
+   * The gate before a call opens: why it may not (no account, no plan, no credits), or `null`.
+   * The person is told (`labels.voiceBlocked`); `onVoiceBlocked` adds what only the host can do.
+   */
+  canStartVoice?: () => VoiceBlockReason | null;
+  /** The call was not opened for `reason`: sign the person in, open the plans… */
+  onVoiceBlocked?: (reason: VoiceBlockReason) => void;
+  /** Where the call's notices go; omitted, Bloom's toast. */
+  onNotice?: (notice: VoiceNotice) => void;
+  /** A call is over, however it ended: refresh credits, the thread… */
+  onCallEnded?: () => void;
+  /** Whether the screen holding the call is the one on show. A live call ends when it is not. */
+  isFocused?: boolean;
+}
+
+export interface VoiceLauncher {
+  /** A call is open (or being opened). */
+  isActive: boolean;
+  /** What the call reports back; `null` until it is under way. */
+  state: VoiceSessionState | null;
+  /** Open a call, after the gate. Does nothing while one is open or the screen is not on show. */
+  start: () => Promise<void>;
+  /** End the call. */
+  end: () => void;
+  /** Spread onto `VoiceSession` (or `AliaVoiceCall`). */
+  sessionProps: VoiceSessionProps;
+}
+
+/** Bloom's toast, by kind: the default home of a call's notices. */
+export function toastNotice({ kind, text }: VoiceNotice): void {
+  if (kind === 'error') toast.error(text);
+  else if (kind === 'warning') toast.warning(text);
+  else toast.info(text);
+}
+
+export function useVoiceLauncher(options: UseVoiceLauncherOptions = {}): VoiceLauncher {
+  const labels = useLabels();
+  const {
+    apiUrl,
+    conversationId,
+    resolveConversation,
+    accountId = null,
+    agentId,
+    locale,
+    voice,
+    onMessagesSaved,
+    canStartVoice,
+    onVoiceBlocked,
+    onNotice,
+    onCallEnded,
+    isFocused = true,
+  } = options;
+  const [isActive, setIsActive] = useState(false);
+  const [state, setState] = useState<VoiceSessionState | null>(null);
+  const latest = useRef({
+    canStartVoice,
+    onVoiceBlocked,
+    onNotice,
+    onCallEnded,
+    resolveConversation,
+    labels,
+  });
+  latest.current = {
+    canStartVoice,
+    onVoiceBlocked,
+    onNotice,
+    onCallEnded,
+    resolveConversation,
+    labels,
+  };
+
+  const notify = useCallback((notice: VoiceNotice) => {
+    (latest.current.onNotice ?? toastNotice)(notice);
+  }, []);
+
+  const end = useCallback(() => {
+    setIsActive(false);
+    setState(null);
+    latest.current.onCallEnded?.();
+  }, []);
+
+  const start = useCallback(async () => {
+    if (isActive || !isFocused) return;
+    const reason = latest.current.canStartVoice?.() ?? null;
+    if (reason !== null) {
+      notify({
+        kind: reason === 'credits-exhausted' ? 'error' : 'info',
+        text: latest.current.labels.voiceBlocked(reason),
+      });
+      latest.current.onVoiceBlocked?.(reason);
+      return;
+    }
+    // The gate first: a call that may not open must not leave an empty conversation behind.
+    const home = conversationId ?? (await latest.current.resolveConversation?.());
+    if (home === undefined) return;
+    // The call opens where its conversation is shown (see `useVoiceCallRequests`): here, at once,
+    // when it already is; wherever the host takes the new conversation, when it was just made.
+    useVoiceCallRequests.getState().ask(home, accountId);
+  }, [isActive, isFocused, conversationId, accountId, notify]);
+
+  const request = useVoiceCallRequests((store) => store.request);
+  useEffect(() => {
+    if (isActive || !isFocused || !isRequestFor(request, conversationId, accountId)) return;
+    useVoiceCallRequests.getState().clear();
+    setIsActive(true);
+  }, [request, isActive, isFocused, conversationId, accountId]);
+
+  // A call belongs to one account and one conversation, on the screen that shows it: it ends when
+  // the screen goes out of focus, the account changes, or the screen moves to another conversation.
+  const openedIn = useRef<{ conversationId: string | undefined; accountId: string | null }>(
+    undefined,
+  );
+  useEffect(() => {
+    if (!isActive) {
+      openedIn.current = undefined;
+      return;
+    }
+    openedIn.current ??= { conversationId, accountId };
+    const call = openedIn.current;
+    if (!isFocused || call.accountId !== accountId || call.conversationId !== conversationId) end();
+  }, [isActive, isFocused, accountId, conversationId, end]);
+
+  const sessionProps = useMemo<VoiceSessionProps>(
+    () => ({
+      ...(apiUrl === undefined ? {} : { apiUrl }),
+      ...(conversationId === undefined ? {} : { conversationId }),
+      ...(agentId === undefined ? {} : { agentId }),
+      ...(locale === undefined ? {} : { locale }),
+      ...(voice === undefined ? {} : { voice }),
+      ...(onMessagesSaved === undefined ? {} : { onMessagesSaved }),
+      onNotice: notify,
+      onStateChange: setState,
+      onEnd: end,
+    }),
+    [apiUrl, conversationId, agentId, locale, voice, onMessagesSaved, notify, end],
+  );
+
+  return { isActive, state, start, end, sessionProps };
+}

package/src/hooks/useVoiceRoom.ts

@@ -25,6 +25,7 @@ import { VoiceCall, type VoiceCallSnapshot, type VoiceSocketFactory } from '../l
 import { VoiceLevelChannel, type VoiceLevelSource } from '../lib/voice-levels';
 import type { ProductVoice, VoiceCloseReason } from '../lib/voice-protocol';
 import { ALIA_API_URL } from '../lib/origins';
+import { useAppAssertionToken } from '../runtime/app-assertion';
 
 export interface UseVoiceRoomOptions {
   apiUrl?: string;
@@ -43,8 +44,6 @@ export interface UseVoiceRoomOptions {
   lang?: string;
   /** Alia stored messages of the call: refresh the thread. */
   onMessagesSaved?: (conversationId: string, messageIds: readonly string[]) => void;
-  /** A tool filed an action for the person's OK; its card is in the conversation. */
-  onApprovalRequested?: (toolName: string) => void;
   /** Test seams: the device's audio and the socket. */
   createAudioEngine?: () => VoiceAudioEngine;
   openSocket?: VoiceSocketFactory;
@@ -101,6 +100,7 @@ export function agentStateOf(state: VoiceCallState): AgentState {
 
 export function useVoiceRoom(options: UseVoiceRoomOptions = {}) {
   const { oxyServices } = useOxy();
+  const getAppAssertion = useAppAssertionToken();
   const levels = useMemo(() => new VoiceLevelChannel(), []);
   const [snapshot, setSnapshot] = useState<VoiceCallSnapshot>(IDLE);
   const callRef = useRef<VoiceCall | null>(null);
@@ -121,6 +121,7 @@ export function useVoiceRoom(options: UseVoiceRoomOptions = {}) {
     const call = new VoiceCall({
       apiUrl: current.apiUrl || ALIA_API_URL,
       getToken,
+      getAppAssertion,
       conversationId: current.conversationId ?? newConversationId(),
       ...(current.agentId === undefined ? {} : { agentId: current.agentId }),
       voice: current.voicePreference ?? 'female',
@@ -133,11 +134,10 @@ export function useVoiceRoom(options: UseVoiceRoomOptions = {}) {
       },
       onMessagesSaved: (conversationId, ids) =>
         optionsRef.current.onMessagesSaved?.(conversationId, ids),
-      onApprovalRequested: (toolName) => optionsRef.current.onApprovalRequested?.(toolName),
     });
     callRef.current = call;
     await call.start();
-  }, [getToken, levels]);
+  }, [getToken, getAppAssertion, levels]);
 
   /** Hang up and forget the call: the room is back to `disconnected`. */
   const disconnect = useCallback(() => {

package/src/index.ts

@@ -3,17 +3,39 @@
 // Reusable chat UI, voice, and streaming components for Oxy apps
 
 // ── Main components ──
-export type { AliaChatAgent, AliaChatState } from './components/AliaChatContent';
+export { AliaChatContent } from './components/AliaChatContent';
+export type {
+  AliaChatAgentRef,
+  AliaChatChrome,
+  AliaChatContentProps,
+  AliaChatState,
+} from './components/AliaChatContent';
+export { AliaParticipants, joinFlights, useParticipants } from './components/AliaParticipants';
+export type { AliaParticipantsProps, UseParticipantsOptions } from './components/AliaParticipants';
+export { AliaParticipantsHeader } from './components/AliaParticipantsHeader';
+export type { AliaParticipantsHeaderProps } from './components/AliaParticipantsHeader';
+export { ALIA_LEAD, leadOf } from './lib/participants';
+export type { AliaChatParticipants, AliaLead, AliaParticipant } from './lib/participants';
+export { ANCHORS, leadToProfile } from './lib/flights';
+export { parseCatalogueTool, toolRendererKey } from './lib/tool-renderers';
+export type { AliaToolRenderers, AliaToolResult } from './lib/tool-renderers';
+export { AliaAskProvider, useAskAgent } from './components/AliaAskProvider';
+export type { AliaAsk, AliaAskAgents, AliaAskProviderProps } from './components/AliaAskProvider';
+export { AliaSharedConversation } from './components/AliaSharedConversation';
+export type { AliaSharedConversationProps } from './components/AliaSharedConversation';
+export type { AliaAddMenu } from './lib/add-menu';
+export type { AliaVoiceOptions } from './hooks/useChatVoice';
 export { AliaChatSheet } from './components/AliaChatSheet';
 export type { AliaChatSheetProps, AliaChatSheetRef } from './components/AliaChatSheet';
-export type { AliaTurn } from './components/AliaChatContent';
+export type { AliaTurn } from './hooks/useChatComposer';
 export { AliaChatScreen } from './components/AliaChatScreen';
 export type { AliaChatScreenProps } from './components/AliaChatScreen';
 
 // ── Chat UI components ──
 export { ALIA_CHARACTER_RUNTIME_URL } from './lib/character-runtime';
 export { DEFAULT_LABELS } from './lib/labels';
-export type { AliaChatLabels } from './lib/labels';
+export { AliaChatLabelsProvider, useLabels } from './lib/labels';
+export type { AliaChatLabels, VoiceBlockReason } from './lib/labels';
 export { VoiceModeIcon } from './components/VoiceModeIcon';
 export { AmbientField, PARALLAX_DURATION, PARALLAX_EASE } from './components/AmbientField';
 export type { AmbientFieldProps } from './components/AmbientField';
@@ -27,6 +49,16 @@ export { IdentityMark } from './components/IdentityMark';
 export type { IdentityMarkProps, IdentityMarkState } from './components/IdentityMark';
 export { AliaMarkdown } from './components/Markdown';
 export type { AliaMarkdownProps, RenderCodeBlock } from './components/Markdown';
+export { ReplyMarkdown } from './components/ReplyMarkdown';
+export { AliaThread } from './components/thread/AliaThread';
+export type { AliaThreadProps, NewConversationOfferProps } from './components/thread/AliaThread';
+export { ThoughtPanel } from './components/thought/ThoughtPanel';
+export type { ThoughtPanelProps } from './components/thought/ThoughtPanel';
+export type { OutputActions } from './components/thought/FilesAndSources';
+export { CanvasComponent } from './components/canvas/CanvasComponent';
+export { restoreOpenerFocus } from './lib/focus-return';
+export { buildPowerLevelOptions, POWER_LEVEL_ICONS } from './lib/power-level-options';
+export type { DeviceModel } from './lib/power-level-options';
 export { AliaWelcomeMessage } from './components/AliaWelcomeMessage';
 export { PlanPreviewCard } from './components/PlanPreviewCard';
 export { AskedQuestions, QuestionCard } from './components/QuestionCard';
@@ -49,11 +81,8 @@ export {
 } from './lib/questions';
 export type { AskedOption, AskedQuestion, QuestionAnswer } from './lib/questions';
 
-// ── Chat hook ──
-export { useAliaChat } from './hooks/useAliaChat';
-export type { UseAliaChatOptions, UseAliaChatReturn } from './hooks/useAliaChat';
-export { AliaChatStreamError } from './lib/chat-stream';
-export type { AliaChatFailure } from './lib/chat-stream';
+// ── Conversation runtime: the one data layer under the sheet, the screen and the Alia app ──
+export * from './runtime';
 
 // ── Read aloud and dictation (no call, no audio engine) ──
 export { useTTS } from './hooks/useTTS';
@@ -67,36 +96,21 @@ export type { VoiceErrorCode } from './lib/speech-messages';
 export { SpeechClipError } from './lib/speech-synthesis';
 export type { SpeechClipErrorCode } from './lib/speech-synthesis';
 
-// ── Model catalogue (GET /catalogue) ──
-// Exported so a consumer building its own picker reads the real models the
-// server offers; the SDK itself ships no model identifier.
-export {
-  fetchCatalogue,
-  parseCatalogue,
-  resolveSelection,
-  resolveModelId,
-  clearCatalogueCache,
-} from './lib/catalogue';
-export type { Catalogue, CatalogueEntry, ModelSelection, ReasoningEffort } from './lib/catalogue';
-
 // ── Types ──
 export type {
-  ChatMessage,
-  ToolInvocation,
   AliaAttachment,
   AliaSuggestion,
   ResearchProgress,
   ResearchSource,
-  PendingPlan,
+  MessagePlan,
   PlanStep,
 } from './types';
 
-// ── Voice capability contract (the implementation lives in `./voice`) ──
-export type {
-  VoiceSessionComponent,
-  VoiceSessionProps,
-  VoiceSessionState,
-} from './types';
+// ── Voice: part of the conversation screen; the host brings callbacks (see `AliaVoiceOptions`) ──
+export type { VoiceNotice, VoiceSessionProps, VoiceSessionState } from './types';
+export { AliaVoiceCall } from './components/voice/AliaVoiceCall';
+export { useVoiceLauncher, toastNotice } from './hooks/useVoiceLauncher';
+export type { UseVoiceLauncherOptions, VoiceLauncher } from './hooks/useVoiceLauncher';
 
 // ── UI Primitives (NativeWind) ──
 export { cn, formatFileSize } from './lib/utils';

package/src/lib/activity-store.ts

@@ -6,7 +6,7 @@ type Sources = Readonly<Record<string, AliaAvatarState>>;
 /**
  * What Alia is doing, from every place that can know. Two sources feed it and neither owns it:
  *
- * - `local`: the turns running in THIS app, one entry per `useAliaChat` instance (the sheet);
+ * - `local`: the turns running in THIS app, one entry per `useConversationThread` instance;
  * - `remote`: runs the server reports for the person, one entry per agent session, so a button
  *   reacts to work that is not in any open chat.
  *

package/src/lib/add-menu.ts

@@ -0,0 +1,7 @@
+import type { ComposerPanelAddMenuGroup } from '@oxy.so/bloom/composer-panel';
+
+/** The rows of the composer's add menu, and what pressing one does. */
+export interface AliaAddMenu {
+  groups: readonly ComposerPanelAddMenuGroup[];
+  onSelect: (rowId: string) => void;
+}

package/src/lib/call-thread.ts

@@ -0,0 +1,33 @@
+/**
+ * What the thread shows while a call is open: the text messages it held when
+ * the call started, then the call's messages.
+ *
+ * A call message the server has stored is shown AS STORED — the copy a reload
+ * or a resume shows, with its tools' arguments and results, which the call's
+ * socket never carries. Same id either way (the call names every message by the
+ * id it is stored under), so swapping one for the other never adds a message.
+ */
+
+import type { Message } from '../runtime/types';
+import type { VoiceMessage } from '../types';
+
+export function callThread(
+  before: readonly Message[],
+  call: readonly VoiceMessage[],
+  stored: readonly Message[] | undefined,
+): Message[] {
+  const storedById = new Map((stored ?? []).map((message) => [message.id, message]));
+  return [...before, ...call.map((message) => storedById.get(message.id) ?? fromCall(message))];
+}
+
+function fromCall(message: VoiceMessage): Message {
+  return {
+    id: message.id,
+    role: message.role,
+    content: message.content,
+    toolInvocations: message.toolInvocations,
+    createdAt: new Date(message.timestamp).toISOString(),
+    source: 'voice' as const,
+    speaker: message.speaker,
+  };
+}

package/src/lib/citations.ts

@@ -1,4 +1,4 @@
-import type { ToolInvocation } from '../types';
+import type { ToolInvocation } from '../runtime/types';
 import { domainOf } from './domain';
 
 export interface CitationSource {
@@ -87,7 +87,7 @@ export function normalizeCitationMarkers(text: string, knownIds?: Iterable<numbe
 
 /**
  * The accessible name of one citation: what a screen reader says for the
- * link, and what `CustomMarkdown` puts in the link's title.
+ * link, and what `ReplyMarkdown` puts in the link's title.
  */
 export function citationLabel(source: CitationSource): string {
   return `Source ${source.id}: ${source.title}`;
@@ -113,3 +113,80 @@ export function linkifyCitations(text: string, sources: CitationSource[]): strin
     return `[${n}](${source.url} "${title}")`;
   });
 }
+
+/** One entry of a rendered references section. */
+export interface ReferenceEntry {
+  id: number;
+  title: string;
+  url: string;
+  domain: string;
+}
+
+/**
+ * Where the references section starts: the API writes `## References` after a
+ * rule; the heading is matched loosely so an older answer, or one
+ * written in Spanish by the model itself, splits the same way.
+ */
+const REFERENCES_HEADING_RE =
+  /(?:^|\n)(?:---\s*\n+)?#{1,3}\s*(?:References|Referencias|Sources|Fuentes)\s*:?\s*(?:\n|$)/i;
+
+/** `[n] [Title](url)` (new) or `[n] Title` + a URL line (legacy). */
+const REFERENCE_LINE_RE = /^\s*\[(\d{1,3})\]\s*(.*)$/;
+// The title may carry escaped brackets (`React \[Wikipedia\]`), which the
+// API writes for a title that contains them.
+const MARKDOWN_LINK_RE = /^\[((?:\\.|[^\]\\])*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)\s*$/;
+const URL_RE = /https?:\/\/[^\s)]+/;
+
+/**
+ * Split an answer into its body and the entries of its references section.
+ *
+ * `references` is `null` when the section is absent or none of its lines
+ * parse, in which case the caller renders the whole text as Markdown and
+ * nothing is lost. Known sources fill in a title or URL a legacy line lacks.
+ */
+export function splitReferences(
+  text: string,
+  sources: CitationSource[] = [],
+): { body: string; references: ReferenceEntry[] | null } {
+  const match = REFERENCES_HEADING_RE.exec(text);
+  if (!match) return { body: text, references: null };
+
+  const body = text.slice(0, match.index).replace(/\s+$/, '');
+  const section = text.slice(match.index + match[0].length);
+  const byId = new Map(sources.map((s) => [s.id, s]));
+
+  const entries: ReferenceEntry[] = [];
+  let current: { id: number; rest: string } | null = null;
+  const flush = () => {
+    if (!current) return;
+    const known = byId.get(current.id);
+    const rest = current.rest.trim();
+    const link = MARKDOWN_LINK_RE.exec(rest);
+    let url = link ? link[2] : (URL_RE.exec(rest)?.[0] ?? known?.url ?? '');
+    let title = link ? link[1] : rest.replace(URL_RE, '').replace(/\s+/g, ' ').trim();
+    if (!url && known) url = known.url;
+    if (!title) title = known?.title ?? (url ? domainOf(url, { stripWww: true }) : '');
+    if (url)
+      entries.push({
+        id: current.id,
+        title: title.replace(/\\([[\]])/g, '$1'),
+        url,
+        domain: domainOf(url, { stripWww: true }),
+      });
+    current = null;
+  };
+
+  for (const line of section.split('\n')) {
+    const m = REFERENCE_LINE_RE.exec(line);
+    if (m) {
+      flush();
+      current = { id: Number(m[1]), rest: m[2] };
+    } else if (current && line.trim().length > 0) {
+      // A legacy entry's URL sits on the indented line after the title.
+      current.rest += ` ${line.trim()}`;
+    }
+  }
+  flush();
+
+  return entries.length > 0 ? { body, references: entries } : { body: text, references: null };
+}

package/src/lib/clipboard.ts

@@ -0,0 +1,23 @@
+import { toast } from '@oxy.so/bloom/toast';
+import * as Clipboard from 'expo-clipboard';
+import type { Translate } from './copy';
+
+/**
+ * Copy `text`, and say which happened.
+ *
+ * The result is the clipboard's own: `setStringAsync` resolves `false` on web when the browser
+ * refuses (no permission, no focus, an insecure origin) and rejects on native when the module is
+ * missing. Either way the answer is `false` and an error toast, and Bloom's copy button, which
+ * confirms only on `true`, stays a copy glyph instead of announcing "Copied!" over nothing.
+ */
+export async function copyText(text: string, t: Translate): Promise<boolean> {
+  let copied: boolean;
+  try {
+    copied = (await Clipboard.setStringAsync(text)) !== false;
+  } catch {
+    copied = false;
+  }
+  if (copied) toast.success(t('chat.copiedToClipboard'));
+  else toast.error(t('chat.copyFailed'));
+  return copied;
+}

package/src/lib/content-utils.ts

@@ -1,3 +1,5 @@
+import { processMessage } from '../runtime/thread/message-processor';
+
 /** A single part of a multi-part chat message content array. */
 export interface ContentPart {
   type: string;
@@ -22,6 +24,14 @@ export function getTextFromContent(content: MessageContent | null | undefined):
   return String(content || '');
 }
 
+/**
+ * A message's words as the thread draws them: its text parts, without the tags other platforms
+ * use (Telegram's), which a reply written for one can still carry.
+ */
+export function messageText(message: { content: MessageContent | null | undefined }): string {
+  return processMessage(message.content ? getTextFromContent(message.content) : '', 'app').text;
+}
+
 /**
  * Extract image URLs from multi-part message content.
  */