@alia.onl/sdk 12.0.0 → 13.1.0

package/src/components/QuestionCard.tsx

@@ -5,31 +5,21 @@ import { type AskedQuestion, formatAnswers } from '../lib/questions';
 
 interface QuestionCardProps {
   questions: AskedQuestion[];
-  /** Sends the answers as the person's next message. Absent: the card is read-only. */
-  onSubmit?: (message: string) => void;
+  /** Sends the answers as the person's next message. */
+  onSubmit: (message: string) => void;
+  /** Shows the corner dismiss; typing a reply in the composer answers just as well. */
+  onDismiss?: () => void;
 }
 
 /** Ids are positions: the questions are the model's, and carry none. */
 const idOf = (index: number) => `q${index}`;
 
 /**
- * The questions Alia asked: Bloom's `Questionnaire` while the person can still answer, and
- * the questions as plain lines once they have (the answer is their message, right below).
- * Typing a reply in the composer answers just as well, which is why there is no dismiss.
+ * The questions Alia asked, as Bloom's `Questionnaire`. Give it to the composer's `question`
+ * slot while the person can still answer: it docks above the composer, where they are about
+ * to type, rather than sitting in the thread.
  */
-export function QuestionCard({ questions, onSubmit }: QuestionCardProps) {
-  if (onSubmit === undefined) {
-    return (
-      <View className="my-2 gap-1">
-        {questions.map((q, i) => (
-          // The model's questions never reorder: the position is the identity.
-          // biome-ignore lint/suspicious/noArrayIndexKey: see above
-          <Muted key={i}>{q.question}</Muted>
-        ))}
-      </View>
-    );
-  }
-
+export function QuestionCard({ questions, onSubmit, onDismiss }: QuestionCardProps) {
   const complete = (answers: QuestionnaireAnswers) =>
     onSubmit(
       formatAnswers(
@@ -42,21 +32,33 @@ export function QuestionCard({ questions, onSubmit }: QuestionCardProps) {
     );
 
   return (
-    <View className="my-2">
-      <Questionnaire
-        questions={questions.map((q, i) => ({
-          id: idOf(i),
-          question: q.question,
-          select: q.multiSelect ? 'multiple' : 'single',
-          other: true,
-          options: q.options.map((option, index) => ({
-            value: String(index),
-            label: option.label,
-            description: option.description,
-          })),
-        }))}
-        onComplete={complete}
-      />
+    <Questionnaire
+      questions={questions.map((q, i) => ({
+        id: idOf(i),
+        question: q.question,
+        select: q.multiSelect ? 'multiple' : 'single',
+        other: true,
+        options: q.options.map((option, index) => ({
+          value: String(index),
+          label: option.label,
+          description: option.description,
+        })),
+      }))}
+      onComplete={complete}
+      onDismiss={onDismiss}
+    />
+  );
+}
+
+/** The questions Alia asked, as plain lines: the thread's record of them once they are answered. */
+export function AskedQuestions({ questions }: { questions: AskedQuestion[] }) {
+  return (
+    <View className="my-2 gap-1">
+      {questions.map((q, i) => (
+        // The model's questions never reorder: the position is the identity.
+        // biome-ignore lint/suspicious/noArrayIndexKey: see above
+        <Muted key={i}>{q.question}</Muted>
+      ))}
     </View>
   );
 }

package/src/components/ThinkingBlock.tsx

@@ -1,6 +1,5 @@
 import { AgentThinking } from '@oxy.so/bloom/agent-thinking';
 import { useEffect, useRef, useState } from 'react';
-import { View } from 'react-native';
 import { useLabels } from '../lib/labels';
 import { AliaMarkdown } from './Markdown';
 
@@ -12,10 +11,11 @@ interface ThinkingBlockProps {
 }
 
 /**
- * A turn's reasoning: Bloom's `AgentThinking` as a disclosure (live while it
- * streams, "Thought for N seconds" once done), with the text set as Markdown.
- * Open and close, the indicator and the chevron are Bloom's; this only counts
- * how long the stream ran, because the message carries no duration.
+ * A turn's reasoning, once it is done: Bloom's `AgentThinking` as a closed disclosure, "Thought
+ * for N seconds", with the text set as Markdown. While the reasoning streams it draws nothing:
+ * the avatar under the reply is the one indicator that the turn is thinking
+ * (`AgentReplyIdentity`), and a second one beside it is noise. It still counts how long the stream
+ * ran, because the message carries no duration.
  */
 export function ThinkingBlock({ text, streaming }: ThinkingBlockProps) {
   const labels = useLabels();
@@ -33,15 +33,11 @@ export function ThinkingBlock({ text, streaming }: ThinkingBlockProps) {
 
   const finishedLabel = seconds ? labels.thoughtFor(seconds) : labels.reasoning;
 
+  if (streaming) return null;
+
   return (
-    <AgentThinking
-      variant="stars"
-      thinking={streaming}
-      label={streaming ? undefined : finishedLabel}
-    >
-      <View style={{ opacity: streaming ? 0.8 : 1 }}>
-        <AliaMarkdown content={text} />
-      </View>
+    <AgentThinking thinking={false} label={finishedLabel}>
+      <AliaMarkdown content={text} />
     </AgentThinking>
   );
 }

package/src/components/VoiceModeIcon.tsx

@@ -1,10 +1,18 @@
-import Entypo from '@expo/vector-icons/Entypo';
-import type { BloomIconComponent } from '@oxy.so/bloom/icons';
+import Svg, { Path } from 'react-native-svg';
+
+/** The glyph's outline: a speaker cone with three rays, drawn on a 512 grid (y down). */
+const GLYPH =
+  'M136 117Q158 95 212.5 119.5Q267 144 323 200Q379 256 403.5 311Q428 366 406 387Q396 398 373 414Q350 430 313.5 447Q277 464 240 472.5Q203 481 162 472.5Q121 464 90.5 433.5Q60 403 51 361.5Q42 320 50.5 283Q59 246 76.5 209.5Q94 173 109.5 150.5Q125 128 136 117ZM348.5 361.5Q348.5 361.5 358.25 364.25Q368 367 373 362.5Q378 358 372.5 338Q367 318 347 286Q327 254 298 225Q269 196 237 176.5Q205 157 185.5 151Q166 145 161 150Q156 155 162 174.5Q168 194 187.5 226Q207 258 236 287.5Q265 317 297 336.5Q329 356 348.5 361.5ZM395 153Q388 161 377 161Q366 161 358.5 153.5Q351 146 351 135Q351 124 359 117L408 68Q415 61 425.5 61Q436 61 443.5 68.5Q451 76 451 86.5Q451 97 444 104ZM285 97Q272 90 272 75Q272 68 275 62L303 13Q310 0 325 0Q336 0 343.5 7.5Q351 15 351 26Q351 32 347 38L320 87Q312 101 297 101Q291 101 285 97ZM509 174Q512 180 512 187Q512 202 499 209L449 236Q443 240 437 240Q426 240 418.5 232.5Q411 225 411 214Q411 199 424 192L474 165Q480 161 486 161Q501 161 509 174Z';
 
 /**
- * The glyph of Alia's voice button: Entypo's `sound`. Remix has no equivalent, so it is
- * handed Bloom's icon contract (`width` / `fill`) for a Bloom `Button` to size and colour.
+ * The glyph of Alia's voice button: the speaker with rays the button has always worn. Bloom has no
+ * equivalent, so it is drawn here against Bloom's icon contract (`width` / `fill`) for a Bloom
+ * `Button` to size and colour.
  */
-export const VoiceModeIcon: BloomIconComponent = ({ width = 18, fill }) => (
-  <Entypo name="sound" size={width} color={fill} />
-);
+export function VoiceModeIcon({ width = 18, fill }: { width?: number; fill?: string }) {
+  return (
+    <Svg width={width} height={width} viewBox="23 -17 512 512">
+      <Path d={GLYPH} fill={fill} />
+    </Svg>
+  );
+}

package/src/components/voice/VoiceControls.tsx

@@ -1,11 +1,12 @@
 /**
- * Bottom voice control bar that replaces the composer when voice mode is active.
- * Contains status text and Bloom's mute/end call controls.
+ * Bottom voice control bar that replaces the composer when voice mode is active: the status
+ * text over Bloom's own `VoiceControls` (microphone and end), the controls of Bloom's voice
+ * mode, not a call's.
  */
 
-import { CallControls } from '@oxy.so/bloom/call-ui';
 import { Loading } from '@oxy.so/bloom/loading';
 import { Text } from '@oxy.so/bloom/typography';
+import { VoiceControls as BloomVoiceControls, type VoiceState } from '@oxy.so/bloom/voice';
 import { View } from 'react-native';
 import type { RoomState, AgentState } from '../../types';
 
@@ -60,6 +61,13 @@ function getStatusText(
   return '';
 }
 
+/** What Bloom's voice controls call the call's state: the microphone is only live while it is. */
+function voiceStateOf(roomState: RoomState, agentState: AgentState): VoiceState {
+  if (roomState === 'error') return 'error';
+  if (roomState !== 'connected') return 'idle';
+  return agentState === 'idle' ? 'listening' : agentState;
+}
+
 export function VoiceControls({
   roomState,
   agentState,
@@ -84,13 +92,13 @@ export function VoiceControls({
       ) : null}
 
       {roomState === 'connected' ? (
-        <CallControls
+        <BloomVoiceControls
+          state={voiceStateOf(roomState, agentState)}
           muted={isMuted}
-          onMutedChange={onToggleMute}
-          onEndCall={onEnd}
-          // TODO(bloom): `CallControls` draws its captions for a dark call stage, so on the
-          // chat's light surface they vanish. The buttons keep their accessible names.
-          labels={{ mute: labels.mute, unmute: labels.unmute, endCall: labels.end }}
+          // Called with nothing: Bloom hands its handlers the next value or the press, and
+          // `onToggleMute` / `onEnd` of a session take optional arguments of their own.
+          onMutedChange={() => onToggleMute()}
+          onEnd={() => onEnd()}
         />
       ) : null}
 

package/src/hooks/useAliaChat.ts

@@ -3,12 +3,18 @@ import { useOxy } from '@oxy.so/services/ui/client';
 import type { ChatMessage, ToolInvocation } from '../types';
 import { getTextFromContent, type MessageContent } from '../lib/content-utils';
 import { resolveModelId } from '../lib/catalogue';
+import { agentMessageId, delegatedAgent } from '../lib/delegation';
 import { streamAliaChat } from '../lib/chat-transport';
 import type { AliaChatStreamEvent } from '../lib/chat-stream';
 
 const API_URL = process.env.EXPO_PUBLIC_ALIA_API_URL ?? 'https://api.alia.onl';
 
 export interface UseAliaChatOptions {
+  /**
+   * The agents the host knows, with their look: a delegation's thinking avatar is drawn from here
+   * until the agent's answer brings its own. Without it (or for an agent it lacks) the default look.
+   */
+  agents?: ReadonlyArray<{ id: string; character?: unknown }>;
   /**
    * Base URL the hook sends its requests to. Defaults to
    * `EXPO_PUBLIC_ALIA_API_URL`, then `https://api.alia.onl`.
@@ -57,6 +63,10 @@ export interface UseAliaChatReturn {
   isStreaming: boolean;
   stop: () => void;
   clear: () => void;
+  /** The person accepted a proposed plan; the card collapses to "approved". */
+  approvePlan: (planId: string) => void;
+  /** The person cancelled a proposed plan: the card collapses to "cancelled" and the turn stops. */
+  rejectPlan: (planId: string) => void;
   error: string | null;
 }
 
@@ -70,6 +80,8 @@ interface PendingUpdates {
   content: string;
   reasoning: string;
   tools: ToolInvocation[];
+  /** How many delegated agents have answered in this turn. */
+  agentAnswers: number;
   timer: ReturnType<typeof setTimeout> | null;
 }
 
@@ -118,6 +130,8 @@ function waitWithAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T>
  */
 export function useAliaChat(options: UseAliaChatOptions = {}): UseAliaChatReturn {
   const { apiUrl = API_URL, model, clientContext, accessToken: accessTokenProp } = options;
+  const directoryRef = useRef(new Map<string, { id: string; character?: unknown }>());
+  directoryRef.current = new Map((options.agents ?? []).map((agent) => [agent.id, agent]));
   const requestUrl = '/v1/chat/completions';
 
   const { oxyServices } = useOxy();
@@ -168,6 +182,75 @@ export function useAliaChat(options: UseAliaChatOptions = {}): UseAliaChatReturn
     });
   }, []);
 
+  /**
+   * An agent's message of this turn, before Alia's own: opened empty by the call that sends for the
+   * agent, filled by its answer. Without an open one, an answer makes a message of its own.
+   */
+  const insertAgentMessage = useCallback(
+    (
+      assistantId: string,
+      agent: { id: string; name: string; character?: unknown },
+      content: string,
+    ) => {
+      if (!mountedRef.current) return;
+      const id = agentMessageId(assistantId, agent.id);
+      setMessages((previous) => {
+        const open = previous.find((message) => message.id === id);
+        let updated: ChatMessage[];
+        if (open && (content === '' || getTextFromContent(open.content) === '')) {
+          // Already open: an answer fills it; a second call to the same agent changes nothing.
+          if (content === '') return previous;
+          // The answer carries the look the server has now: it replaces the one the call guessed.
+          updated = previous.map((message) =>
+            message === open
+              ? {
+                  ...open,
+                  content,
+                  agentInfo: {
+                    id: agent.id,
+                    name: agent.name,
+                    character: agent.character ?? open.agentInfo?.character,
+                  },
+                }
+              : message,
+          );
+        } else {
+          const message: ChatMessage = {
+            id: open ? `${id}-${previous.length}` : id,
+            role: 'assistant',
+            content,
+            createdAt: Date.now(),
+            agentInfo: { id: agent.id, name: agent.name, character: agent.character },
+          };
+          const at = previous.findIndex((candidate) => candidate.id === assistantId);
+          updated = [...previous];
+          updated.splice(at < 0 ? updated.length : at, 0, message);
+        }
+        messagesRef.current = updated;
+        return updated;
+      });
+    },
+    [],
+  );
+
+  /** A turn that ends with an agent never answering leaves no empty message of the agent's. */
+  const removeUnansweredAgents = useCallback((assistantId: string) => {
+    if (!mountedRef.current) return;
+    setMessages((previous) => {
+      const updated = previous.filter(
+        (message) =>
+          !(
+            message.agentInfo !== undefined &&
+            message.id.startsWith(`${assistantId}-agent-`) &&
+            getTextFromContent(message.content).trim() === ''
+          ),
+      );
+      if (updated.length === previous.length) return previous;
+      messagesRef.current = updated;
+      return updated;
+    });
+  }, []);
+
   const flushPendingUpdates = useCallback(
     (pending: PendingUpdates) => {
       const content = pending.content;
@@ -310,6 +393,7 @@ export function useAliaChat(options: UseAliaChatOptions = {}): UseAliaChatReturn
         content: '',
         reasoning: '',
         tools: [],
+        agentAnswers: 0,
         timer: null,
       };
       pendingRef.current = pending;
@@ -339,6 +423,15 @@ export function useAliaChat(options: UseAliaChatOptions = {}): UseAliaChatReturn
             if (index < 0) pending.tools = [...pending.tools, invocation];
             else pending.tools[index] = invocation;
             flushPendingUpdates(pending);
+            // A call to an agent opens the agent's message at once: empty, thinking, until it answers.
+            const agent = delegatedAgent(invocation);
+            // The call names the agent; its look is the host's directory's, until the answer brings the server's.
+            if (agent)
+              insertAgentMessage(
+                pending.assistantId,
+                { ...agent, character: directoryRef.current.get(agent.id)?.character },
+                '',
+              );
             return;
           }
           case 'tool_result': {
@@ -373,11 +466,14 @@ export function useAliaChat(options: UseAliaChatOptions = {}): UseAliaChatReturn
               },
             }));
             return;
