@alia.onl/sdk 15.8.0 → 19.1.0

package/src/hooks/useChatComposer.ts

@@ -0,0 +1,299 @@
+import type { AvatarFlights } from '@oxy.so/bloom/avatar-flight';
+import { useOxy } from '@oxy.so/services/ui/client';
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+import type { NativeSyntheticEvent, TextInput, TextInputKeyPressEventData } from 'react-native';
+import type { SharedValue } from 'react-native-reanimated';
+import { leadToProfile } from '../lib/flights';
+import type { AliaLead } from '../lib/participants';
+import { imageUriToDataUrl } from '../lib/image-data-url';
+import {
+  useComposerDraft,
+  useComposerDraftStore,
+  useDraftAddress,
+} from '../runtime/composer-draft-store';
+import type { SendOptions } from '../runtime/types';
+import type { ConversationThread } from '../runtime/use-conversation-thread';
+import { useTurnEdit } from '../runtime/use-turn-edit';
+import type { AliaAttachment, AliaSuggestion } from '../types';
+import { useComposerSuggestions, useSuggestionQuery } from './useComposerSuggestions';
+import { useFocusWhenPresented } from './useFocusWhenPresented';
+
+/** A turn of the person's: the text, and the photos (`data:` or `https:` URLs) sent with it. */
+export interface AliaTurn {
+  text: string;
+  images?: ReadonlyArray<string>;
+}
+
+export interface UseChatComposerOptions {
+  conversationId: string | undefined;
+  thread: ConversationThread;
+  /** Nothing is stored: the first turn is sent without creating a conversation (ghost mode). */
+  ephemeral: boolean;
+  /** The composer is closed (the usage limit): nothing may be sent. */
+  closed: boolean;
+  /** A write is done in the present, so it ends a jump into the thread's past. */
+  onWrite: () => void;
+  /**
+   * Hands the first turn of an empty chat to the host instead of sending it here (a sheet opens
+   * the conversation in a new sheet over this one).
+   */
+  onStart: ((turn: AliaTurn) => void) | undefined;
+  /** The avatar flights: the greeting leaves with the first turn. */
+  flights: AvatarFlights;
+  /** Whose greeting it is: the lead's avatar is the one that flies. */
+  lead: AliaLead;
+  /** A turn sent once as the chat mounts: the conversation a sheet was opened for. */
+  initialTurn: AliaTurn | undefined;
+  /** The signed-out person sent a turn: the host asks them to sign in. */
+  onSignInRequired: (() => void) | undefined;
+  /** A refusal to say, with its title. */
+  reportError: (message: string, title?: string) => void;
+  /** The suggestions over the composer on an empty chat, and the host's side of finding them. */
+  welcomeSuggestions: AliaSuggestion[] | undefined;
+  suggestionMatches: AliaSuggestion[] | undefined;
+  onSuggestionQuery: ((query: string) => void) | undefined;
+  onSuggestionPicked: ((suggestion: AliaSuggestion) => void) | undefined;
+  /** The sheet this chat is in: the composer takes focus once it is up. */
+  presentedProgress: SharedValue<number> | undefined;
+}
+
+/** A photo handed over as a `data:` URL, as the composer would hold it. */
+function dataUrlAttachment(url: string, index: number): AliaAttachment {
+  const mimeType = /^data:([^;,]+)/.exec(url)?.[1] ?? 'image/jpeg';
+  return {
+    id: `turn-photo-${index}`,
+    type: 'image',
+    name: `photo-${index + 1}`,
+    uri: url,
+    size: 0,
+    mimeType,
+  };
+}
+
+/**
+ * Everything the person does with the composer: the draft they are writing (kept per conversation,
+ * shared with every other surface), sending it, rewriting a question already sent, answering
+ * Alia's questions, picking a suggestion, asking for a reply again.
+ *
+ * Sending is the one path every turn takes. The draft is cleared at once and handed back if the
+ * request fails; an edit replaces the question it rewrites; an empty chat may hand its first turn
+ * to the host; a signed-out person is sent to sign in with their draft kept.
+ */
+export function useChatComposer({
+  conversationId,
+  thread,
+  ephemeral,
+  closed,
+  onWrite,
+  onStart,
+  flights,
+  lead,
+  initialTurn,
+  onSignInRequired,
+  reportError,
+  welcomeSuggestions,
+  suggestionMatches,
+  onSuggestionQuery,
+  onSuggestionPicked,
+  presentedProgress,
+}: UseChatComposerOptions) {
+  const { isAuthenticated } = useOxy();
+  const {
+    messages,
+    isLoading,
+    sendMessage,
+    createNewConversation,
+    editMessage,
+    regenerateMessage,
+    turnOptionsOf,
+  } = thread;
+
+  // ── The draft ──
+  const target = conversationId ?? null;
+  const draft = useComposerDraft(target);
+  const address = useDraftAddress(target);
+  const photos = draft.attachments;
+  /** What a send carries beyond the text: the connector and skills chosen for this turn. */
+  const turnOptions = useMemo<SendOptions>(
+    () => ({ mcpServerId: draft.mcpServerId, skillNames: draft.skillNames }),
+    [draft.mcpServerId, draft.skillNames],
+  );
+  const setText = useCallback(
+    (text: string) => useComposerDraftStore.getState().setText(address, text),
+    [address],
+  );
+  const addAttachment = useCallback(
+    (attachment: AliaAttachment) =>
+      useComposerDraftStore.getState().addAttachment(address, attachment),
+    [address],
+  );
+  const removeAttachment = useCallback(
+    (id: string) => useComposerDraftStore.getState().removeAttachment(address, id),
+    [address],
+  );
+  const edit = useTurnEdit({ target, messages, turnOptionsOf, onEditMessage: editMessage });
+  const { editing } = edit;
+
+  // ── Sending ──
+  // A turn goes into the open conversation; with none open, it creates one and is sent from it —
+  // unless nothing is to be stored.
+  const sendTurn = useCallback(
+    (text: string, attachments?: AliaAttachment[], options?: SendOptions) =>
+      conversationId || ephemeral
+        ? sendMessage(text, attachments, options)
+        : createNewConversation(text, attachments, options),
+    [conversationId, ephemeral, sendMessage, createNewConversation],
+  );
+
+  // The first turn of an empty chat goes to the host when it asked for it; every other turn is
+  // sent here.
+  const firstTurn = messages.length === 0;
+  const startsElsewhere = onStart !== undefined && firstTurn;
+  const submitTurn = useCallback(
+    async (text: string, attachments: AliaAttachment[] = [], options?: SendOptions) => {
+      onWrite();
+      if (startsElsewhere) {
+        const images = await Promise.all(
+          attachments.map((photo) => imageUriToDataUrl(photo.uri, photo.mimeType)),
+        );
+        // The host's conversation sheet opens first so that the flight, drawn when it launches, is
+        // above it; this chat stays on the greeting, so the avatar can still be measured.
+        onStart({ text, ...(images.length > 0 ? { images } : {}) });
+        await flights.launch([leadToProfile(lead)]);
+        return;
+      }
+      // The greeting leaves with the first turn: measure it before it does.
+      if (firstTurn) await flights.launch([leadToProfile(lead)]);
+      await sendTurn(text, attachments, options);
+    },
+    [startsElsewhere, onStart, firstTurn, flights, lead, sendTurn, onWrite],
+  );
+
+  // The conversation this chat was opened for, sent once.
+  const initialSent = useRef(false);
+  useEffect(() => {
+    if (!initialTurn || initialSent.current) return;
+    initialSent.current = true;
+    void sendTurn(initialTurn.text, initialTurn.images?.map(dataUrlAttachment));
+  }, [initialTurn, sendTurn]);
+
+  const submit = useCallback(
+    async (value: string) => {
+      const text = value.trim();
+      if ((!text && photos.length === 0) || isLoading || closed) return;
+      // An edit rewrites the question's words; an attachment alone does not make a replacement.
+      if (editing !== undefined && !text) return;
+      // Signed out: the host asks for the sign-in instead of firing a request that would 401. The
+      // draft stays in the composer for after.
+      if (!isAuthenticated && onSignInRequired) {
+        onSignInRequired();
+        return;
+      }
+      const attachments = photos.length > 0 ? photos : undefined;
+      // Cleared optimistically: the send path restores text, attachments and the turn's connector
+      // and skills to this draft if the request fails.
+      useComposerDraftStore.getState().clear(address);
+      try {
+        if (editing !== undefined) await edit.submit(text, turnOptions, attachments);
+        else await submitTurn(text, attachments, turnOptions);
+      } catch (err) {
+        // Nothing was sent (the photos could not be read): keep the draft.
+        useComposerDraftStore.getState().restore(address, { text: value, attachments: photos });
+        reportError(err instanceof Error ? err.message : 'Could not attach the photos');
+      }
+    },
+    [
+      photos,
+      isLoading,
+      closed,
+      editing,
+      isAuthenticated,
+      onSignInRequired,
+      address,
+      edit,
+      turnOptions,
+      submitTurn,
+      reportError,
+    ],
+  );
+
+  // A reply again, sent the way its question was (the composer's choice when it is unknown).
+  const latest = useRef({ regenerateMessage, turnOptions });
+  latest.current = { regenerateMessage, turnOptions };
+  const regenerate = useCallback((assistantMessageId: string) => {
+    const { regenerateMessage: again, turnOptions: fallback } = latest.current;
+    void again(assistantMessageId, fallback);
+  }, []);
+
+  // ── Suggestions over the composer on an empty chat ──
+  const query = useSuggestionQuery(draft.text, firstTurn && !closed);
+  useEffect(() => {
+    onSuggestionQuery?.(query);
+  }, [query, onSuggestionQuery]);
+  // Read through a ref: it is a prop of the suggestions' rows and the send path changes per token.
+  const submitRef = useRef(submit);
+  useEffect(() => {
+    submitRef.current = submit;
+  });
+  const pickSuggestion = useCallback(
+    (suggestion: AliaSuggestion) => {
+      onSuggestionPicked?.(suggestion);
+      // A template has blanks to fill, so it goes into the composer for the person to finish
+      // instead of being sent with its placeholders.
+      if (suggestion.template) setText(suggestion.text);
+      else void submitRef.current(suggestion.text);
+    },
+    [onSuggestionPicked, setText],
+  );
+  const suggestions = useComposerSuggestions({
+    draft: draft.text,
+    enabled: firstTurn && !closed,
+    welcome: welcomeSuggestions,
+    matches: suggestionMatches,
+    onPick: pickSuggestion,
+  });
+
+  // ── The field: focus, and its keys ──
+  const inputRef = useRef<TextInput | null>(null);
+  useFocusWhenPresented(presentedProgress, () => inputRef.current?.focus());
+  // Starting an edit puts the caret in the composer that now holds the question: the Edit press
+  // left focus on the row's button, so typing went nowhere and Escape could not reach the edit.
+  const editingId = editing?.messageId;
+  useEffect(() => {
+    if (editingId !== undefined) inputRef.current?.focus();
+  }, [editingId]);
+  const { onKeyPress: onSuggestionKeyPress } = suggestions;
+  const cancelEdit = edit.cancel;
+  const onKeyPress = useCallback(
+    (event: NativeSyntheticEvent<TextInputKeyPressEventData>) => {
+      // Escape leaves an edit, as its Cancel does: it is the top-most thing open while the
+      // question is being rewritten.
+      if (editing !== undefined && event.nativeEvent.key === 'Escape') {
+        event.preventDefault();
+        cancelEdit();
+        return;
+      }
+      onSuggestionKeyPress(event);
+    },
+    [editing, cancelEdit, onSuggestionKeyPress],
+  );
+
+  return {
+    text: draft.text,
+    setText,
+    photos,
+    addAttachment,
+    removeAttachment,
+    address,
+    turnOptions,
+    edit,
+    editing,
+    firstTurn,
+    sendTurn,
+    submit,
+    regenerate,
+    suggestions: { ...suggestions, onPick: pickSuggestion },
+    inputRef,
+    onKeyPress,
+  };
+}

