@alia.onl/sdk 10.1.0 → 11.0.0

package/src/lib/chat-transport.ts

@@ -1,3 +1,4 @@
+import type { MessageContent } from './content-utils';
 import {
   AliaChatStreamError,
   consumeAliaChatStream,
@@ -20,7 +21,7 @@ export interface AliaChatRequest {
   readonly url: string;
   /** `publisher/model`; omitted, the server's default model answers. */
   readonly model?: string;
-  readonly messages: ReadonlyArray<{ readonly role: string; readonly content: string }>;
+  readonly messages: ReadonlyArray<{ readonly role: string; readonly content: MessageContent }>;
   /**
    * `'voice'` asks for an answer meant to be heard: short, conversational, no
    * formatting (the API layers its voice response profile over the turn's

package/src/lib/citations.ts

@@ -0,0 +1,63 @@
+import type { ToolInvocation } from '../types';
+
+export interface CitationSource {
+  /** The citation number, as it appears in `[n]`. */
+  id: number;
+  url: string;
+  title: string;
+  domain: string;
+}
+
+interface PersistedResearchSource {
+  id?: unknown;
+  url?: unknown;
+  title?: unknown;
+}
+
+function domainOf(url: string): string {
+  try {
+    return new URL(url).hostname.replace(/^www\./, '');
+  } catch {
+    return url;
+  }
+}
+
+/**
+ * The numbered sources of a research answer.
+ *
+ * Only `deepResearch` invocations carry NUMBERED sources; a `webSearch` result has URLs but
+ * no `[n]` to stand for them, so it contributes nothing here. The first invocation to claim a
+ * number wins, which is also the only one there is.
+ */
+export function extractCitationSources(
+  toolInvocations?: readonly ToolInvocation[],
+  /** `researchProgress.sources` of a live research answer, before it is persisted. */
+  liveSources?: readonly PersistedResearchSource[] | null,
+): CitationSource[] {
+  const byId = new Map<number, CitationSource>();
+  const take = (raw: PersistedResearchSource) => {
+    if (!raw || typeof raw !== 'object') return;
+    const id = typeof raw.id === 'number' ? raw.id : Number(raw.id);
+    const url = typeof raw.url === 'string' ? raw.url : '';
+    if (!Number.isInteger(id) || id < 1 || url.length === 0 || byId.has(id)) return;
+    const title =
+      typeof raw.title === 'string' && raw.title.trim().length > 0
+        ? raw.title.trim()
+        : domainOf(url);
+    byId.set(id, { id, url, title, domain: domainOf(url) });
+  };
+
+  for (const inv of toolInvocations ?? []) {
+    if (inv.toolName !== 'deepResearch' || inv.state !== 'result') continue;
+    const result = inv.result;
+    const sources: unknown =
+      result !== null && typeof result === 'object'
+        ? (result as { sources?: unknown }).sources
+        : undefined;
+    if (!Array.isArray(sources)) continue;
+    for (const raw of sources as PersistedResearchSource[]) take(raw);
+  }
+  for (const raw of liveSources ?? []) take(raw);
+
+  return [...byId.values()].sort((a, b) => a.id - b.id);
+}

package/src/lib/content-utils.ts

@@ -28,8 +28,9 @@ export function getTextFromContent(content: MessageContent | null | undefined):
 export function getImagesFromContent(content: MessageContent | null | undefined): string[] {
   if (!Array.isArray(content)) return [];
   return content
-    .filter((p): p is ContentPart & { image_url: { url: string } } =>
-      p.type === 'image_url' && typeof p.image_url?.url === 'string',
+    .filter(
+      (p): p is ContentPart & { image_url: { url: string } } =>
+        p.type === 'image_url' && typeof p.image_url?.url === 'string',
     )
     .map((p) => p.image_url.url);
 }

package/src/lib/image-data-url.ts

@@ -0,0 +1,15 @@
+/**
+ * Reads a picked image (a `file://` URI on native, a `blob:` URL on web) into a
+ * `data:` URL, the one form the chat API accepts as an `image_url` part without
+ * the server having to reach the device.
+ */
+export async function imageUriToDataUrl(uri: string): Promise<string> {
+  if (uri.startsWith('data:')) return uri;
+  const blob = await (await fetch(uri)).blob();
+  return await new Promise<string>((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onerror = () => reject(reader.error ?? new Error('Could not read the image'));
+    reader.onload = () => resolve(String(reader.result));
+    reader.readAsDataURL(blob);
+  });
+}

package/src/lib/keyboard.tsx

@@ -18,7 +18,7 @@ type KeyboardAwareScrollViewProps = ScrollViewProps & {
 const KeyboardAwareScrollView = React.forwardRef<ScrollView, KeyboardAwareScrollViewProps>(
   ({ bottomOffset, disableScrollOnKeyboardHide, enabled, extraKeyboardSpace, ...props }, ref) => (
     <ScrollView ref={ref} {...props} />
-  )
+  ),
 );
 KeyboardAwareScrollView.displayName = 'KeyboardAwareScrollView';
 

package/src/lib/labels.tsx

@@ -0,0 +1,81 @@
+import { createContext, type ReactNode, useContext, useMemo } from 'react';
+import { englishWorkLog, type Translate } from './work-log-copy';
+
+/** Every string the chat UI draws itself. Bloom's own copy follows `BloomProvider locale`. */
+export interface AliaChatLabels {
+  // Header
+  clear: string;
+  close: string;
+  chatActions: string;
+  // Composer
+  placeholder: string;
+  addMenuGroup: string;
+  addPhotos: string;
+  startVoice: string;
+  voiceFailed: string;
+  // Messages
+  copy: string;
+  copied: string;
+  edit: string;
+  save: string;
+  cancel: string;
+  readAloud: string;
+  stopReading: string;
+  // Plan
+  planTitle: string;
+  planApprove: string;
+  planCancel: string;
+  planApproved: string;
+  planCancelled: string;
+  // Reasoning
+  reasoning: string;
+  thoughtFor: (seconds: number) => string;
+  // The turn's work log
+  /** The words of the tool log, keyed as the Alia app keys them (see `work-log-copy.ts`). */
+  workLog: Translate;
+  // Research
+}
+
+export const DEFAULT_LABELS: AliaChatLabels = {
+  clear: 'Clear',
+  close: 'Close',
+  chatActions: 'Chat actions',
+  placeholder: 'Ask Alia...',
+  addMenuGroup: 'Add',
+  addPhotos: 'Photos',
+  startVoice: 'Start voice',
+  voiceFailed: "Couldn't start the voice call",
+  copy: 'Copy',
+  copied: 'Copied',
+  edit: 'Edit',
+  save: 'Save',
+  cancel: 'Cancel',
+  readAloud: 'Read aloud',
+  stopReading: 'Stop reading',
+  planTitle: "Here's my plan",
+  planApprove: 'Approve',
+  planCancel: 'Cancel',
+  planApproved: 'Plan approved',
+  planCancelled: 'Plan cancelled',
+  reasoning: 'Reasoning',
+  thoughtFor: (seconds) => `Thought for ${seconds} seconds`,
+  workLog: englishWorkLog,
+};
+
+const LabelsContext = createContext<AliaChatLabels>(DEFAULT_LABELS);
+
+/** The chat's labels: the defaults, with whatever the host overrides. */
+export function AliaChatLabelsProvider({
+  labels,
+  children,
+}: {
+  labels?: Partial<AliaChatLabels>;
+  children: ReactNode;
+}) {
+  const value = useMemo(() => ({ ...DEFAULT_LABELS, ...labels }), [labels]);
+  return <LabelsContext.Provider value={value}>{children}</LabelsContext.Provider>;
+}
+
+export function useLabels(): AliaChatLabels {
+  return useContext(LabelsContext);
+}

package/src/lib/speech-recognition.native.ts

@@ -16,7 +16,10 @@
  * listeners.
  */
 
-import type { ExpoSpeechRecognitionErrorCode, ExpoSpeechRecognitionModule as NativeModule } from 'expo-speech-recognition';
+import type {
+  ExpoSpeechRecognitionErrorCode,
+  ExpoSpeechRecognitionModule as NativeModule,
+} from 'expo-speech-recognition';
 import {
   clampLevel,
   matchSpeechLocale,
@@ -68,7 +71,10 @@ export async function requestSpeechRecognitionPermission(): Promise<SpeechRecogn
     const permission = await module.requestPermissionsAsync();
     return permission.granted ? null : { code: 'not-allowed', detail: permission.status };
   } catch (error: unknown) {
-    return { code: 'other', detail: error instanceof Error ? error.message : 'permission request failed' };
+    return {
+      code: 'other',
+      detail: error instanceof Error ? error.message : 'permission request failed',
+    };
   }
 }
 
@@ -134,7 +140,8 @@ export async function chooseSpeechRecognizer(lang: string): Promise<SpeechRecogn
   for (const service of order) {
     let offered: string[];
     try {
-      offered = (await module.getSupportedLocales({ androidRecognitionServicePackage: service })).locales;
+      offered = (await module.getSupportedLocales({ androidRecognitionServicePackage: service }))
+        .locales;
     } catch {
       continue;
     }
@@ -209,7 +216,11 @@ export function startSpeechRecognition(
       ...(options.echoCancellation ? { iosVoiceProcessingEnabled: true } : {}),
     });
   } catch (error: unknown) {
-    if (!ended) handlers.onError({ code: 'other', detail: error instanceof Error ? error.message : 'start failed' });
+    if (!ended)
+      handlers.onError({
+        code: 'other',
+        detail: error instanceof Error ? error.message : 'start failed',
+      });
     finish();
   }
 