-          case 'agent_answer':
-            pending.content += event.content;
-            updateAssistant(pending.assistantId, () => ({ agentInfo: event.agent }));
-            scheduleFlush(pending);
+          case 'agent_answer': {
+            // A delegated agent speaks as itself: its answer is its own message, placed before
+            // Alia's reply, as the Alia app places it. The call that sent for it already opened
+            // the message; an answer with no call opens it. Several agents are several messages.
+            pending.agentAnswers++;
+            insertAgentMessage(pending.assistantId, event.agent, event.content);
             return;
+          }
         }
       };
 
@@ -409,6 +505,9 @@ export function useAliaChat(options: UseAliaChatOptions = {}): UseAliaChatReturn
       } finally {
         cancelPendingTimer(pending);
         flushPendingUpdates(pending);
+        removeUnansweredAgents(pending.assistantId);
+        // Alia said nothing herself after handing the turn over: no empty reply under the answers.
+        if (pending.agentAnswers > 0) removeEmptyAssistant(pending.assistantId);
         linked.dispose();
         if (pendingRef.current === pending) pendingRef.current = null;
         if (activeRequestRef.current?.key === request.key) {
@@ -427,6 +526,8 @@ export function useAliaChat(options: UseAliaChatOptions = {}): UseAliaChatReturn
       oxyServices,
       requestUrl,
       removeEmptyAssistant,
+      removeUnansweredAgents,
+      insertAgentMessage,
       scheduleFlush,
       updateAssistant,
     ],
@@ -439,5 +540,23 @@ export function useAliaChat(options: UseAliaChatOptions = {}): UseAliaChatReturn
     setError(null);
   }, [stop]);
 