package/src/hooks/useChatVoice.ts

@@ -0,0 +1,129 @@
+import { useOxy } from '@oxy.so/services/ui/client';
+import { useQueryClient } from '@tanstack/react-query';
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+import type { AliaAvatarState } from '../components/AliaAvatar';
+import { callThread } from '../lib/call-thread';
+import { turnActivityState } from '../lib/turn-state';
+import { useAliaRuntime } from '../runtime/config';
+import { aliaQueryKeys } from '../runtime/query-keys';
+import type { Message } from '../runtime/types';
+import { type SoundSources, useVoiceSoundEffects } from './useSoundEffects';
+import { type UseVoiceLauncherOptions, useVoiceLauncher } from './useVoiceLauncher';
+
+/** What a host tells the chat about its voice call (see {@link UseVoiceLauncherOptions}). */
+export type AliaVoiceOptions = Omit<
+  UseVoiceLauncherOptions,
+  'apiUrl' | 'conversationId' | 'agentId' | 'accountId' | 'resolveConversation' | 'isFocused'
+> & {
+  /** The cues played as the call thinks, uses tools, connects and ends. Omitted, the call is silent. */
+  sounds?: SoundSources;
+};
+
+export interface UseChatVoiceOptions {
+  /** The host's say: on by default, `false` for a text-only chat, an object for its callbacks. */
+  options: false | AliaVoiceOptions | undefined;
+  conversationId: string | undefined;
+  agentId: string | undefined;
+  /** Whether the screen holding the chat is the one on show. A live call ends when it is not. */
+  isFocused: boolean;
+  /** Makes the conversation a call lives in when none is open (after the gate). */
+  ensureConversation: () => Promise<string | undefined>;
+  messages: Message[];
+  setMessages: (messages: Message[]) => void;
+  /** The conversation's stored messages: a call message shows as stored once it is. */
+  storedMessages: readonly Message[] | undefined;
+  /** A text turn is in flight. */
+  isLoading: boolean;
+}
+
+/**
+ * The chat's voice call.
+ *
+ * The launcher owns whether a call is open, the gate before one opens and what it reports back
+ * (for the ambient wave, the cues and the transcript); the call itself loads on the first one.
+ * The transcript is merged into the thread: the text messages the chat held when the call
+ * started, then the call's, so the conversation reads as one. And what Alia is doing — the
+ * header's mark — follows the call while one is open and the text turn otherwise.
+ */
+export function useChatVoice({
+  options,
+  conversationId,
+  agentId,
+  isFocused,
+  ensureConversation,
+  messages,
+  setMessages,
+  storedMessages,
+  isLoading,
+}: UseChatVoiceOptions) {
+  const runtime = useAliaRuntime();
+  const { user } = useOxy();
+  const queryClient = useQueryClient();
+  const enabled = options !== false;
+  const { sounds, ...launcherOptions }: AliaVoiceOptions =
+    options === false || options === undefined ? {} : options;
+  const { onCallEnded } = launcherOptions;
+
+  const refreshConversation = useCallback(
+    (id: string) => {
+      void queryClient.invalidateQueries({ queryKey: aliaQueryKeys.conversations.detail(id) });
+      void queryClient.invalidateQueries({ queryKey: aliaQueryKeys.conversations.all });
+    },
+    [queryClient],
+  );
+
+  const launcher = useVoiceLauncher({
+    apiUrl: runtime.apiUrl,
+    conversationId,
+    agentId,
+    accountId: user?.id ?? null,
+    locale: runtime.speech.language,
+    voice: runtime.speech.voice,
+    resolveConversation: ensureConversation,
+    onMessagesSaved: refreshConversation,
+    isFocused,
+    ...launcherOptions,
+    // The call's transcript is in the thread, whatever else the host refreshes.
+    onCallEnded: () => {
+      if (conversationId !== undefined) refreshConversation(conversationId);
+      onCallEnded?.();
+    },
+  });
+  const { isActive, state, start } = launcher;
+  const agentState = state?.agentState;
+
+  useVoiceSoundEffects({
+    isVoiceActive: isActive,
+    agentState: agentState ?? 'idle',
+    isConnected: state?.isConnected ?? false,
+    sounds: sounds ?? {},
+  });
+
+  // The transcript, after the text messages the chat held when the call started.
+  const textBeforeCall = useRef<Message[]>([]);
+  const voiceMessages = state?.messages;
+  useEffect(() => {
+    if (!voiceMessages) return;
+    setMessages(callThread(textBeforeCall.current, voiceMessages, storedMessages));
+  }, [voiceMessages, storedMessages, setMessages]);
+
+  const latestMessages = useRef(messages);
+  latestMessages.current = messages;
+  const activate = useCallback(() => {
+    if (isActive) return;
+    textBeforeCall.current = [...latestMessages.current];
+    void start();
+  }, [isActive, start]);
+
+  // What Alia is doing, which the header's mark shows.
+  const markState = useMemo<AliaAvatarState>(() => {
+    if (isActive) {
+      if (agentState === 'speaking') return 'writing';
+      if (agentState === 'thinking') return 'thinking';
+      return 'idle';
+    }
+    return turnActivityState(messages, isLoading);
+  }, [messages, isLoading, isActive, agentState]);
+
+  return { enabled, launcher, isActive, state, agentState, activate, markState };
+}

