@alia.onl/sdk 12.0.0 → 13.0.0

package/src/lib/citations.ts

@@ -54,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/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/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/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

@@ -48,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;
@@ -266,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,12 @@
 // 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';
@@ -11,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 {