-  return { messages, setMessages, send, isStreaming, stop, clear, error };
+  const decidePlan = useCallback((planId: string, decision: 'approved' | 'rejected') => {
+    setMessages((prev) =>
+      prev.map((message) =>
+        message.pendingPlan?.planId === planId
+          ? { ...message, pendingPlan: { ...message.pendingPlan, [decision]: true } }
+          : message,
+      ),
+    );
+  }, []);
+  const approvePlan = useCallback((planId: string) => decidePlan(planId, 'approved'), [decidePlan]);
+  const rejectPlan = useCallback(
+    (planId: string) => {
+      decidePlan(planId, 'rejected');
+      stop();
+    },
+    [decidePlan, stop],
+  );
+
+  return { messages, setMessages, send, isStreaming, stop, clear, approvePlan, rejectPlan, error };
 }

package/src/hooks/useComposerSuggestions.ts

@@ -0,0 +1,84 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import type { NativeSyntheticEvent, TextInputKeyPressEventData } from 'react-native';
+import {
+  type Completion,
+  SEARCH_DEBOUNCE_MS,
+  SEARCH_FROM,
+  composerCompletions,
+} from '../lib/suggestions';
+import type { AliaSuggestion } from '../types';
+
+/**
+ * The draft, once typing has settled, for the host to search with; empty while the draft is
+ * too short to search or suggestions are off. The data stays the host's: the Alia app asks its
+ * API through react-query, a host of the SDK chat asks whatever it has.
+ */
+export function useSuggestionQuery(draft: string, enabled: boolean): string {
+  const [query, setQuery] = useState('');
+  useEffect(() => {
+    const next = enabled ? draft.trim() : '';
+    if (next.length < SEARCH_FROM) {
+      setQuery('');
+      return;
+    }
+    const timer = setTimeout(() => setQuery(next), SEARCH_DEBOUNCE_MS);
+    return () => clearTimeout(timer);
+  }, [draft, enabled]);
+  return query;
+}
+
+/**
+ * The suggestions over a composer: the rows for the draft, which one the keyboard is on, and
+ * the composer's own `onKeyPress` (arrows move, Enter picks the selected row, Escape closes).
+ * Enter is left to the composer while no row is selected.
+ */
+export function useComposerSuggestions<T extends AliaSuggestion>({
+  draft,
+  enabled,
+  welcome,
+  matches,
+  onPick,
+}: {
+  draft: string;
+  /** Only a fresh conversation offers suggestions. */
+  enabled: boolean;
+  welcome: readonly T[] | undefined;
+  matches: readonly T[] | undefined;
+  onPick: (suggestion: T) => void;
+}) {
+  const [selected, setSelected] = useState(-1);
+  const [dismissed, setDismissed] = useState(false);
+
+  // A new draft reopens the list and clears the keyboard selection.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: the draft is the trigger
+  useEffect(() => {
+    setDismissed(false);
+    setSelected(-1);
+  }, [draft]);
+
+  const completions: Completion<T>[] = useMemo(
+    () => (enabled && !dismissed ? composerCompletions(draft, welcome, matches) : []),
+    [enabled, dismissed, draft, welcome, matches],
+  );
+
+  const onKeyPress = useCallback(
+    (event: NativeSyntheticEvent<TextInputKeyPressEventData>) => {
+      if (completions.length === 0) return;
+      const key = event.nativeEvent.key;
+      if (key === 'ArrowDown' || key === 'ArrowUp') {
+        event.preventDefault();
+        const step = key === 'ArrowDown' ? 1 : -1;
+        setSelected((current) => (current + step + completions.length) % completions.length);
+      } else if (key === 'Enter' && selected >= 0) {
+        event.preventDefault();
+        onPick(completions[selected]!.suggestion);
+      } else if (key === 'Escape') {
+        event.preventDefault();
+        setDismissed(true);
+      }
+    },
+    [completions, selected, onPick],
+  );
+
+  return { completions, selected, onKeyPress };
+}

