@alia.onl/sdk 15.7.0 → 19.0.0

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]);

package/src/hooks/useReadAloud.ts

@@ -0,0 +1,92 @@
+import { toast } from '@oxy.so/bloom/toast';
+import { useCallback, useEffect, useRef } from 'react';
+import { useLabels } from '../lib/labels';
+import { useAliaRuntime } from '../runtime/config';
+import { useDictationStore } from './useDictation';
+import { useTTS } from './useTTS';
+
+export type ReadAloudState = 'idle' | 'loading' | 'playing' | 'paused' | 'error';
+
+/**
+ * The screen whose player is sounding, if any.
+ *
+ * `useTTS` keeps its player PER HOOK INSTANCE while the playback state is one shared store — and
+ * a host can keep every visited chat mounted, each with its own thread and so its own instance.
+ * Starting a reply in one chat must stop a reply still playing in another, and only the instance
+ * that owns a player can stop it. So the owner registers its `stop` here, and anyone may call it.
+ */
+let owner: { stop: () => void } | null = null;
+
+/** Silence whatever a thread is reading aloud, on any mounted screen. */
+export function stopReadingAloud(): void {
+  const current = owner;
+  owner = null;
+  current?.stop();
+}
+
+/**
+ * Read one reply aloud, as a toggle.
+ *
+ * - A press starts it; a second press on the same reply stops it — not `useTTS`'s pause, which
+ *   would leave a half-read reply parked with nothing on screen saying so.
+ * - `blocked` is a call or a dictation holding the audio: the button is disabled, and anything
+ *   already being read stops when either starts. Two voices at once, or the microphone recording
+ *   Alia's own voice into the draft, is the thing this prevents.
+ * - A failure is a toast, and the button goes back to idle.
+ *
+ * It speaks with the runtime's `apiUrl` and the host's `speech` preferences.
+ */
+export function useReadAloud(blocked: boolean) {
+  const { t } = useLabels();
+  const { apiUrl, speech } = useAliaRuntime();
+  const { readAloud, stop, activeMessageId, playbackState } = useTTS({ apiUrl, ...speech });
+  const self = useRef<{ stop: () => void }>({ stop });
+  self.current.stop = stop;
+  const owns = owner === self.current && activeMessageId !== null;
+
+  // A call or a dictation began: whatever is being read stops, wherever.
+  const dictating = useDictationStore((s) => s.isRecording);
+  const busy = blocked || dictating;
+  useEffect(() => {
+    if (busy) stopReadingAloud();
+  }, [busy]);
+
+  useEffect(() => {
+    if (!owns || playbackState !== 'error') return;
+    toast.error(t('chat.readAloudFailed'));
+    stopReadingAloud();
+  }, [owns, playbackState, t]);
+
+  // Leaving takes the player with it (`useTTS` releases it); the shared state has to go too, or
+  // every other screen would show a reply still playing.
+  useEffect(() => {
+    const me = self.current;
+    return () => {
+      if (owner === me) stopReadingAloud();
+    };
+  }, []);
+
+  const active = useRef(activeMessageId);
+  active.current = activeMessageId;
+  const toggle = useCallback(
+    (messageId: string, text: string, conversationId?: string) => {
+      const wasThis = active.current === messageId;
+      stopReadingAloud();
+      if (wasThis) return;
+      owner = self.current;
+      // The route makes a clip once and answers every later press — here or after a reload — from
+      // storage. `conversationId` files it under the conversation, so deleting that deletes it;
+      // the caller passes it only for a message the server holds (`Message.unsaved`): for one it
+      // does not, the route answers 404 and nothing would be read.
+      void readAloud(messageId, text, conversationId);
+    },
+    [readAloud],
+  );
+
+  const stateOf = useCallback(
+    (messageId: string): ReadAloudState => (activeMessageId === messageId ? playbackState : 'idle'),
+    [activeMessageId, playbackState],
+  );
+
+  return { toggle, stateOf, blocked: busy };
+}

package/src/hooks/useShareHandler.ts