package/src/lib/speech-recognition.ts

@@ -38,11 +38,25 @@ import type {
 // Declared here rather than taken from lib.dom: TypeScript's DOM library does
 // not ship the prefixed constructor, and the unprefixed one is not everywhere.
 
-interface WebSpeechAlternative { readonly transcript: string }
-interface WebSpeechResult { readonly isFinal: boolean; readonly length: number; readonly [index: number]: WebSpeechAlternative }
-interface WebSpeechResultList { readonly length: number; readonly [index: number]: WebSpeechResult }
-interface WebSpeechResultEvent { readonly results: WebSpeechResultList }
-interface WebSpeechErrorEvent { readonly error: string; readonly message?: string }
+interface WebSpeechAlternative {
+  readonly transcript: string;
+}
+interface WebSpeechResult {
+  readonly isFinal: boolean;
+  readonly length: number;
+  readonly [index: number]: WebSpeechAlternative;
+}
+interface WebSpeechResultList {
+  readonly length: number;
+  readonly [index: number]: WebSpeechResult;
+}
+interface WebSpeechResultEvent {
+  readonly results: WebSpeechResultList;
+}
+interface WebSpeechErrorEvent {
+  readonly error: string;
+  readonly message?: string;
+}
 
 interface WebSpeechRecognition {
   lang: string;
@@ -95,7 +109,12 @@ export async function requestSpeechRecognitionPermission(): Promise<SpeechRecogn
 
 function domErrorName(error: unknown): string {
   // A DOMException is not always `instanceof Error`, so read `.name` off the object.
-  if (typeof error === 'object' && error !== null && 'name' in error && typeof error.name === 'string') {
+  if (
+    typeof error === 'object' &&
+    error !== null &&
+    'name' in error &&
+    typeof error.name === 'string'
+  ) {
     return error.name;
   }
   return '';
@@ -149,7 +168,8 @@ const LEVEL_INTERVAL_MS = 100;
 
 /** An analyser on the microphone, polled on a clock. Returns its teardown. */
 function meterStream(stream: MediaStream, onLevel: (level: number) => void): () => void {
-  const AudioContextCtor = (globalThis as unknown as { AudioContext?: typeof AudioContext }).AudioContext;
+  const AudioContextCtor = (globalThis as unknown as { AudioContext?: typeof AudioContext })
+    .AudioContext;
   if (AudioContextCtor === undefined) return () => undefined;
   let context: AudioContext;
   try {

package/src/lib/task-labels.ts

@@ -0,0 +1,67 @@
+import { englishWorkLog, type Translate } from './work-log-copy';
+
+/** Tools that have a name of their own in the catalogue. Others are named from their id. */
+const NAMED_PILL = new Set([
+  'browse',
+  'webSearch',
+  'webScraper',
+  'generateFile',
+  'sendTelegramMessage',
+  'sendSlack',
+  'sendDiscord',
+  'sendSignal',
+  'sendEmail',
+  'delegateToAgent',
+  'askAgent',
+  // The API's app router: the model opening a connected app whose tools did not all fit in
+  // one request.
+  'useApps',
+  'agentSearch',
+  'userMemory',
+  'shellExec',
+  'fileEdit',
+  'codeInterpreter',
+]);
+
+/** Tools whose finished label differs from the running one; the rest read the same. */
+const NAMED_DONE = new Set([
+  'browse',
+  'webScraper',
+  'generateFile',
+  'delegateToAgent',
+  'askAgent',
+  'useApps',
+  'agentSearch',
+  'userMemory',
+  'shellExec',
+  'fileEdit',
+  'codeInterpreter',
+]);
+
+/** A tool's short label, in the reader's language when a translator is given. */
+export function getToolPillLabel(toolName: string, t: Translate = englishWorkLog): string {
+  if (NAMED_PILL.has(toolName)) return t(`tasks.tool.pill.${toolName}`);
+
+  // Oxy service tools: oxy_serviceName__toolName → "ServiceName"
+  if (toolName.startsWith('oxy_')) {
+    const parts = toolName.replace('oxy_', '').split('__');
+    return (parts[0] ?? '').replace(/[-_]/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+  }
+
+  // Fallback: camelCase → "Camel Case"
+  return toolName
+    .replace(/([A-Z])/g, ' $1')
+    .replace(/^./, (c) => c.toUpperCase())
+    .trim();
+}
+
+/**
+ * The finished form of a tool's label, for a task whose call has returned (`TaskList` swaps
+ * `runningTitle` for this once the task's steps land). Labels that are already names
+ * ("Telegram", "Email") read the same either way, so they fall back to the running label.
+ */
+export function getToolDoneLabel(toolName: string, t: Translate = englishWorkLog): string {
+  return NAMED_DONE.has(toolName)
+    ? t(`tasks.tool.done.${toolName}`)
+    : getToolPillLabel(toolName, t);
+}

package/src/lib/tool-call-status.ts

@@ -0,0 +1,28 @@
+import type { ToolInvocation } from '../types';
+
+/**
+ * Where a tool call stands:
+ *  - `running`: still in flight in a live turn.
+ *  - `done`: it returned a result without an error.
+ *  - `error`: it returned, and the result carries an `error`.
+ *  - `interrupted`: it never returned and its turn is over — a stop, a failure, or a
+ *    persisted turn cut short. It must not read as running.
+ */
+export type ToolCallStatus = 'running' | 'done' | 'error' | 'interrupted';
+
+export function toolCallStatus(
+  inv: Pick<ToolInvocation, 'state' | 'result'>,
+  live: boolean,
+): ToolCallStatus {
+  if (inv.state !== 'result') return live ? 'running' : 'interrupted';
+  const result: unknown = inv.result;
+  if (
+    result !== null &&
+    typeof result === 'object' &&
+    'error' in result &&
+    Boolean((result as { error?: unknown }).error)
+  ) {
+    return 'error';
+  }
+  return 'done';
+}

package/src/lib/tool-registry.ts

@@ -5,27 +5,27 @@ interface ToolDefinition {
 
 const TOOL_REGISTRY: Record<string, ToolDefinition> = {
   // Search
-  webSearch:           { label: 'Searching the web',         category: 'search' },
-  scrapeURL:           { label: 'Reading URL',               category: 'search' },
-  getTimeline:         { label: 'Getting timeline',          category: 'search' },
-  searchKnowledgeBase: { label: 'Searching knowledge base',  category: 'search' },
-  webScraper:          { label: 'Reading web page',          category: 'search' },
-  browse:              { label: 'Browsing the web',          category: 'search' },
+  webSearch: { label: 'Searching the web', category: 'search' },
+  scrapeURL: { label: 'Reading URL', category: 'search' },
+  getTimeline: { label: 'Getting timeline', category: 'search' },
+  searchKnowledgeBase: { label: 'Searching knowledge base', category: 'search' },
+  webScraper: { label: 'Reading web page', category: 'search' },
+  browse: { label: 'Browsing the web', category: 'search' },
 
   // Communication
-  sendWhatsAppMessage: { label: 'Sending WhatsApp message',  category: 'communication' },
-  getWhatsAppChats:    { label: 'Loading WhatsApp chats',    category: 'communication' },
+  sendWhatsAppMessage: { label: 'Sending WhatsApp message', category: 'communication' },
+  getWhatsAppChats: { label: 'Loading WhatsApp chats', category: 'communication' },
   getWhatsAppMessages: { label: 'Reading WhatsApp messages', category: 'communication' },
-  sendTelegramMessage: { label: 'Sending Telegram message',  category: 'communication' },
+  sendTelegramMessage: { label: 'Sending Telegram message', category: 'communication' },
 
   // Utility
-  getCurrentDate:      { label: 'Getting current date',      category: 'utility' },
-  generateFile:        { label: 'Generating file',           category: 'utility' },
+  getCurrentDate: { label: 'Getting current date', category: 'utility' },
+  generateFile: { label: 'Generating file', category: 'utility' },
 
   // Memory
-  saveUserMemory:        { label: 'Saving to memory',      category: 'memory' },
-  updateUserPreferences: { label: 'Updating preferences',  category: 'memory' },
-  updateUserContext:     { label: 'Updating context',      category: 'memory' },
+  saveUserMemory: { label: 'Saving to memory', category: 'memory' },
+  updateUserPreferences: { label: 'Updating preferences', category: 'memory' },
+  updateUserContext: { label: 'Updating context', category: 'memory' },
 };
 
 /**

package/src/lib/voice-text.ts

@@ -11,12 +11,11 @@
 
 const TAG = String.raw`ALIA_TITLE|TITLE|TÍTULO|TITRE|TITOLO|TITEL|ЗАГОЛОВОК`;
 
-const TITLE_STRIP_RE = new RegExp(
-  String.raw`\[(${TAG})\].*?\[\/\1\]|<(${TAG})>.*?<\/\2>`, 'gi',
-);
+const TITLE_STRIP_RE = new RegExp(String.raw`\[(${TAG})\].*?\[\/\1\]|<(${TAG})>.*?<\/\2>`, 'gi');
 
 const TITLE_PARTIAL_RE = new RegExp(
-  String.raw`\[(${TAG})\].*?(\[\/\1\])?$|<(${TAG})>.*?(<\/\3>)?$`, 'si',
+  String.raw`\[(${TAG})\].*?(\[\/\1\])?$|<(${TAG})>.*?(<\/\3>)?$`,
+  'si',
 );
 
 /**
@@ -31,7 +30,10 @@ export function stripTitleTags(content: string, { trim = true }: { trim?: boolea
 }
 
 /** The same, for an answer still streaming: an opened tag hides the rest. */
-export function stripTitleTagsPartial(content: string, { trim = true }: { trim?: boolean } = {}): string {
+export function stripTitleTagsPartial(
+  content: string,
+  { trim = true }: { trim?: boolean } = {},
+): string {
   const stripped = content.replace(TITLE_STRIP_RE, '').replace(TITLE_PARTIAL_RE, '');
   return trim ? stripped.trim() : stripped;
 }
@@ -106,7 +108,11 @@ export function takeSpeechChunks(
     rest = '';
   } else if (rest.length > MAX_RUN_CHARS) {
     const window = rest.slice(0, MAX_RUN_CHARS);
-    const pause = Math.max(window.lastIndexOf(', '), window.lastIndexOf('; '), window.lastIndexOf(': '));
+    const pause = Math.max(
+      window.lastIndexOf(', '),
+      window.lastIndexOf('; '),
+      window.lastIndexOf(': '),
+    );
     const cut = pause > 0 ? pause + 2 : Math.max(window.lastIndexOf(' '), 1);
     sentences.push(rest.slice(0, cut));
     rest = rest.slice(cut);

package/src/lib/voice-turn.ts

@@ -43,7 +43,10 @@ export interface VoiceTurn {
 export type VoiceTurnSender = (turn: VoiceTurn) => Promise<void>;
 
 interface LinkedClientFactory {
-  createLinkedClient(config: { baseURL: string }): { client: AuthenticatedResponseClient; dispose(): void };
+  createLinkedClient(config: { baseURL: string }): {
+    client: AuthenticatedResponseClient;
+    dispose(): void;
+  };
 }
 
 export interface AliaVoiceTurnSenderOptions {

package/src/lib/work-log-copy.ts

@@ -0,0 +1,61 @@
+/**
+ * The words of the work log (`work-log.ts`), keyed the way the Alia app's own catalogue keys
+ * them, so the app hands its translator straight in. A host without one gets English.
+ */
+export type Translate = (key: string, params?: Record<string, unknown>) => string;
+
+type Entry = string | { one: string; other: string };
+
+const CATALOGUE: Record<string, Entry> = {
+  'chat.bloom.researched': 'Researched',
+  'chat.bloom.searchCount': { one: '1 search', other: '{{count}} searches' },
+  'chat.bloom.searchedWeb': 'Searched the web for',
+  'chat.bloom.searchFailed': 'Search failed',
+  'chat.bloom.noResults': 'No results',
+  'chat.bloom.resultCount': { one: '1 result', other: '{{count}} results' },
+  'chat.bloom.visited': 'Visited',
+  'chat.bloom.researching': 'Researching',
+  'chat.bloom.sourceCount': { one: '1 source', other: '{{count}} sources' },
+  'chat.bloom.createdFile': 'Created',
+  'chat.bloom.writingFile': 'Writing',
+  'chat.bloom.taskInput': 'With',
+  'chat.bloom.taskFailed': 'Returned an error',
+  'chat.bloom.taskStopped': "Didn't finish",
+  'tasks.tool.pill.browse': 'Browsing',
+  'tasks.tool.pill.webSearch': 'Web search',
+  'tasks.tool.pill.webScraper': 'Reading page',
+  'tasks.tool.pill.generateFile': 'Generating file',
+  'tasks.tool.pill.sendTelegramMessage': 'Telegram',
+  'tasks.tool.pill.sendSlack': 'Slack',
+  'tasks.tool.pill.sendDiscord': 'Discord',
+  'tasks.tool.pill.sendSignal': 'Signal',
+  'tasks.tool.pill.sendEmail': 'Email',
+  'tasks.tool.pill.delegateToAgent': 'Delegating',
+  'tasks.tool.pill.askAgent': 'Asking an agent',
+  'tasks.tool.pill.useApps': 'Opening apps',
+  'tasks.tool.pill.agentSearch': 'Searching agents',
+  'tasks.tool.pill.userMemory': 'Remembering',
+  'tasks.tool.pill.shellExec': 'Running command',
+  'tasks.tool.pill.fileEdit': 'Editing file',
+  'tasks.tool.pill.codeInterpreter': 'Running code',
+  'tasks.tool.done.browse': 'Browsed',
+  'tasks.tool.done.webScraper': 'Read page',
+  'tasks.tool.done.generateFile': 'Generated file',
+  'tasks.tool.done.delegateToAgent': 'Delegated',
+  'tasks.tool.done.askAgent': 'Asked an agent',
+  'tasks.tool.done.useApps': 'Opened apps',
+  'tasks.tool.done.agentSearch': 'Searched agents',
+  'tasks.tool.done.userMemory': 'Remembered',
+  'tasks.tool.done.shellExec': 'Ran command',
+  'tasks.tool.done.fileEdit': 'Edited file',
+  'tasks.tool.done.codeInterpreter': 'Ran code',
+};
+
+/** The default translator: the English above, with `{{count}}` plurals. */
+export const englishWorkLog: Translate = (key, params) => {
+  const entry = CATALOGUE[key];
+  if (entry === undefined) return key;
+  const count = typeof params?.count === 'number' ? params.count : undefined;
+  const text = typeof entry === 'string' ? entry : count === 1 ? entry.one : entry.other;
+  return text.replace('{{count}}', String(count ?? ''));
+};