package/src/hooks/useDocumentPicker.ts

@@ -1,37 +1,11 @@
-import * as DocumentPicker from 'expo-document-picker';
+import { type DocumentPickerResult, pickDocuments } from '../lib/document-picker';
 
-export type DocumentPickerResult = {
-  uri: string;
-  name: string;
-  size: number;
-  mimeType: string;
-};
+export type { DocumentPickerResult };
 
 type UseDocumentPickerResult = {
   pickDocument: () => Promise<DocumentPickerResult[] | undefined>;
 };
 
 export function useDocumentPicker(): UseDocumentPickerResult {
-  const pickDocument = async (): Promise<DocumentPickerResult[] | undefined> => {
-    try {
-      const result = await DocumentPicker.getDocumentAsync({
-        type: '*/*',
-        multiple: true,
-        copyToCacheDirectory: true,
-      });
-
-      if (result.canceled === false && result.assets && result.assets.length > 0) {
-        return result.assets.map((asset) => ({
-          uri: asset.uri,
-          name: asset.name,
-          size: asset.size || 0,
-          mimeType: asset.mimeType || 'application/octet-stream',
-        }));
-      }
-    } catch (error) {
-      console.warn('Failed to pick document:', error);
-    }
-  };
-
-  return { pickDocument };
+  return { pickDocument: pickDocuments };
 }