package/src/index.ts

@@ -3,18 +3,21 @@
 // Reusable chat UI, voice, and streaming components for Oxy apps
 
 // ── Main components ──
+export type { AliaChatAgent, AliaChatState } from './components/AliaChatContent';
 export { AliaChatSheet } from './components/AliaChatSheet';
 export type { AliaChatSheetProps, AliaChatSheetRef } from './components/AliaChatSheet';
 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 { VoiceModeIcon } from './components/VoiceModeIcon';
 export { AmbientField, PARALLAX_DURATION, PARALLAX_EASE } from './components/AmbientField';
 export type { AmbientFieldProps } from './components/AmbientField';
-export { AliaAvatar } from './components/AliaAvatar';
+export { ALIA_AVATAR, AliaAvatar } from './components/AliaAvatar';
+export { DEFAULT_AGENT_CHARACTER, readAgentCharacter } from './lib/agent-character';
 export type { AliaAvatarProps, AliaAvatarState } from './components/AliaAvatar';
 export { IdentityMark } from './components/IdentityMark';
 export type { IdentityMarkProps, IdentityMarkState } from './components/IdentityMark';
@@ -22,7 +25,11 @@ export { AliaMarkdown } from './components/Markdown';
 export type { AliaMarkdownProps, RenderCodeBlock } from './components/Markdown';
 export { AliaWelcomeMessage } from './components/AliaWelcomeMessage';
 export { PlanPreviewCard } from './components/PlanPreviewCard';
