@alia.onl/sdk 15.8.0 → 19.1.0

package/src/lib/participants.ts

@@ -0,0 +1,86 @@
+import type { AvatarCharacter } from '@oxy.so/bloom/agent-avatar';
+import type { AliaAgentProfile } from '../runtime/agents';
+import type { Message } from '../runtime/types';
+import { readAgentCharacter } from './agent-character';
+import { ALIA_AVATAR } from './alia-character';
+
+/** Somebody in the conversation who answers: its lead, or an agent the lead consulted. */
+export interface AliaParticipant {
+  id: string;
+  name: string;
+  handle?: string;
+  /** The 3D character it is drawn as. */
+  character: AvatarCharacter;
+  color?: string;
+}
+
+/** The conversation's lead: who greets, whose name is on the composer, who the header shows first. */
+export interface AliaLead extends AliaParticipant {
+  /** Alia herself, rather than an agent the chat was opened on. */
+  isAlia: boolean;
+  /** The agent's own greeting; Alia greets with the chat's labels. */
+  greeting?: string;
+  /** The agent's own starters, offered over the composer of an empty chat. */
+  starters: Array<{ title: string; prompt: string }>;
+}
+
+/** Who is in the conversation, as the header draws it: the lead, then whoever has joined. */
+export interface AliaChatParticipants {
+  lead: AliaLead;
+  /** The consulted agents that have joined the header, in the order they joined. */
+  joined: AliaParticipant[];
+}
+
+/** Alia as a lead. */
+export const ALIA_LEAD: AliaLead = {
+  id: 'alia',
+  name: 'Alia',
+  handle: 'alia',
+  character: ALIA_AVATAR,
+  isAlia: true,
+  starters: [],
+};
+
+/** The lead of a chat: the agent it was opened on (`agent={{ id }}`), or Alia. */
+export function leadOf(profile: AliaAgentProfile | null | undefined): AliaLead {
+  if (!profile) return ALIA_LEAD;
+  return {
+    id: profile.id,
+    name: profile.name,
+    handle: profile.handle,
+    character: readAgentCharacter(profile.character),
+    color: profile.color,
+    isAlia: false,
+    greeting: profile.greeting,
+    starters: profile.starters,
+  };
+}
+
+/** A consulted agent as a message carries it (`agentInfo`). */
+export function participantOf(agentInfo: NonNullable<Message['agentInfo']>): AliaParticipant {
+  return {
+    id: agentInfo.id,
+    name: agentInfo.name,
+    handle: agentInfo.handle,
+    character: readAgentCharacter(agentInfo.character),
+    color: agentInfo.color,
+  };
+}
+
+/**
+ * The agents that answered in `messages`, besides the lead, in the order they first did — each
+ * with whether its first answer is the one being streamed now (it is joining) or one already
+ * written (it was there when the chat opened).
+ */
+export function consultedAgents(
+  messages: readonly Message[],
+  leadId: string,
+): Array<{ participant: AliaParticipant; live: boolean }> {
+  const seen = new Map<string, { participant: AliaParticipant; live: boolean }>();
+  for (const message of messages) {
+    const info = message.agentInfo;
+    if (!info || info.id === leadId || seen.has(info.id)) continue;
+    seen.set(info.id, { participant: participantOf(info), live: message.isStreaming === true });
+  }
+  return [...seen.values()];
+}

package/src/lib/power-level-options.ts