package/src/hooks/useFailedTurnToast.ts

@@ -0,0 +1,43 @@
+import { useLabels } from '../lib/labels';
+import type { FailedTurn } from '../runtime/model';
+import { toast } from '@oxy.so/bloom/toast';
+import { useEffect, useRef } from 'react';
+
+/** One toast for the failed turn, replaced by the next failure and dismissed with the turn. */
+export const FAILED_TURN_TOAST_ID = 'failed-turn';
+/** Long enough to read the line and press Retry; a toast that is gone before that is no error. */
+export const FAILED_TURN_TOAST_MS = 10_000;
+
+/**
+ * A failed turn is told with a toast, with Retry as its action.
+ *
+ * The person's message is still in the thread, and the toast says why it has no answer in the
+ * app's own words, in the reader's language (the server's stand-in text, "all models are busy…",
+ * is never shown as Alia's own). Real output before the failure reads "interrupted", not "couldn't
+ * answer". The server's words, if any, go under the line. It leaves with the turn: when the failure
+ * is cleared (a retry, a new message, another chat), so does the toast.
+ */
+export function useFailedTurnToast(
+  failedTurn: FailedTurn | null | undefined,
+  onRetry?: () => void,
+) {
+  const { t } = useLabels();
+  // The latest retry, without making a new toast of every render.
+  const retry = useRef(onRetry);
+  retry.current = onRetry;
+
+  useEffect(() => {
+    if (!failedTurn) return;
+    const line = failedTurn.partial ? t('chat.turnInterrupted') : t('chat.turnFailed');
+    const canRetry = failedTurn.retryable && retry.current !== undefined;
+    toast.error(canRetry ? `${line} ${t('chat.turnFailedRetryHint')}` : line, {
+      id: FAILED_TURN_TOAST_ID,
+      description: failedTurn.detail || undefined,
+      duration: FAILED_TURN_TOAST_MS,
+      ...(canRetry ? { action: { label: t('chat.retry'), onClick: () => retry.current?.() } } : {}),
+    });
+    return () => {
+      toast.dismiss(FAILED_TURN_TOAST_ID);
+    };
+  }, [failedTurn, t]);
+}

