@alia.onl/sdk 10.1.0 → 11.0.0

package/src/lib/work-log.ts

@@ -0,0 +1,378 @@
+import {
+  RiBookOpenLine,
+  RiFileTextLine,
+  RiGlobalLine,
+  RiSearchLine,
+  RiTerminalBoxLine,
+  RiToolsLine,
+} from '@oxy.so/bloom/icons';
+import type { TaskListChip, TaskListStep, TaskListTask } from '@oxy.so/bloom/task-list';
+import type { WebSearchBrand, WebSearchSource, WebSearchStep } from '@oxy.so/bloom/web-search';
+import type { ToolInvocation } from '../types';
+import { extractCitationSources } from './citations';
+import { getToolDoneLabel, getToolPillLabel } from './task-labels';
+import { toolCallStatus } from './tool-call-status';
+import { englishWorkLog, type Translate } from './work-log-copy';
+
+/**
+ * A turn's tool calls, as the two Bloom logs draw them.
+ *
+ * Where the turn WENT (searches, page visits, research) is a `WebSearch`
+ * trail; what it DID with every other tool is a `TaskList`. Calls that return
+ * a card (weather, market…) are neither — the caller filters them out first.
+ *
+ * Both logs count UNITS and are driven by `revealed`, never by their own
+ * ticker: a unit counts as revealed only when the event that produced it has
+ * arrived. A call whose arguments are still streaming (`partial-call`) is a
+ * step that is known but not yet revealed, so the log shimmers on it and shows
+ * its Working tail; a step's sources are a unit that exists only once the
+ * result carried them.
+ */
+
+/** What a host can swap: the words, and where a site's icon is served from. */
+export interface WorkLogOptions {
+  /** Translator for the log's words (see `work-log-copy.ts`). Default: English. */
+  t?: Translate;
+  /** The URL of a site's cached icon, or nothing for Bloom's quiet dot. */
+  faviconUrl?: (url: string) => string | null | undefined;
+}
+
+/** The result of a call, when it is an object (the tools return objects). */
+function resultOf(inv: Pick<ToolInvocation, 'result'>): Record<string, unknown> | undefined {
+  const result = inv.result;
+  return result !== null && typeof result === 'object' && !Array.isArray(result)
+    ? (result as Record<string, unknown>)
+    : undefined;
+}
+
+/** The research the live stream reports before the answer is persisted. */
+export interface LiveResearch {
+  currentQuery?: string;
+  sourcesFound?: number;
+  sources?: Array<{ id?: unknown; url?: unknown; title?: unknown }> | null;
+}
+
+/** Tools whose calls are a place the turn went, not a task it did. */
+const WEB_TOOLS = new Set(['webSearch', 'browse', 'webScraper', 'deepResearch']);
+
+export function isWebInvocation(inv: Pick<ToolInvocation, 'toolName'>): boolean {
+  return WEB_TOOLS.has(inv.toolName);
+}
+
+function str(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function domainOf(url: string): string {
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return url;
+  }
+}
+
+/** The site marks Bloom draws, by registrable domain. Anything else is a quiet dot. */
+const BRANDS: Array<[string, WebSearchBrand]> = [
+  ['github.com', 'github'],
+  ['gitlab.com', 'gitlab'],
+  ['bitbucket.org', 'bitbucket'],
+  ['x.com', 'x'],
+  ['twitter.com', 'x'],
+  ['reddit.com', 'reddit'],
+  ['facebook.com', 'facebook'],
+  ['instagram.com', 'instagram'],
+  ['linkedin.com', 'linkedin'],
+  ['tiktok.com', 'tiktok'],
+  ['spotify.com', 'spotify'],
+  ['twitch.tv', 'twitch'],
+  ['notion.so', 'notion'],
+  ['notion.site', 'notion'],
+  ['figma.com', 'figma'],
+  ['apple.com', 'apple'],
+  ['microsoft.com', 'microsoft'],
+  ['google.com', 'google'],
+  ['discord.com', 'discord'],
+  ['slack.com', 'slack'],
+  ['dropbox.com', 'dropbox'],
+  ['telegram.org', 'telegram'],
+  ['t.me', 'telegram'],
+  ['whatsapp.com', 'whatsapp'],
+  ['amazon.com', 'amazon'],
+];
+
+function brandOf(domain: string): WebSearchBrand | undefined {
+  const host = domain.toLowerCase();
+  return BRANDS.find(([site]) => host === site || host.endsWith(`.${site}`))?.[1];
+}
+
+/**
+ * One source row. Its favicon is Clarity's copy of the site's icon: the one a
+ * search result carries, or the URL Clarity serves it at for anything else
+ * (a page Alia read). Bloom draws a brand mark over it, and the dot when
+ * Clarity has not fetched that site yet.
+ */
+function source(
+  url: string,
+  options: WorkLogOptions,
+  title?: string,
+  faviconUrl?: string,
+): WebSearchSource {
+  const domain = domainOf(url);
+  const brand = brandOf(domain);
+  const favicon = faviconUrl ?? options.faviconUrl?.(url);
+  return {
+    title: title ?? domain,
+    domain,
+    href: url,
+    ...(brand ? { brand } : {}),
+    ...(favicon ? { faviconUrl: favicon } : {}),
+  };
+}
+
+function uniqueSources(list: WebSearchSource[]): WebSearchSource[] {
+  const seen = new Set<string>();
+  return list.filter((s) => {
+    const key = s.href ?? s.title;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function succeeded(inv: ToolInvocation): boolean {
+  return toolCallStatus(inv, true) === 'done';
+}
+
+function isSearch(inv: ToolInvocation): boolean {
+  if (inv.toolName === 'webSearch') return true;
+  const action = str(resultOf(inv)?.action) ?? str(inv.args?.action);
+  return inv.toolName === 'browse' && action === 'search';
+}
+
+/** One step, and whether the event that produced it has arrived. */
+interface MappedStep {
+  step: WebSearchStep;
+  arrived: boolean;
+}
+
+function webStep(
+  inv: ToolInvocation,
+  live: LiveResearch | undefined,
+  options: WorkLogOptions,
+): MappedStep {
+  const t = options.t ?? englishWorkLog;
+  const arrived = inv.state !== 'partial-call';
+  const ok = succeeded(inv);
+  const res = resultOf(inv);
+
+  if (inv.toolName === 'deepResearch') {
+    const cited = extractCitationSources([inv], live?.sources);
+    const searches = typeof res?.totalSearches === 'number' ? res.totalSearches : 0;
+    return {
+      arrived,
+      step: {
+        label: t('chat.bloom.researched'),
+        query: str(inv.args?.query),
+        icon: RiBookOpenLine,
+        ...(searches > 0 ? { meta: t('chat.bloom.searchCount', { count: searches }) } : {}),
+        ...(cited.length > 0 ? { sources: cited.map((c) => source(c.url, options, c.title)) } : {}),
+      },
+    };
+  }
+
+  if (isSearch(inv)) {
+    const results: unknown[] = ok && Array.isArray(res?.results) ? res.results : [];
+    const sources = uniqueSources(
+      results.flatMap((r) => {
+        const url = str((r as { url?: unknown })?.url);
+        return url
+          ? [
+              source(
+                url,
+                options,
+                str((r as { title?: unknown }).title),
+                str((r as { faviconUrl?: unknown }).faviconUrl),
+              ),
+            ]
+          : [];
+      }),
+    );
+    const count = typeof res?.count === 'number' ? res.count : results.length;
+    return {
+      arrived,
+      step: {
+        label: t('chat.bloom.searchedWeb'),
+        query: str(inv.args?.query),
+        icon: RiSearchLine,
+        // Say what came back, including nothing: a search that found nothing or
+        // failed must not look like one whose sources are missing.
+        ...(inv.state !== 'result'
+          ? {}
+          : !ok
+            ? { meta: t('chat.bloom.searchFailed') }
+            : count === 0
+              ? { meta: t('chat.bloom.noResults') }
+              : { meta: t('chat.bloom.resultCount', { count }) }),
+        ...(sources.length > 0 ? { sources } : {}),
+      },
+    };
+  }
+
+  // A page visit: `webScraper`, or `browse` reading a URL.
+  const url = str(res?.url) ?? str(inv.args?.url);
+  return {
+    arrived,
+    step: {
+      label: t('chat.bloom.visited'),
+      query: url ? domainOf(url) : undefined,
+      icon: RiGlobalLine,
+      ...(ok && url && inv.state === 'result'
+        ? { sources: [source(url, options, str(res?.title))] }
+        : {}),
+    },
+  };
+}
+
+/** How many leading units have arrived. Units are revealed in order, so the first missing one stops the count. */
+function arrivedUnits(mapped: MappedStep[]): number {
+  let revealed = 0;
+  for (const { step, arrived } of mapped) {
+    if (!arrived) break;
+    revealed += step.sources?.length ? 2 : 1;
+  }
+  return revealed;
+}
+
+export interface WebSearchLog {
+  steps: WebSearchStep[];
+  revealed: number;
+}
+
+/**
+ * The `WebSearch` trail of a turn: one step per search, page visit or
+ * research run, with the sources each surfaced.
+ *
+ * `research` is the live `researchProgress` of a research answer. Before the
+ * answer is saved there is no `deepResearch` invocation yet, so the progress
+ * is the step; once it is saved the invocation is, and the live sources only
+ * fill in what the persisted ones lack.
+ */
+export function webSearchLog(
+  invocations: readonly ToolInvocation[] | undefined,
+  research: LiveResearch | undefined,
+  options: WorkLogOptions = {},
+): WebSearchLog {
+  const t = options.t ?? englishWorkLog;
+  const web = (invocations ?? []).filter(isWebInvocation);
+  const mapped = web.map((inv) => webStep(inv, research, options));
+
+  const hasResearchCall = web.some((inv) => inv.toolName === 'deepResearch');
+  if (research && !hasResearchCall) {
+    const cited = extractCitationSources(undefined, research.sources);
+    const found = typeof research.sourcesFound === 'number' ? research.sourcesFound : cited.length;
+    mapped.push({
+      arrived: true,
+      step: {
+        label: t('chat.bloom.researching'),
+        query: str(research.currentQuery),
+        icon: RiBookOpenLine,
+        ...(found > 0 ? { meta: t('chat.bloom.sourceCount', { count: found }) } : {}),
+        ...(cited.length > 0 ? { sources: cited.map((c) => source(c.url, options, c.title)) } : {}),
+      },
+    });
+  }
+
+  return { steps: mapped.map((m) => m.step), revealed: arrivedUnits(mapped) };
+}
+
+/** Argument keys worth a chip, in the order they are shown. */
+const CHIP_KEYS = [
+  'filename',
+  'path',
+  'file',
+  'command',
+  'url',
+  'query',
+  'name',
+  'title',
+  'subject',
+  'to',
+  'handle',
+];
+const CHIP_MAX = 60;
+
+function argChips(args: Record<string, unknown> | undefined): TaskListChip[] {
+  if (!args) return [];
+  const chips: TaskListChip[] = [];
+  for (const key of CHIP_KEYS) {
+    const value = str(args[key]);
+    if (value && value.length <= CHIP_MAX) chips.push({ label: value });
+    if (chips.length === 3) break;
+  }
+  return chips;
+}
+
+const TASK_ICONS: Record<string, NonNullable<TaskListTask['icon']>> = {
+  generateFile: RiFileTextLine,
+  fileEdit: RiFileTextLine,
+  shellExec: RiTerminalBoxLine,
+  codeInterpreter: RiTerminalBoxLine,
+};
+
+export interface TaskListLog {
+  tasks: TaskListTask[];
+  revealed: number;
+}
+
+/**
+ * The `TaskList` of a turn: one task per call that is neither a web step nor
+ * a card, titled from `task-utils.ts`.
+ *
+ * Steps come from what the call really carried: its arguments as chips once
+ * the call is made (the file name for `generateFile`), and how it ended once
+ * the result is in — an error, or a call the turn left behind (`live` false
+ * with no result). A successful call adds no "Done" row: the swap from the
+ * running title to the finished one already says it.
+ */
+export function taskListLog(
+  invocations: readonly ToolInvocation[] | undefined,
+  live: boolean,
+  options: WorkLogOptions = {},
+): TaskListLog {
+  const t = options.t ?? englishWorkLog;
+  let revealed = 0;
+  let open = true;
+  const tasks = (invocations ?? [])
+    .filter((inv) => !isWebInvocation(inv))
+    .map((inv): TaskListTask => {
+      const status = toolCallStatus(inv, live);
+      const steps: TaskListStep[] = [];
+
+      if (inv.toolName === 'generateFile') {
+        const name = str(resultOf(inv)?.filename) ?? str(inv.args?.filename);
+        if (name)
+          steps.push({
+            label: t(status === 'done' ? 'chat.bloom.createdFile' : 'chat.bloom.writingFile'),
+            chips: [{ label: name }],
+          });
+      } else {
+        const chips = argChips(inv.args);
+        if (chips.length > 0) steps.push({ label: t('chat.bloom.taskInput'), chips });
+      }
+      if (status === 'error') steps.push({ label: t('chat.bloom.taskFailed') });
+      if (status === 'interrupted') steps.push({ label: t('chat.bloom.taskStopped') });
+
+      // Header and argument steps land with the call; the outcome with the result.
+      const arrived = inv.state !== 'partial-call';
+      if (open && arrived) revealed += 1 + steps.length;
+      else open = false;
+
+      return {
+        title: getToolDoneLabel(inv.toolName, t),
+        runningTitle: getToolPillLabel(inv.toolName, t),
+        icon: TASK_ICONS[inv.toolName] ?? RiToolsLine,
+        steps,
+      };
+    });
+  return { tasks, revealed };
+}

package/src/tools.ts

@@ -0,0 +1,11 @@
+// @alia.onl/sdk/tools — what a turn's tool calls mean, without the UI.
+// Pure functions: the status of a call, the numbered sources of a research answer, the
+// words for a tool. They load no React Native, so a host's models and tests can use them.
+
+export { extractCitationSources } from './lib/citations';
+export type { CitationSource } from './lib/citations';
+export { getToolDoneLabel, getToolPillLabel } from './lib/task-labels';
+export { toolCallStatus } from './lib/tool-call-status';
+export type { ToolCallStatus } from './lib/tool-call-status';
+export { englishWorkLog } from './lib/work-log-copy';
+export type { Translate } from './lib/work-log-copy';

package/src/types.ts

@@ -115,8 +115,11 @@ export interface VoiceSessionProps {
   apiUrl?: string;
   /** Called on every room, agent, or transcript change. */
   onStateChange: (state: VoiceSessionState) => void;
-  /** The call is over — the user ended it, it errored, or the room dropped. */
-  onEnd: () => void;
+  /**
+   * The call is over — the user ended it, it errored, or the room dropped. When it
+   * failed, say why, so the shell can tell the person instead of silently going back.
+   */
+  onEnd: (error?: string) => void;
 }
 
 /**

package/src/voice.ts

@@ -5,8 +5,6 @@
 
 // ── Voice components ──
 export { VoiceSession } from './components/voice/VoiceSession';
-export { AudioWaveVisualizer } from './components/voice/AudioWaveVisualizer';
-export { VoiceOverlay } from './components/voice/VoiceOverlay';
 export { VoiceControls } from './components/voice/VoiceControls';
 export { VOICE_CONTROLS_LABELS } from './components/voice/VoiceControls';
 export type { VoiceControlsLabels, VoiceControlsProps } from './components/voice/VoiceControls';
@@ -15,14 +13,24 @@ export type { VoiceControlsLabels, VoiceControlsProps } from './components/voice
 export { useVoiceRoom } from './hooks/useVoiceRoom';
 export type { UseVoiceRoomOptions } from './hooks/useVoiceRoom';
 export { createAliaVoiceTurnSender } from './lib/voice-turn';
-export type { VoiceTurn, VoiceTurnMessage, VoiceTurnSender, AliaVoiceTurnSenderOptions } from './lib/voice-turn';
+export type {
+  VoiceTurn,
+  VoiceTurnMessage,
+  VoiceTurnSender,
+  AliaVoiceTurnSenderOptions,
+} from './lib/voice-turn';
 export type { VoiceLevelSource } from './lib/voice-levels';
 export { VOICE_ERROR_MESSAGES } from './lib/speech-messages';
 export type { VoiceErrorCode } from './lib/speech-messages';
 export { useAudioLevelMonitor } from './hooks/useAudioLevelMonitor';
 export { useAudioLevels } from './hooks/useAudioLevels';
 export { useAmbientWave } from './hooks/useAmbientWave';
-export type { UseAmbientWaveOptions, UseAmbientWaveResult, AmbientWaveVoice, AmbientWaveMode } from './hooks/useAmbientWave';
+export type {
+  UseAmbientWaveOptions,
+  UseAmbientWaveResult,
+  AmbientWaveVoice,
+  AmbientWaveMode,
+} from './hooks/useAmbientWave';
 export { useSoundEffects, useVoiceSoundEffects } from './hooks/useSoundEffects';
 export type { SoundName, SoundSources } from './hooks/useSoundEffects';
 

package/src/components/Reasoning.tsx

@@ -1,152 +0,0 @@
-import React, { createContext, useContext, useEffect, useRef, useState } from 'react';
-import { View, Text, Pressable, StyleSheet } from 'react-native';
-import Animated, {
-  useAnimatedStyle,
-  useSharedValue,
-  withRepeat,
-  withTiming,
-  withSequence,
-  cancelAnimation,
-} from 'react-native-reanimated';
-
-
-// Context
-type ReasoningContextType = {
-  isStreaming: boolean;
-  isOpen: boolean;
-  setIsOpen: (open: boolean) => void;
-  duration: number | undefined;
-};
-
-const ReasoningContext = createContext<ReasoningContextType | null>(null);
-
-function useReasoning() {
-  const context = useContext(ReasoningContext);
-  if (!context) throw new Error('useReasoning must be used within a Reasoning component');
-  return context;
-}
-
-// Props
-interface ReasoningProps {
-  isStreaming?: boolean;
-  defaultOpen?: boolean;
-  duration?: number;
-  children: React.ReactNode;
-}
-
-interface ReasoningTriggerProps {
-  onPress?: () => void;
-}
-
-interface ReasoningContentProps {
-  children: string;
-}
-
-// Reasoning wrapper — manages open/close state with auto-open during streaming
-export function Reasoning({ isStreaming = false, defaultOpen = true, duration: externalDuration, children }: ReasoningProps) {
-  const [isOpen, setIsOpen] = useState(defaultOpen);
-  const [duration, setDuration] = useState<number | undefined>(externalDuration);
-  const startTimeRef = useRef<number | null>(null);
-  const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
-
-  useEffect(() => {
-    if (isStreaming) {
-      setIsOpen(true);
-      startTimeRef.current = Date.now();
-      intervalRef.current = setInterval(() => {
-        if (startTimeRef.current) {
-          setDuration(Math.floor((Date.now() - startTimeRef.current) / 1000));
-        }
-      }, 1000);
-    } else {
-      if (intervalRef.current) { clearInterval(intervalRef.current); intervalRef.current = null; }
-      if (startTimeRef.current !== null) {
-        const t = setTimeout(() => setIsOpen(false), 500);
-        return () => clearTimeout(t);
-      }
-    }
-    return () => { if (intervalRef.current) clearInterval(intervalRef.current); };
-  }, [isStreaming]);
-
-  useEffect(() => { if (externalDuration !== undefined) setDuration(externalDuration); }, [externalDuration]);
-
-  return (
-    <ReasoningContext.Provider value={{ isStreaming, isOpen, setIsOpen, duration }}>
-      <View>{children}</View>
-    </ReasoningContext.Provider>
-  );
-}
-
-// Trigger — shows "Thinking for Xs..." label with pulsing icon
-export function ReasoningTrigger({ onPress }: ReasoningTriggerProps) {
-  const { isStreaming, isOpen, setIsOpen, duration } = useReasoning();
-  const pulseOpacity = useSharedValue(1);
-
-  useEffect(() => {
-    if (isStreaming) {
-      pulseOpacity.value = withRepeat(withSequence(withTiming(0.4, { duration: 800 }), withTiming(1, { duration: 800 })), -1, false);
-    } else {
-      cancelAnimation(pulseOpacity);
-      pulseOpacity.value = 1;
-    }
-  }, [isStreaming]);
-
-  const pulseStyle = useAnimatedStyle(() => ({ opacity: pulseOpacity.value }));
-
-  const message = isStreaming
-    ? (duration ? `Thinking for ${duration}s...` : 'Thinking...')
-    : (duration ? `Thought for ${duration} seconds` : 'Reasoning');
-
-  const handlePress = onPress || (() => setIsOpen(!isOpen));
-
-  return (
-    <Pressable onPress={handlePress} style={styles.trigger}>
-      <Animated.View style={isStreaming ? pulseStyle : undefined}>
-        <Text style={{ color: '#a855f7', fontSize: 14 }}>{'\u2726'}</Text>
-      </Animated.View>
-      <Text style={[styles.triggerText, { color: '#a855f7' }]}>{message}</Text>
-      <Text style={{ color: '#a855f7', fontSize: 14 }}>{onPress ? '\u203A' : (isOpen ? '\u25BE' : '\u25B8')}</Text>
-    </Pressable>
-  );
-}
-
-// Content — renders thinking text (collapsible)
-export function ReasoningContent({ children }: ReasoningContentProps) {
-  const { isOpen, isStreaming } = useReasoning();
-
-  if (!isOpen) return null;
-
-  // Lazy import AliaMarkdown to avoid circular dependency
-  const { AliaMarkdown } = require('./Markdown');
-
-  return (
-    <View style={[styles.contentWrapper, { backgroundColor: '#a855f710', borderColor: '#a855f730' }]}>
-      <View style={{ opacity: isStreaming ? 0.8 : 1 }}>
-        <AliaMarkdown content={children} />
-      </View>
-    </View>
-  );
-}
-
-const styles = StyleSheet.create({
-  trigger: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    gap: 8,
-    paddingVertical: 8,
-    paddingHorizontal: 12,
-    borderRadius: 8,
-  },
-  triggerText: {
-    fontSize: 14,
-    fontWeight: '500',
-    flex: 1,
-  },
-  contentWrapper: {
-    borderRadius: 8,
-    padding: 12,
-    borderWidth: 1,
-    marginHorizontal: 12,
-    marginBottom: 12,
-  },
-});