@@ -0,0 +1,66 @@
+import type { ComposerPanelPermissionOption } from '@oxy.so/bloom/composer-panel';
+import { RiComputerLine } from '@oxy.so/bloom/icons/RiComputerLine';
+import { RiFireLine } from '@oxy.so/bloom/icons/RiFireLine';
+import { RiFlashlightLine } from '@oxy.so/bloom/icons/RiFlashlightLine';
+import { RiLightbulbLine } from '@oxy.so/bloom/icons/RiLightbulbLine';
+import { RiRocket2Line } from '@oxy.so/bloom/icons/RiRocket2Line';
+import { RiSparkling2Line } from '@oxy.so/bloom/icons/RiSparkling2Line';
+import { RiSpeedUpLine } from '@oxy.so/bloom/icons/RiSpeedUpLine';
+import { RiVipCrownLine } from '@oxy.so/bloom/icons/RiVipCrownLine';
+import { POWER_LEVELS, type PowerLevel } from '../runtime/power-levels';
+import type { Translate } from './copy';
+
+/**
+ * The power-level selector, in the shape Bloom's composer mode selector takes.
+ *
+ * Alia's users choose how much power a turn gets, never which hosted model answers it: Oxy picks
+ * the model of the chosen level for every request. The selector is `ComposerPill`'s mode picker —
+ * Bloom's own radio menu of a label, a short description and an icon per mode — so the seven
+ * levels read the same way every Bloom mode selector does. Models running on the person's OWN
+ * devices follow the levels: that is their machine, not a model Alia offers, and which devices
+ * are connected is the host's to say.
+ */
+
+type IconComponent = ComposerPanelPermissionOption['icon'];
+
+/** One glyph per level, rising with the power it stands for. */
+export const POWER_LEVEL_ICONS: Record<PowerLevel, IconComponent> = {
+  auto: RiSparkling2Line,
+  instant: RiFlashlightLine,
+  medium: RiSpeedUpLine,
+  high: RiLightbulbLine,
+  xhigh: RiFireLine,
+  pro: RiRocket2Line,
+  ultra: RiVipCrownLine,
+};
+
+/** A model running on one of the person's own devices, offered after the levels. */
+export interface DeviceModel {
+  /** What a request carries as `model` (`local/<runtime>/<model>`). */
+  id: string;
+  /** The tag the person knows it by, e.g. `llama3.1:8b`. */
+  name: string;
+  /** Which of their devices is running it. */
+  deviceLabel: string;
+}
+
+/** The selector's options: the seven levels, then the person's device models. */
+export function buildPowerLevelOptions(
+  t: Translate,
+  deviceModels: readonly DeviceModel[],
+): ComposerPanelPermissionOption[] {
+  return [
+    ...POWER_LEVELS.map((level) => ({
+      id: level,
+      label: t(`powerLevels.${level}.label`),
+      description: t(`powerLevels.${level}.description`),
+      icon: POWER_LEVEL_ICONS[level],
+    })),
+    ...deviceModels.map((model) => ({
+      id: model.id,
+      label: model.name,
+      description: t('powerLevels.onDevice', { device: model.deviceLabel }),
+      icon: RiComputerLine,
+    })),
+  ];
+}

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 { ChatMessage, ToolInvocation } from '../types';
+import type { Message, ToolInvocation } from '../runtime/types';
 
 /** The tool's name on the wire. */
 export const ASK_USER_QUESTION_TOOL = 'askUserQuestion';
