@alia.onl/sdk 11.1.0 → 13.0.0

package/src/lib/chat-stream.ts

@@ -1,4 +1,5 @@
 import type { PlanStep, ResearchProgress, ResearchSource } from '../types';
+import { ASK_USER_QUESTION_TOOL } from './questions';
 
 const MAX_STREAM_BYTES = 8 * 1024 * 1024;
 const MAX_STREAM_LINES = 65_536;
@@ -30,7 +31,12 @@ export type AliaChatStreamEvent =
   | {
       readonly kind: 'agent_answer';
       readonly content: string;
-      readonly agent: { readonly id: string; readonly name: string; readonly avatar: null };
+      readonly agent: {
+        readonly id: string;
+        readonly name: string;
+        /** The agent's look as the server stores it (JSON); absent from a server that does not send it. */
+        readonly character?: unknown;
+      };
     };
 
 export interface AliaChatStreamResult {
@@ -323,7 +329,15 @@ function parseNamedEvent(eventName: string, payload: unknown): AliaChatStreamEve
     case 'alia.agent': {
       assertOnlyKeys(
         body,
-        ['eventVersion', 'agentId', 'agentName', 'agentHandle', 'agentColor', 'content'],
+        [
+          'eventVersion',
+          'agentId',
+          'agentName',
+          'agentHandle',
+          'agentColor',
+          'agentCharacter',
+          'content',
+        ],
         eventName,
       );
       if (body.agentColor !== null) asString(body.agentColor, `${eventName} agentColor`);
@@ -334,7 +348,11 @@ function parseNamedEvent(eventName: string, payload: unknown): AliaChatStreamEve
         agent: {
           id: asString(body.agentId, `${eventName} agentId`),
           name: asString(body.agentName, `${eventName} agentName`),
-          avatar: null,
+          // As the server sent it, parsed where it is drawn (`readAgentCharacter`). Absent from an
+          // older server, null for an agent that could not be read: the default look then.
+          ...(body.agentCharacter === undefined || body.agentCharacter === null
+            ? {}
+            : { character: body.agentCharacter }),
         },
       };
     }