package/src/hooks/useMessageVote.ts

@@ -0,0 +1,50 @@
+import { toast } from '@oxy.so/bloom/toast';
+import { useCallback, useRef } from 'react';
+import { useLabels } from '../lib/labels';
+import { useAliaApi } from '../runtime/api';
+import { ALIA_API_ROUTES } from '../runtime/model';
+
+export type Vote = 'up' | 'down';
+
+/**
+ * Like or dislike a reply; pressing the same vote again retracts it.
+ *
+ * `conversationId` is the conversation that holds the MESSAGE, which is not always the one on
+ * screen — a thread shows several, and an old message's vote sent to the stretch being streamed
+ * into would fail quietly. It is `undefined` for a message no conversation holds yet
+ * (`Message.unsaved`): a turn that failed or was stopped. There is nothing to record the vote on,
+ * and the button cannot be hidden on its own, so the press says so rather than thanking the person
+ * for nothing.
+ */
+export function useMessageVote() {
+  const { t } = useLabels();
+  const api = useAliaApi();
+  /** This screen's votes, read to decide whether a press casts or retracts one. */
+  const votes = useRef<Record<string, Vote>>({});
+  const inFlight = useRef<Set<string>>(new Set());
+
+  return useCallback(
+    (messageId: string, vote: Vote, conversationId: string | undefined) => {
+      if (conversationId === undefined) {
+        toast.error(t('chat.feedbackFailed'));
+        return;
+      }
+      if (inFlight.current.has(messageId)) return;
+      const next = votes.current[messageId] === vote ? null : vote;
+      if (next) votes.current[messageId] = next;
+      else delete votes.current[messageId];
+      inFlight.current.add(messageId);
+      api
+        .patch(ALIA_API_ROUTES.conversations.vote(conversationId, messageId), { vote: next })
+        .then(() => toast.success(t('chat.thanksFeedback')))
+        .catch(() => {
+          // Back to what the server holds, so the next press casts it again.
+          if (next) delete votes.current[messageId];
+          else votes.current[messageId] = vote;
+          toast.error(t('chat.feedbackFailed'));
+        })
+        .finally(() => inFlight.current.delete(messageId));
+    },
+    [api, t],
+  );
+}