-export { QuestionCard } from './components/QuestionCard';
+export { AskedQuestions, QuestionCard } from './components/QuestionCard';
+export { ComposerSuggestions } from './components/ComposerSuggestions';
+export { useComposerSuggestions, useSuggestionQuery } from './hooks/useComposerSuggestions';
+export { composerCompletions } from './lib/suggestions';
+export type { Completion } from './lib/suggestions';
 export {
   ASK_USER_QUESTION_TOOL,
   askedQuestions,
@@ -61,7 +68,7 @@ export type { Catalogue, CatalogueEntry, ModelSelection, ReasoningEffort } from
 export type {
   ChatMessage,
   ToolInvocation,
-  WelcomeSuggestion,
+  AliaSuggestion,
   ResearchProgress,
   ResearchSource,
   PendingPlan,

package/src/lib/agent-character.ts

@@ -0,0 +1,28 @@
+import { parseAvatarCharacter, type AvatarCharacter } from '@oxy.so/bloom/agent-avatar';
+
+/**
+ * The look of an agent whose own is not known: a server that does not send one yet, an agent that
+ * has since been deleted, a stored character this Bloom cannot draw. One neutral character, the same
+ * everywhere, so an unknown look is recognisably "not chosen" and never one that belongs to somebody.
+ */
+export const DEFAULT_AGENT_CHARACTER: AvatarCharacter = {
+  shape: 'rounded_cube',
+  eyes: 'oval',
+  eyewear: 'none',
+  accessory: 'none',
+  color: 'violet',
+};
+
+/**
+ * The character an agent is drawn as, from the JSON the server stores for it
+ * (`agents.character`): Bloom's own parser decides what it can draw, and anything else is the
+ * default look rather than an avatar that fails to render.
+ */
+export function readAgentCharacter(value: unknown): AvatarCharacter {
+  if (value === null || value === undefined) return DEFAULT_AGENT_CHARACTER;
+  try {
+    return parseAvatarCharacter(value);
+  } catch {
+    return DEFAULT_AGENT_CHARACTER;
+  }
+}

package/src/lib/character-runtime.ts

@@ -0,0 +1,10 @@
+/**
+ * Where the 3D character runtime (Alia's avatar) is served from when the host does not say.
+ *
+ * The runtime is ~214 MB of engine and data, so the chat loads it from Alia's own web origin
+ * instead of asking every app to host a copy. That origin serves it with CORS open
+ * (`packages/app/worker/index.js`), which a cross-origin module import needs; an app with a
+ * strict CSP allows it in `script-src` and `connect-src`. A host that serves its own copy
+ * passes `characterRuntimeUrl`.
+ */
+export const ALIA_CHARACTER_RUNTIME_URL = 'https://alia.onl/bloom-character/runtime.mjs';

package/src/lib/chat-stream.ts

@@ -31,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 {
@@ -324,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`);
@@ -335,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 }),
         },
       };
     }