@@ -0,0 +1,24 @@
+import { toast } from '@oxy.so/bloom/toast';
+import { useCallback } from 'react';
+import { useLabels } from '../lib/labels';
+import { type AliaConversationShare, useShareConversation } from '../runtime/sharing';
+
+/**
+ * What the header's share button does: mint the conversation's read-only link, then hand it to
+ * the host, which builds its own URL and shows its own share sheet. `undefined` without a host
+ * `onShare`, so there is no button.
+ */
+export function useShareHandler(
+  onShare: ((share: AliaConversationShare) => void) | undefined,
+): ((conversationId: string | undefined) => void) | undefined {
+  const { share } = useShareConversation();
+  const { t } = useLabels();
+  const handle = useCallback(
+    (conversationId: string | undefined) => {
+      if (conversationId === undefined || onShare === undefined) return;
+      void share(conversationId).then(onShare, () => toast.error(t('chat.shareFailed')));
+    },
+    [share, onShare, t],
+  );
+  return onShare === undefined ? undefined : handle;
+}

package/src/hooks/useSoundEffects.ts

@@ -91,7 +91,7 @@ export function useSoundEffects(enabled: boolean = false, sounds: SoundSources =
 
 /**
  * Hook that automatically triggers sound effects based on voice state changes.
- * Wire this into the conversation page alongside useVoiceMode.
+ * Wire this into the conversation page from the launcher's state (`useVoiceLauncher`).
  */
 export function useVoiceSoundEffects({
   isVoiceActive,

package/src/hooks/useTTS.ts

@@ -6,8 +6,7 @@ import { errorMessage } from '../lib/utils';
 import { create } from 'zustand';
 import { createAudioLevelMeter } from '../lib/audio-level';
 import { requestSpeechClip } from '../lib/speech-synthesis';
-
-const API_URL = process.env.EXPO_PUBLIC_ALIA_API_URL ?? 'https://api.alia.onl';
+import { ALIA_API_URL } from '../lib/origins';
 
 // ============== OPTIONS ==============
 
@@ -83,7 +82,7 @@ useTTSStore.subscribe((state, previous) => {
 // ============== HOOK ==============
 
 export function useTTS(options: UseTTSOptions = {}) {
-  const apiUrl = options.apiUrl || API_URL;
+  const apiUrl = options.apiUrl || ALIA_API_URL;
   const voicePref = options.voice ?? 'female';
   const voiceModel = options.model;
   const tonePref = options.tone ?? 'default';

package/src/hooks/useThoughtScope.ts

@@ -0,0 +1,59 @@
+import { useQueryClient } from '@tanstack/react-query';
+import { useEffect, useMemo } from 'react';
+import { aliaQueryKeys } from '../runtime/query-keys';
+import { type ThoughtScope, useThoughtStore } from '../runtime/thought-store';
+import type { FailedTurn } from '../runtime/turn-failure';
+import type { Message } from '../runtime/types';
+
+export interface UseThoughtScopeOptions {
+  /** The conversation being streamed into, or `undefined` for a new chat. */
+  conversationId: string | undefined;
+  messages: Message[];
+  conversationLoading: boolean;
+  isLoading: boolean;
+  failedTurn: FailedTurn | null;
+}
+
+/**
+ * This conversation as the thought panel reads it: its messages, whether they are all here yet,
+ * and the turn in flight — kept in the thought store.
+ *
+ * Keyed on the conversation and its messages, NOT on the panel being open. Syncing only while
+ * the panel was open meant the first press on a tool row rendered against whatever the store held
+ * before — another conversation's messages, or none — and found nothing by id. The store accepts
+ * this only while the open selection belongs to the same conversation, so a new-chat screen
+ * mounted underneath cannot blank a panel opened here.
+ *
+ * A load that failed is read off the query cache at the moment the memo recomputes: the load's
+ * end is what flips `conversationLoading`, so the read is fresh exactly when it matters.
+ */
+export function useThoughtScope({
+  conversationId,
+  messages,
+  conversationLoading,
+  isLoading,
+  failedTurn,
+}: UseThoughtScopeOptions): ThoughtScope {
+  const queryClient = useQueryClient();
+  const sync = useThoughtStore((s) => s.sync);
+
+  const scope = useMemo<ThoughtScope>(() => {
+    const loadFailed =
+      conversationId !== undefined &&
+      queryClient.getQueryState(aliaQueryKeys.conversations.detail(conversationId))?.status ===
+        'error';
+    return {
+      conversationId: conversationId ?? null,
+      messages,
+      status: conversationLoading ? 'loading' : loadFailed ? 'failed' : 'ready',
+      isLoading,
+      failedTurn,
+    };
+  }, [conversationId, messages, conversationLoading, isLoading, failedTurn, queryClient]);
+
+  useEffect(() => {
+    sync(scope);
+  }, [scope, sync]);
+
+  return scope;
+}

package/src/hooks/useThreadRows.ts

@@ -0,0 +1,145 @@
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+import { useLabels } from '../lib/labels';
+import {
+  type Message,
+  type ThreadMessage,
+  arrivedIds,
+  daySeparators,
+  threadSeamIds,
+  turnTimings,
+} from '../runtime/model';
+import { useTimelineShape } from './useTimelineWindow';
+
+/** The history of a conversation that has none, as ONE array: a fresh `[]` per render would break every memo. */
+const NO_HISTORY: ThreadMessage[] = [];
+
+/** For a row the timings map has never heard of: a shared frozen object keeps memoised rows still. */
+const EMPTY_TIMING = Object.freeze({ startedAt: null, endedAt: null });
+
+/** True for Alia's own replies (a delegated agent's are not). */
+function isAliaReply(message: Message): boolean {
+  return message.role === 'assistant' && !message.agentInfo;
+}
+
+export interface UseThreadRowsOptions {
+  /** The conversation being streamed into. */
+  messages: readonly Message[];
+  /** Everything said in the thread before it, oldest first. Empty where nothing is behind it. */
+  history: readonly ThreadMessage[] | undefined;
+  /** The conversation being streamed into: where the seam between the history and the live rows falls. */
+  conversationId: string | undefined;
+  /** The conversation's messages are still on their way. */
+  conversationLoading: boolean;
+}
+
+/**
+ * What the thread draws, derived once per change of its STRUCTURE.
+ *
+ * The live list as ids, roles, stamps and speakers is what a streamed token never changes, so
+ * everything derived from the whole thread (day lines, seams, turn timings, the last answer of
+ * Alia's, the window's ids) is keyed on that rather than on the messages: a token re-derives
+ * nothing, it re-renders the row it was written into and that is all.
+ */
+export function useThreadRows({
+  messages,
+  history: historyMessages,
+  conversationId,
+  conversationLoading,
+}: UseThreadRowsOptions) {
+  const { t, locale } = useLabels();
+  const history = historyMessages ?? NO_HISTORY;
+
+  const live = useMemo(
+    () => messages.filter((m) => m.role === 'user' || m.role === 'assistant'),
+    [messages],
+  );
+
+  /**
+   * Everything on screen, in reading order: the history first, the conversation being streamed
+   * into after it. Every position below — which row is last, which is the last of Alia's — is an
+   * index into THIS, not into the live messages.
+   */
+  const rows = useMemo<Message[]>(
+    () => (history.length === 0 ? live : [...history, ...live]),
+    [history, live],
+  );
+
+  const liveShape = useTimelineShape(live);
+  const shape = useMemo<readonly Message[]>(
+    () => (history.length === 0 ? liveShape : [...history, ...liveShape]),
+    [history, liveShape],
+  );
+  const ids = useMemo(() => shape.map((m) => m.id), [shape]);
+
+  /**
+   * The live rows that arrived since the last change to the list, which are the only ones that
+   * animate in. A history row never does, and neither does a conversation that was loaded or
+   * switched to (`arrivedIds`).
+   */
+  const previousLive = useRef<{ ids: readonly string[]; loading: boolean } | null>(null);
+  const arrived = useMemo(
+    () =>
+      arrivedIds(
+        previousLive.current?.ids ?? null,
+        previousLive.current?.loading ?? false,
+        liveShape,
+      ),
+    [liveShape],
+  );
+  useEffect(() => {
+    previousLive.current = { ids: liveShape.map((m) => m.id), loading: conversationLoading };
+  }, [liveShape, conversationLoading]);
+
+  /**
+   * Every turn's start and end, computed once for the whole thread: asked per row it is O(n²), and
+   * this list re-renders roughly twenty times a second while an answer streams.
+   */
+  const timings = useMemo(() => turnTimings(shape), [shape]);
+
+  /** The day each message starts, when it starts a new one: Bloom's inline date line above it. */
+  const dayLabels = useMemo(() => {
+    const labels = new Map<string, string>();
+    for (const { messageId, label } of daySeparators(shape, new Date(), locale)) {
+      labels.set(
+        messageId,
+        label.kind === 'today'
+          ? t('chat.today')
+          : label.kind === 'yesterday'
+            ? t('chat.yesterday')
+            : label.text,
+      );
+    }
+    return labels;
+  }, [shape, locale, t]);
+
+  /**
+   * Where one conversation of a thread ends and the next begins: the model was given a fresh
+   * context there, and everything above is out of its sight (`threadSeamIds`).
+   */
+  const seamIds = useMemo(
+    () => threadSeamIds(history, liveShape, conversationId ?? ''),
+    [history, liveShape, conversationId],
+  );
+
+  const timingOf = useCallback(
+    (messageId: string) => timings.get(messageId) ?? EMPTY_TIMING,
+    [timings],
+  );
+
+  const lastReplyIndex = useMemo(
+    () => shape.reduce((acc, m, i) => (isAliaReply(m) ? i : acc), -1),
+    [shape],
+  );
+
+  return {
+    rows,
+    live,
+    history,
+    ids,
+    arrived,
+    dayLabels,
+    seamIds,
+    lastReplyIndex,
+    timingOf,
+  };
+}

package/src/hooks/useThreadView.ts

@@ -0,0 +1,68 @@
+import { useCallback, useMemo, useState } from 'react';
+import type { ThreadHistory, ThreadSearchHit } from '../runtime/thread/thread-history';
+import { useThreadHistory } from '../runtime/use-thread-history';
+import { useThreadWindow } from '../runtime/use-thread-search';
+
+/**
+ * What the thread looks at: the present, or a moment in its past.
+ *
+ * An agent's thread has two states and they are not variations of one. At the present, the
+ * history runs into the conversation being streamed into. At a moment — a hit of the thread's
+ * search — the screen shows the stretch around one old message and there is nothing live beneath
+ * it. The way back is leaving, not scrolling: the endpoint pages BACKWARDS only, so walking
+ * forward from a jump would be a road that ends.
+ *
+ * `threadHandle` is the agent's handle; without it the chat is one conversation with nothing
+ * behind it and there is nothing to page into, search or jump to.
+ */
+export function useThreadView(
+  threadHandle: string | undefined,
+  conversationId: string | undefined,
+) {
+  const present = useThreadHistory(threadHandle, conversationId);
+  const [searchOpen, setSearchOpen] = useState(false);
+  /** The message the reader jumped to, by cursor, or `null` for the present. */
+  const [jumpedTo, setJumpedTo] = useState<string | null>(null);
+  const past = useThreadWindow(threadHandle, jumpedTo);
+  const jumped = jumpedTo !== null;
+
+  // Ask for the page above, unless one is already coming. Bloom fires `onStartReached` once per
+  // approach and re-arms when the reader leaves the zone, so the guards left are about the DATA.
+  const source = jumped
+    ? { ...past, loading: past.isLoadingMore || past.isLoading }
+    : { ...present, loading: present.isLoadingMore };
+  const { messages, hasMore, loading, loadMore: fetchMore } = source;
+  const loadMore = useCallback(() => {
+    if (!loading) void fetchMore();
+  }, [loading, fetchMore]);
+
+  const history = useMemo<ThreadHistory | undefined>(
+    () =>
+      threadHandle === undefined
+        ? undefined
+        : { messages, loading, ...(hasMore ? { loadMore } : {}) },
+    [threadHandle, messages, loading, hasMore, loadMore],
+  );
+
+  /**
+   * Open the thread around a hit, and close the search over it. The cursor rather than the
+   * message id: an id addresses a message, and only a cursor addresses a POSITION, which is what
+   * a window is asked for.
+   */
+  const jump = useCallback((hit: ThreadSearchHit) => {
+    setJumpedTo(hit.cursor);
+    setSearchOpen(false);
+  }, []);
+
+  return {
+    history,
+    /** The cursor jumped to, or `null` at the present. */
+    focusCursor: jumpedTo,
+    jumped,
+    jump,
+    backToLatest: useCallback(() => setJumpedTo(null), []),
+    searchOpen,
+    openSearch: useCallback(() => setSearchOpen(true), []),
+    closeSearch: useCallback(() => setSearchOpen(false), []),
+  };
+}