package/src/hooks/useOpenThought.ts

@@ -0,0 +1,79 @@
+import { useCallback, useEffect, useRef } from 'react';
+import { rememberOpener } from '../lib/focus-return';
+import { useAliaRuntime } from '../runtime/config';
+import { type ThoughtScope, type ThoughtTab, useThoughtStore } from '../runtime/thought-store';
+import type { ThreadMessage } from '../runtime/thread/thread-history';
+
+/** Open the thought panel on a turn; `opener` is the control pressed, to give focus back to. */
+export type OpenThought = (messageId: string, tab?: ThoughtTab, opener?: unknown) => void;
+
+/**
+ * The scope a press on a row hands the thought panel: the conversation the row belongs to, which
+ * is not always the one being streamed into.
+ *
+ * A live row belongs to the conversation on screen. A history row belongs to an earlier stretch
+ * of the thread — persisted and complete — so its scope is that stretch's messages and nothing
+ * about the live turn. Keyed by conversation and message: the panel never shows one
+ * conversation's turn under another's.
+ */
+export function thoughtScopeFor(
+  messageId: string,
+  live: ThoughtScope,
+  history: readonly ThreadMessage[],
+): ThoughtScope {
+  if (live.messages.some((m) => m.id === messageId)) return live;
+  const past = history.find((m) => m.id === messageId);
+  if (past === undefined) return live;
+  return {
+    conversationId: past.conversationId,
+    messages: history.filter((m) => m.conversationId === past.conversationId),
+    status: 'ready',
+    isLoading: false,
+    failedTurn: null,
+  };
+}
+
+/**
+ * Open the thought panel on any turn — the one in flight or one long past — or `undefined` when
+ * the host has no panel to show it in (`AliaRuntimeHost.showThought`): the row then draws its
+ * "worked for" line as plain text.
+ *
+ * `runningTurnId` is the turn in flight once it has begun using tools. The first tool of a turn
+ * opens the panel on it unless the host declines (something else is open), once per turn: a
+ * reader who closes it keeps it closed.
+ *
+ * The returned function is stable: it is a prop of every memoised row, while the live scope
+ * changes per streamed token, so the scopes are read at press time through a ref.
+ */
+export function useOpenThought(
+  live: ThoughtScope,
+  history: readonly ThreadMessage[],
+  runningTurnId: string | null,
+): OpenThought | undefined {
+  const { showThought } = useAliaRuntime().host;
+  const select = useThoughtStore((s) => s.open);
+  const latest = useRef({ live, history, showThought });
+  useEffect(() => {
+    latest.current = { live, history, showThought };
+  });
+
+  const open = useCallback<OpenThought>(
+    (messageId, tab, opener) => {
+      const { live: scope, history: past, showThought: show } = latest.current;
+      rememberOpener(opener);
+      select(messageId, thoughtScopeFor(messageId, scope, past), tab);
+      show?.('pressed');
+    },
+    [select],
+  );
+
+  const autoOpened = useRef<string | null>(null);
+  useEffect(() => {
+    if (runningTurnId === null || autoOpened.current === runningTurnId) return;
+    autoOpened.current = runningTurnId;
+    const { live: scope, showThought: show } = latest.current;
+    if (show?.('automatic') === true) select(runningTurnId, scope);
+  }, [runningTurnId, select]);
+
+  return showThought === undefined ? undefined : open;
+}

package/src/hooks/usePendingQuestions.ts

@@ -1,6 +1,6 @@
 import { useCallback, useMemo, useState } from 'react';
 import { type AskedQuestion, pendingQuestions } from '../lib/questions';
-import type { ChatMessage } from '../types';
+import type { Message } from '../runtime/types';
 
 /**
  * What Alia asked in her last turn and the person has not answered: asked above the composer,
@@ -8,7 +8,7 @@ import type { ChatMessage } from '../types';
  * puts the card away until she asks again.
  */
 export function usePendingQuestions(
-  messages: readonly Pick<ChatMessage, 'id' | 'role' | 'toolInvocations'>[],
+  messages: readonly Pick<Message, 'id' | 'role' | 'toolInvocations'>[],
   isStreaming: boolean,
 ): { questions: AskedQuestion[]; dismiss: () => void } {
   const asked = useMemo(() => pendingQuestions(messages, isStreaming), [messages, isStreaming]);