@@ -83,7 +83,7 @@ export function formatAnswers(questions: AskedQuestion[], answers: QuestionAnswe
  * is the answer, so nothing is pending then.
  */
 export function pendingQuestions(
-  messages: readonly Pick<ChatMessage, 'role' | 'toolInvocations'>[],
+  messages: readonly Pick<Message, 'role' | 'toolInvocations'>[],
   isStreaming: boolean,
 ): AskedQuestion[] {
   const last = messages.at(-1);

package/src/lib/task-labels.ts

@@ -1,13 +1,13 @@
-import { englishWorkLog, type Translate } from './work-log-copy';
+import { englishCopy, type Translate } from './copy';
 
 /** 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;
+  return englishCopy(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 {
+export function getToolPillLabel(toolName: string, t: Translate = englishCopy): string {
   if (isNamed('pill', toolName)) return t(`tasks.tool.pill.${toolName}`);
 
   // Oxy service tools: oxy_serviceName__toolName → "ServiceName"
@@ -28,7 +28,7 @@ export function getToolPillLabel(toolName: string, t: Translate = englishWorkLog
  * `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 {
+export function getToolDoneLabel(toolName: string, t: Translate = englishCopy): string {
   return isNamed('done', toolName)
     ? t(`tasks.tool.done.${toolName}`)
     : getToolPillLabel(toolName, t);

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

@@ -1,4 +1,4 @@
-import type { ToolInvocation } from '../types';
+import type { ToolInvocation } from '../runtime/types';
 
 /**
  * Where a tool call stands:

package/src/lib/tool-icons.ts

@@ -0,0 +1,36 @@
+import type { BloomIconComponent } from '@oxy.so/bloom/icons';
+import { RiCalendarLine } from '@oxy.so/bloom/icons/RiCalendarLine';
+import { RiChat3Line } from '@oxy.so/bloom/icons/RiChat3Line';
+import { RiDatabase2Line } from '@oxy.so/bloom/icons/RiDatabase2Line';
+import { RiFileTextLine } from '@oxy.so/bloom/icons/RiFileTextLine';
+import { RiGlobalLine } from '@oxy.so/bloom/icons/RiGlobalLine';
+import { RiLightbulbFlashLine } from '@oxy.so/bloom/icons/RiLightbulbFlashLine';
+import { RiLink } from '@oxy.so/bloom/icons/RiLink';
+import { RiSearchLine } from '@oxy.so/bloom/icons/RiSearchLine';
+import { RiSendPlaneLine } from '@oxy.so/bloom/icons/RiSendPlaneLine';
+import { RiSettings3Line } from '@oxy.so/bloom/icons/RiSettings3Line';
+import { RiUserLine } from '@oxy.so/bloom/icons/RiUserLine';
+
+/** The glyph a tool's step carries in the thought panel, by tool name. */
+const TOOL_ICONS: ReadonlyMap<string, BloomIconComponent> = new Map([
+  ['webSearch', RiSearchLine],
+  ['scrapeURL', RiLink],
+  ['getTimeline', RiCalendarLine],
+  ['searchKnowledgeBase', RiDatabase2Line],
+  ['webScraper', RiGlobalLine],
+  ['browse', RiGlobalLine],
+  ['sendWhatsAppMessage', RiChat3Line],
+  ['getWhatsAppChats', RiChat3Line],
+  ['getWhatsAppMessages', RiChat3Line],
+  ['sendTelegramMessage', RiSendPlaneLine],
+  ['getCurrentDate', RiCalendarLine],
+  ['generateFile', RiFileTextLine],
+  ['saveUserMemory', RiLightbulbFlashLine],
+  ['updateUserPreferences', RiSettings3Line],
+  ['updateUserContext', RiUserLine],
+]);
+
+/** A tool's glyph; a tool with none of its own reads as the web it reached. */
+export function getToolIcon(toolName: string): BloomIconComponent {
+  return TOOL_ICONS.get(toolName) ?? RiGlobalLine;
+}

package/src/lib/tool-renderers.tsx

@@ -0,0 +1,48 @@
+import { createContext, type ReactNode, useContext } from 'react';
+
+/**
+ * A tool's result as a host's renderer receives it (`docs/agent-embedding.md` §3): the app and the
+ * tool its canonical name names, what it was called with and what it returned.
+ */
+export interface AliaToolResult {
+  /** The app of `oxy_<app>__<tool>` / `self_<app>__<tool>`. */
+  app: string;
+  tool: string;
+  toolCallId: string;
+  input?: Record<string, unknown>;
+  output: unknown;
+  /** The consulted agent that called it; absent for the lead's own calls. */
+  agentId?: string;
+}
+
+/**
+ * The host's own drawings of catalogue tools' results, keyed `<app>:<tool>` — `homiio:searchListings`
+ * for `oxy_homiio__searchListings`. Drawn before the generic tool card, for the lead's calls and a
+ * consulted agent's alike.
+ */
+export type AliaToolRenderers = Readonly<Record<string, (result: AliaToolResult) => ReactNode>>;
+
+/**
+ * `oxy_<app>__<tool>` or `self_<app>__<tool>`: the only names a renderer is keyed from. The app
+ * part is an Oxy app slug; the tool part is whatever follows the separator.
+ */
+const CANONICAL_TOOL = /^(?:oxy|self)_([a-z][a-z0-9-]{0,63})__([A-Za-z0-9_-]+)$/;
+
+/** The app and tool of a canonical catalogue tool name, or `null` for any other name. */
+export function parseCatalogueTool(toolName: string): { app: string; tool: string } | null {
+  const match = CANONICAL_TOOL.exec(toolName);
+  return match ? { app: match[1], tool: match[2] } : null;
+}
+
+/** The renderer key of a tool name (`<app>:<tool>`), or `null` when it is not a catalogue tool. */
+export function toolRendererKey(toolName: string): string | null {
+  const parsed = parseCatalogueTool(toolName);
+  return parsed ? `${parsed.app}:${parsed.tool}` : null;
+}
+
+const RenderersContext = createContext<AliaToolRenderers>({});
+
+export const AliaToolRenderersProvider = RenderersContext.Provider;
+
+/** The host's renderers, `{}` when it brought none. */
+export const useToolRenderers = () => useContext(RenderersContext);

package/src/lib/turn-state.ts

@@ -1,9 +1,9 @@
-import type { ChatMessage } from '../types';
+import type { Message } from '../runtime/types';
 import type { AliaAvatarState } from '../components/AliaAvatar';
 
 /** What a chat turn is doing, from its messages: the one reading the header mark and every button share. */
 export function turnActivityState(
-  messages: ReadonlyArray<ChatMessage>,
+  messages: ReadonlyArray<Message>,
   isStreaming: boolean,
 ): AliaAvatarState {
   if (!isStreaming) return 'idle';

package/src/lib/voice-call-request.ts

@@ -0,0 +1,49 @@
+import { create } from 'zustand';
+
+/** A call somebody asked for, waiting for the screen that shows its conversation. */
+export interface VoiceCallRequest {
+  readonly conversationId: string;
+  readonly accountId: string | null;
+  readonly at: number;
+}
+
+/** How long a request waits for its screen. A navigation that never arrives must not open a call later. */
+export const CALL_REQUEST_TTL_MS = 15_000;
+
+interface VoiceCallRequestStore {
+  request: VoiceCallRequest | null;
+  ask: (conversationId: string, accountId: string | null) => void;
+  clear: () => void;
+}
+
+/**
+ * Where a call is asked for, apart from where it opens.
+ *
+ * Starting a call and showing it are the same thing when the conversation is already on screen,
+ * and two screens apart when it is not: a new-chat route makes the conversation and the host
+ * navigates to it. Both go the same way. The launcher AND the screen of the conversation meet
+ * here — it asks, and whichever launcher is mounted for that conversation (that account, in time)
+ * takes the request and opens the call. The sheet, the screen and the app share this one path.
+ */
+export const useVoiceCallRequests = create<VoiceCallRequestStore>((set) => ({
+  request: null,
+  ask: (conversationId, accountId) =>
+    set({ request: { conversationId, accountId, at: Date.now() } }),
+  clear: () => set({ request: null }),
+}));
+
+/** Whether `request` is for this conversation and account, and still worth opening. */
+export function isRequestFor(
+  request: VoiceCallRequest | null,
+  conversationId: string | undefined,
+  accountId: string | null,
+  now = Date.now(),
+): boolean {
+  return (
+    request !== null &&
+    conversationId !== undefined &&
+    request.conversationId === conversationId &&
+    request.accountId === accountId &&
+    now - request.at <= CALL_REQUEST_TTL_MS
+  );
+}

package/src/lib/voice-call.ts

@@ -77,6 +77,11 @@ export interface VoiceCallOptions {
   readonly apiUrl: string;
   /** The person's Oxy session token, read at connect and every few minutes. */
   readonly getToken: () => string | null;
+  /**
+   * The host's Oxy app assertion, sent with the first `auth` of each socket so
+   * an agent Oxy confines to an app opens only there (ADR 0021). Absent: none.
+   */
+  readonly getAppAssertion?: () => Promise<string | null>;
   readonly conversationId: string;
   readonly agentId?: string;
   readonly voice: ProductVoice;
@@ -88,8 +93,6 @@ export interface VoiceCallOptions {
   readonly onChange: (snapshot: VoiceCallSnapshot) => void;
   /** Alia stored messages of the call in the conversation. */
   readonly onMessagesSaved?: (conversationId: string, messageIds: readonly string[]) => void;
-  /** A tool filed an action for the person's OK; the card is in the conversation. */
-  readonly onApprovalRequested?: (toolName: string) => void;
   readonly tokenRefreshMs?: number;
   readonly resumeRetryMs?: number;
 }
@@ -113,6 +116,13 @@ export class VoiceCall {
   private readonly options: VoiceCallOptions;
   private state: VoiceCallState = { kind: 'idle' };
   private messages: VoiceMessage[] = [];
+  /**
+   * Each message's text by the item it was spoken in, in the order the items
+   * began: an assistant turn that called a tool is one message of two items.
+   */
+  private readonly itemTexts = new Map<string, Map<string, string>>();
+  /** The message each item belongs to. */
+  private readonly messageOfItem = new Map<string, string>();
   private muted = false;
   private endingSoonMs: number | null = null;
   private model: VoiceCallSnapshot['model'] = null;
@@ -246,7 +256,23 @@ export class VoiceCall {
         return;
       }
       this.lastToken = token;
-      socket.send(JSON.stringify({ type: 'auth', token } satisfies VoiceClientEvent));
+      const getAppAssertion = this.options.getAppAssertion;
+      if (getAppAssertion === undefined) {
+        socket.send(JSON.stringify({ type: 'auth', token } satisfies VoiceClientEvent));
+        return;
+      }
+      void getAppAssertion()
+        .catch(() => null)
+        .then((appAssertion) => {
+          if (this.socket !== socket || this.finished || socket.readyState !== OPEN) return;
+          socket.send(
+            JSON.stringify({
+              type: 'auth',
+              token,
+              ...(appAssertion ? { appAssertion } : {}),
+            } satisfies VoiceClientEvent),
+          );
+        });
     };
     socket.onmessage = (event) => {
       if (this.socket !== socket || this.finished) return;
@@ -362,10 +388,10 @@ export class VoiceCall {
           this.setState({ kind: 'thinking' });
         return;
       case 'transcript.delta':
-        this.upsertMessage(event.role, event.itemId, (previous) => previous + event.text, true);
+        this.upsertMessage(event, (previous) => previous + event.text, true);
         return;
       case 'transcript.done':
-        this.upsertMessage(event.role, event.itemId, () => event.text, false);
+        this.upsertMessage(event, () => event.text, false);
         return;
       case 'assistant.audio_done':
         return;
@@ -379,11 +405,13 @@ export class VoiceCall {
         if (this.state.kind === 'thinking' && this.playingItem === null) this.afterSpeech();
         return;
       case 'tool.started':
+        this.recordTool(event, 'call');
         this.activeTools.set(event.callId, event.name);
         this.toolRan = true;
         if (LIVE.has(this.state.kind)) this.setState({ kind: 'using-tool', tool: event.name });
         return;
       case 'tool.finished': {
+        this.recordTool(event, 'result');
         this.activeTools.delete(event.callId);
         if (this.state.kind !== 'using-tool') return;
         const still = [...this.activeTools.values()].at(-1);
@@ -392,9 +420,6 @@ export class VoiceCall {
         );
         return;
       }
-      case 'approval.requested':
-        this.options.onApprovalRequested?.(event.toolName);
-        return;
       case 'messages.saved':
         this.options.onMessagesSaved?.(event.conversationId, event.messageIds);
         return;
@@ -455,41 +480,79 @@ export class VoiceCall {
     this.finish({ kind: 'ended', reason });
   }
 
+  /**
+   * One message per `messageId`, the id the server stores and announces it
+   * under, so the stored copy that reaches the thread is this message, not a
+   * second one. Its text is its items' texts in order.
+   */
   private upsertMessage(
-    role: 'user' | 'assistant',
-    itemId: string,
-    content: (previous: string) => string,
+    event: { role: 'user' | 'assistant'; messageId: string; itemId: string },
+    text: (previous: string) => string,
     isStreaming: boolean,
   ): void {
-    const id = `${role}-${itemId}`;
-    const index = this.messages.findIndex((message) => message.id === id);
-    if (index === -1) {
-      this.messages = [
-        ...this.messages,
-        {
-          id,
-          role,
-          ...(role === 'assistant' ? { speaker: 'primary' as const } : {}),
-          content: content(''),
-          timestamp: Date.now(),
-          isStreaming,
-        },
-      ];
-    } else {
-      const previous = this.messages[index]!;
-      const next = [...this.messages];
-      next[index] = { ...previous, content: content(previous.content), isStreaming };
-      this.messages = next;
-    }
+    const { messageId, itemId } = event;
+    const items = this.itemTexts.get(messageId) ?? new Map<string, string>();
+    this.itemTexts.set(messageId, items);
+    this.messageOfItem.set(itemId, messageId);
+    items.set(itemId, text(items.get(itemId) ?? ''));
+    const content = [...items.values()].filter((part) => part !== '').join(' ');
+    this.writeMessage(messageId, event.role, (message) => ({ ...message, content, isStreaming }));
+  }
+
+  /**
+   * A tool the answer ran, inside the answer's message, by name and state: the
+   * device never receives its arguments or result, and the stored message that
+   * carries them replaces this one once it is saved.
+   */
+  private recordTool(
+    event: { messageId: string; callId: string; name: string },
+    state: 'call' | 'result',
+  ): void {
+    this.writeMessage(event.messageId, 'assistant', (message) => {
+      const invocation = { toolCallId: event.callId, toolName: event.name, state };
+      const tools = message.toolInvocations ?? [];
+      const index = tools.findIndex((tool) => tool.toolCallId === event.callId);
+      return {
+        ...message,
+        toolInvocations:
+          index === -1
+            ? [...tools, invocation]
+            : tools.map((tool, at) => (at === index ? invocation : tool)),
+      };
+    });
+  }
+
+  private writeMessage(
+    messageId: string,
+    role: 'user' | 'assistant',
+    change: (message: VoiceMessage) => VoiceMessage,
+  ): void {
+    const index = this.messages.findIndex((message) => message.id === messageId);
+    const current: VoiceMessage =
+      index === -1
+        ? {
+            id: messageId,
+            role,
+            ...(role === 'assistant' ? { speaker: 'primary' as const } : {}),
+            content: '',
+            timestamp: Date.now(),
+            isStreaming: false,
+          }
+        : this.messages[index]!;
+    const next = change(current);
+    this.messages =
+      index === -1
+        ? [...this.messages, next]
+        : this.messages.map((message, at) => (at === index ? next : message));
     this.emit();
   }
 
   private settleStreaming(itemId: string | null): void {
-    if (itemId === null) return;
-    const id = `assistant-${itemId}`;
-    if (!this.messages.some((message) => message.id === id && message.isStreaming)) return;
+    const messageId = itemId === null ? undefined : this.messageOfItem.get(itemId);
+    if (messageId === undefined) return;
+    if (!this.messages.some((message) => message.id === messageId && message.isStreaming)) return;
     this.messages = this.messages.map((message) =>
-      message.id === id ? { ...message, isStreaming: false } : message,
+      message.id === messageId ? { ...message, isStreaming: false } : message,
     );
     this.emit();
   }

package/src/lib/voice-controls-labels.ts

@@ -0,0 +1,31 @@
+// The call bar's words, apart from the component so the chat's labels can hold them without
+// reaching React Native.
+
+/** 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;
+  end: string;
+}
+
+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',
+  end: 'End',
+};