@@ -579,6 +597,10 @@ export async function consumeAliaChatStream(
     }
     for (const event of parsed.events) {
       if (event.kind === 'content' && event.content.trim().length > 0) answerReceived = true;
+      // A turn that ends at a question card is answered by the card, even with no sentence before it.
+      if (event.kind === 'tool_call' && event.toolName === ASK_USER_QUESTION_TOOL) {
+        answerReceived = true;
+      }
       onEvent(event);
     }
     if (parsed.finishReason !== null) {

package/src/lib/citations.ts

@@ -1,4 +1,5 @@
 import type { ToolInvocation } from '../types';
+import { domainOf } from './domain';
 
 export interface CitationSource {
   /** The citation number, as it appears in `[n]`. */
@@ -14,14 +15,6 @@ interface PersistedResearchSource {
   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.
  *
@@ -43,8 +36,8 @@ export function extractCitationSources(
     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) });
+        : domainOf(url, { stripWww: true });
+    byId.set(id, { id, url, title, domain: domainOf(url, { stripWww: true }) });
   };
 
   for (const inv of toolInvocations ?? []) {
@@ -61,3 +54,62 @@ export function extractCitationSources(
 
   return [...byId.values()].sort((a, b) => a.id - b.id);
 }
+
+const FULLWIDTH_MARKER_RE = /【\s*(\d{1,3})\s*(?:†[^】]*)?】/g;
+const ASCII_DAGGER_MARKER_RE = /\[(\d{1,3})†[^\]]*\]/g;
+const COMMA_LIST_RE = /\[(\d{1,3}(?:\s*,\s*\d{1,3})+)\](?![(:])/g;
+const SINGLE_MARKER_RE = /\[(\d{1,3})\](?![(:])/g;
+
+/**
+ * Rewrite every citation marker into the `[n]` form; with `knownIds`, drop
+ * the ones that name no source. See the API twin for the reasoning.
+ */
+export function normalizeCitationMarkers(text: string, knownIds?: Iterable<number>): string {
+  const known = knownIds ? new Set(knownIds) : null;
+
+  let out = text
+    .replace(FULLWIDTH_MARKER_RE, '[$1]')
+    .replace(ASCII_DAGGER_MARKER_RE, '[$1]')
+    .replace(COMMA_LIST_RE, (_m, list: string) =>
+      list
+        .split(',')
+        .map((n) => `[${n.trim()}]`)
+        .join(''),
+    );
+
+  if (known && known.size > 0) {
+    out = out.replace(SINGLE_MARKER_RE, (m, n: string) => (known.has(Number(n)) ? m : ''));
+    out = out.replace(/[ \t]+([.,;:!?])/g, '$1').replace(/[ \t]{2,}/g, ' ');
+  }
+
+  return out;
+}
+
+/**
+ * The accessible name of one citation: what a screen reader says for the
+ * link, and what `CustomMarkdown` puts in the link's title.
+ */
+export function citationLabel(source: CitationSource): string {
+  return `Source ${source.id}: ${source.title}`;
+}
+
+/**
+ * `[n]` markers that name a known source become Markdown links to it, so the
+ * SDK's Markdown renderer makes them pressable. Markers with no source are
+ * left as text: dropping them here would hide that the model cited something
+ * the reader cannot check, and the API already drops them for new answers.
+ *
+ * Runs on the normalised text, so legacy `【n†…】` markers link too. The
+ * link title carries the accessible name; a title containing quotes would end
+ * it early, so those are folded to apostrophes.
+ */
+export function linkifyCitations(text: string, sources: CitationSource[]): string {
+  if (sources.length === 0) return normalizeCitationMarkers(text);
+  const byId = new Map(sources.map((s) => [s.id, s]));
+  return normalizeCitationMarkers(text).replace(SINGLE_MARKER_RE, (m, n: string) => {
+    const source = byId.get(Number(n));
+    if (!source) return m;
+    const title = citationLabel(source).replace(/"/g, "'");
+    return `[${n}](${source.url} "${title}")`;
+  });
+}

package/src/lib/delegation.ts

@@ -0,0 +1,34 @@
+import type { ToolInvocation } from '../types';
+
+/** The tools that hand a question to another agent. */
+const DELEGATION_TOOLS = new Set(['delegateToAgent', 'askAgent']);
+
+export interface WorkingAgent {
+  id: string;
+  name: string;
+}
+
+const text = (value: unknown): string | undefined =>
+  typeof value === 'string' && value.trim() !== '' ? value : undefined;
+
+/**
+ * The agent a delegation call is for, from its arguments: an id (`agentId`) and a name
+ * (`agentName`, or `agent` when it is a name). Whichever is missing falls back on the other, so
+ * the placeholder and the answer that follows agree on who it is as long as the call names them.
+ */
+export function delegatedAgent(invocation: ToolInvocation): WorkingAgent | null {
+  if (!DELEGATION_TOOLS.has(invocation.toolName)) return null;
+  const args = invocation.args ?? {};
+  const id = text(args.agentId) ?? text(args.agent_id) ?? text(args.agent) ?? text(args.name);
+  const name = text(args.agentName) ?? text(args.agent) ?? text(args.name) ?? id;
+  if (!id || !name) return null;
+  return { id, name };
+}
+
+/**
+ * The id of an agent's message in a turn. A delegation call creates it empty (the agent is
+ * thinking) and the agent's answer fills the same message, so one element carries the avatar from
+ * thinking to answered.
+ */
+export const agentMessageId = (assistantId: string, agentId: string) =>
+  `${assistantId}-agent-${agentId}`;

package/src/lib/domain.ts

@@ -0,0 +1,12 @@
+/**
+ * The host of a URL, or the string itself when it is not one. Citations drop a leading `www.`
+ * (the number in `[3]` names a site); a source row in the work log keeps the host as served.
+ */
+export function domainOf(url: string, { stripWww = false }: { stripWww?: boolean } = {}): string {
+  try {
+    const host = new URL(url).hostname;
+    return stripWww ? host.replace(/^www\./, '') : host;
+  } catch {
+    return url;
+  }
+}

package/src/lib/flights.ts

@@ -0,0 +1,24 @@
+import { createContext, useContext } from 'react';
+import type { AvatarFlights, AvatarFlightSpec } from '@oxy.so/bloom/avatar-flight';
+
+import { ALIA_AVATAR } from '../components/AliaAvatar';
+
+/** Where Alia's avatar is in the chat: large in the greeting, then small in the header's profile. */
+export const ALIA_ANCHORS = { welcome: 'alia:welcome', profile: 'alia:profile' } as const;
+
+/** The greeting's avatar flies up into the header's profile as the conversation begins. */
+export const ALIA_TO_PROFILE: AvatarFlightSpec = {
+  key: 'alia',
+  character: ALIA_AVATAR,
+  from: ALIA_ANCHORS.welcome,
+  to: ALIA_ANCHORS.profile,
+  duration: 800,
+};
+
+const FlightsContext = createContext<AvatarFlights | null>(null);
+
+/** The chat's avatar flights, for the greeting and the header that share them. */
+export const AliaFlightsProvider = FlightsContext.Provider;
+
+/** `null` outside a chat: the greeting and the header then draw their avatars without flying. */
+export const useAliaFlights = () => useContext(FlightsContext);

package/src/lib/greeting.ts

@@ -0,0 +1,15 @@
+/** Commas of the languages the apps greet in: Latin, fullwidth, ideographic and Arabic. */
+const COMMA = /[,，、،]/;
+
+/**
+ * A greeting in two lines: the address ("Hi Nate,") over the rest ("what's on your mind?"). It
+ * breaks after the first comma, which keeps the greeting one string a translator writes once; a
+ * greeting without one (or with nothing after it) stays a single line.
+ */
+export function greetingLines(greeting: string): [string] | [string, string] {
+  const at = greeting.search(COMMA);
+  if (at < 0) return [greeting];
+  const first = greeting.slice(0, at + 1);
+  const rest = greeting.slice(at + 1).trim();
+  return rest === '' ? [greeting] : [first, rest];
+}

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

@@ -1,15 +1,36 @@
+import * as FileSystem from 'expo-file-system';
+import { Platform } from 'react-native';
+
 /**
- * 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.
+ * Reads a picked image into a `data:` URL, the one form the chat API accepts as an `image_url`
+ * part without the server having to reach the device. The picker's URI means nothing off the
+ * device: on web it is a `blob:` URL (a handle into this tab's memory), on native a `file://`
+ * path, and sent as it is either arrives as a string the model cannot open.
+ *
+ * Web reads the blob back; native reads the file with `expo-file-system`, as the Alia app does.
  */
-export async function imageUriToDataUrl(uri: string): Promise<string> {
+export async function imageUriToDataUrl(uri: string, mimeType?: string): Promise<string> {
   if (uri.startsWith('data:')) return uri;
+  if (Platform.OS !== 'web') {
+    const base64 = await FileSystem.readAsStringAsync(uri, {
+      encoding: FileSystem.EncodingType.Base64,
+    });
+    return `data:${mimeType || 'image/jpeg'};base64,${base64}`;
+  }
   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.onload = () => {
+      const result = String(reader.result);
+      // `readAsDataURL` stamps the blob's own type; it is only octet-stream when the blob has
+      // none, and then the picker's type is the better guess.
+      resolve(
+        mimeType && result.startsWith('data:application/octet-stream')
+          ? result.replace('data:application/octet-stream', `data:${mimeType}`)
+          : result,
+      );
+    };
     reader.readAsDataURL(blob);
   });
 }

package/src/lib/labels.tsx

@@ -5,7 +5,9 @@ import { englishWorkLog, type Translate } from './work-log-copy';
 export interface AliaChatLabels {
   // Header
   clear: string;
-  close: string;
+  back: string;
+  share: string;
+  more: string;
   chatActions: string;
   // Composer
   placeholder: string;
@@ -15,6 +17,8 @@ export interface AliaChatLabels {
   voiceFailed: string;
   // Messages
   copy: string;
+  helpful: string;
+  unhelpful: string;
   copied: string;
   edit: string;
   save: string;
@@ -38,7 +42,9 @@ export interface AliaChatLabels {
 
 export const DEFAULT_LABELS: AliaChatLabels = {
   clear: 'Clear',
-  close: 'Close',
+  back: 'Back',
+  share: 'Share',
+  more: 'More',
   chatActions: 'Chat actions',
   placeholder: 'Ask Alia...',
   addMenuGroup: 'Add',
@@ -46,6 +52,8 @@ export const DEFAULT_LABELS: AliaChatLabels = {
   startVoice: 'Start voice',
   voiceFailed: "Couldn't start the voice call",
   copy: 'Copy',
+  helpful: 'Helpful response',
+  unhelpful: 'Unhelpful response',
   copied: 'Copied',
   edit: 'Edit',
   save: 'Save',

package/src/lib/questions.ts

@@ -4,7 +4,7 @@
 // call: it is stored with the message, survives a reload, and is answered by the person's
 // next message. Pure functions, no React Native, so a host's models and tests can use them.
 
-import type { ToolInvocation } from '../types';
+import type { ChatMessage, ToolInvocation } from '../types';
 
 /** The tool's name on the wire. */
 export const ASK_USER_QUESTION_TOOL = 'askUserQuestion';
@@ -76,3 +76,17 @@ export function formatAnswers(questions: AskedQuestion[], answers: QuestionAnswe
     })
     .join('\n\n');
 }
+
+/**
+ * What Alia asked in her last turn and the person has not answered yet: the questions of the
+ * last message when it is hers and finished. A message after them, typed or sent from the card,
+ * is the answer, so nothing is pending then.
+ */
+export function pendingQuestions(
+  messages: readonly Pick<ChatMessage, 'role' | 'toolInvocations'>[],
+  isStreaming: boolean,
+): AskedQuestion[] {
+  const last = messages.at(-1);
+  if (isStreaming || last?.role !== 'assistant') return [];
+  return (last.toolInvocations ?? []).flatMap((invocation) => askedQuestions(invocation) ?? []);
+}

package/src/lib/suggestions.ts

@@ -0,0 +1,53 @@
+import type { AliaSuggestion } from '../types';
+
+/**
+ * Which suggestions a draft gets, shared by the Alia app and the SDK chat so they offer the
+ * same rows: the welcome suggestions while the draft is short, and from two characters the
+ * search's matches with the typed part located inside each.
+ */
+
+/** Up to this many rows. */
+export const MAX_ROWS = 6;
+/** The draft length at which the search takes over from the welcome list. */
+export const SEARCH_FROM = 2;
+/** How long typing settles before the search is asked. */
+export const SEARCH_DEBOUNCE_MS = 200;
+
+export interface Completion<T extends AliaSuggestion = AliaSuggestion> {
+  suggestion: T;
+  /** The typed text's range inside `suggestion.text`, or an empty range. */
+  matchStart: number;
+  matchEnd: number;
+}
+
+/** Which rows to show for a draft: welcome while short, matches from two characters. */
+export function composerCompletions<T extends AliaSuggestion>(
+  draft: string,
+  welcome: readonly T[] | undefined,
+  matches: readonly T[] | undefined,
+): Completion<T>[] {
+  const query = draft.trim();
+  if (query.length < SEARCH_FROM) {
+    return (welcome ?? []).slice(0, MAX_ROWS).map((suggestion) => ({
+      suggestion,
+      matchStart: 0,
+      matchEnd: 0,
+    }));
+  }
+  const lower = query.toLowerCase();
+  const seen = new Set<string>();
+  const rows: Completion<T>[] = [];
+  for (const suggestion of matches ?? []) {
+    if (rows.length >= MAX_ROWS) break;
+    const text = suggestion.text.toLowerCase();
+    if (seen.has(text)) continue;
+    seen.add(text);
+    const start = text.indexOf(lower);
+    rows.push({
+      suggestion,
+      matchStart: start === -1 ? 0 : start,
+      matchEnd: start === -1 ? 0 : start + query.length,
+    });
+  }
+  return rows;
+}

package/src/lib/task-labels.ts

@@ -1,46 +1,14 @@
 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',
-]);
+/** Whether the catalogue names this tool itself; otherwise the label is made from its id. */
+function isNamed(kind: 'pill' | 'done', toolName: string): boolean {
+  const key = `tasks.tool.${kind}.${toolName}`;
+  return englishWorkLog(key) !== key;
+}
 
 /** 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}`);
+  if (isNamed('pill', toolName)) return t(`tasks.tool.pill.${toolName}`);
 
   // Oxy service tools: oxy_serviceName__toolName → "ServiceName"
   if (toolName.startsWith('oxy_')) {
@@ -61,7 +29,7 @@ export function getToolPillLabel(toolName: string, t: Translate = englishWorkLog
  * ("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)
+  return isNamed('done', toolName)
     ? t(`tasks.tool.done.${toolName}`)
     : getToolPillLabel(toolName, t);
 }

package/src/lib/use-after-delay.ts

@@ -0,0 +1,19 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * `active`, but only once it has held for `delay` ms; false again the moment it stops. For an
+ * indicator that must not flash for a state that ends at once (Alia "thinking" for the instant
+ * before she hands the turn to an agent, where the agent is the one that thinks).
+ */
+export function useAfterDelay(active: boolean, delay: number): boolean {
+  const [settled, setSettled] = useState(false);
+  useEffect(() => {
+    if (!active) {
+      setSettled(false);
+      return;
+    }
+    const timer = setTimeout(() => setSettled(true), delay);
+    return () => clearTimeout(timer);
+  }, [active, delay]);
+  return settled;
+}

package/src/lib/work-log.ts

@@ -10,6 +10,7 @@ import type { TaskListChip, TaskListStep, TaskListTask } from '@oxy.so/bloom/tas
 import type { WebSearchBrand, WebSearchSource, WebSearchStep } from '@oxy.so/bloom/web-search';
 import type { ToolInvocation } from '../types';
 import { extractCitationSources } from './citations';
+import { domainOf } from './domain';
 import { getToolDoneLabel, getToolPillLabel } from './task-labels';
 import { toolCallStatus } from './tool-call-status';
 import { englishWorkLog, type Translate } from './work-log-copy';
@@ -47,6 +48,7 @@ function resultOf(inv: Pick<ToolInvocation, 'result'>): Record<string, unknown>
 
 /** The research the live stream reports before the answer is persisted. */
 export interface LiveResearch {
+  isComplete?: boolean;
   currentQuery?: string;
   sourcesFound?: number;
   sources?: Array<{ id?: unknown; url?: unknown; title?: unknown }> | null;
@@ -63,14 +65,6 @@ function str(value: unknown): string | undefined {
   return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
 }
 
-function domainOf(url: string): string {
-  try {
-    return new URL(url).hostname;
-  } catch {
-    return url;
-  }
-}
-
 /** The site marks Bloom draws, by registrable domain. Anything else is a quiet dot. */
 const BRANDS: Array<[string, WebSearchBrand]> = [
   ['github.com', 'github'],
@@ -273,7 +267,7 @@ export function webSearchLog(
     mapped.push({
       arrived: true,
       step: {
-        label: t('chat.bloom.researching'),
+        label: t(research.isComplete ? 'chat.bloom.researched' : 'chat.bloom.researching'),
         query: str(research.currentQuery),
         icon: RiBookOpenLine,
         ...(found > 0 ? { meta: t('chat.bloom.sourceCount', { count: found }) } : {}),

package/src/tools.ts

@@ -2,7 +2,13 @@
 // Pure functions: the status of a call, the numbered sources of a research answer, the
 // words for a tool. They load no React Native, so a host's models and tests can use them.
 
-export { extractCitationSources } from './lib/citations';
+export {
+  citationLabel,
+  extractCitationSources,
+  linkifyCitations,
+  normalizeCitationMarkers,
+} from './lib/citations';
+export { domainOf } from './lib/domain';
 export type { CitationSource } from './lib/citations';
 export { getToolDoneLabel, getToolPillLabel } from './lib/task-labels';
 export {
@@ -10,6 +16,7 @@ export {
   askedQuestions,
   formatAnswers,
   isQuestionInvocation,
+  pendingQuestions,
 } from './lib/questions';
 export type { AskedOption, AskedQuestion, QuestionAnswer } from './lib/questions';
 export { toolCallStatus } from './lib/tool-call-status';

package/src/types.ts

@@ -1,12 +1,12 @@
 import type { ComponentType } from 'react';
 import type { SharedValue } from 'react-native-reanimated';
 
-// ── Welcome / Suggestion Types ──
+// ── Suggestion Types ──
 
-export interface WelcomeSuggestion {
+/** A line the person can pick: `text` is what is shown and what is sent. */
+export interface AliaSuggestion {
   id: string;
-  title: string;
-  description: string;
+  text: string;
 }
 
 // ── Chat Message Types ──
@@ -63,7 +63,8 @@ export interface ChatMessage {
   /** Cached TTS audio URL for read-aloud */
   audioUrl?: string;
   /** Delegated agent identity */
-  agentInfo?: { id: string; name: string; avatar: string | null };
+  /** `character` is the agent's look as the server stores it (JSON), parsed where it is drawn. */
+  agentInfo?: { id: string; name: string; character?: unknown };
 }
 
 export interface ToolInvocation {