@alia.onl/sdk 13.1.0 → 13.2.0

package/src/index.ts

@@ -26,7 +26,14 @@ export type { AliaMarkdownProps, RenderCodeBlock } from './components/Markdown';
 export { AliaWelcomeMessage } from './components/AliaWelcomeMessage';
 export { PlanPreviewCard } from './components/PlanPreviewCard';
 export { AskedQuestions, QuestionCard } from './components/QuestionCard';
+export { AliaComposer } from './components/AliaComposer';
+export type {
+  AliaComposerProps,
+  AliaComposerQuestions,
+  AliaComposerSuggestions,
+} from './components/AliaComposer';
 export { ComposerSuggestions } from './components/ComposerSuggestions';
+export { usePendingQuestions } from './hooks/usePendingQuestions';
 export { useComposerSuggestions, useSuggestionQuery } from './hooks/useComposerSuggestions';
 export { composerCompletions } from './lib/suggestions';
 export type { Completion } from './lib/suggestions';
@@ -50,6 +57,8 @@ export type { UseTTSOptions } from './hooks/useTTS';
 export { useSpeechToText, useSTTStore } from './hooks/useSpeechToText';
 export { VOICE_ERROR_MESSAGES } from './lib/speech-messages';
 export type { VoiceErrorCode } from './lib/speech-messages';
+export { SpeechClipError } from './lib/speech-synthesis';
+export type { SpeechClipErrorCode } from './lib/speech-synthesis';
 export type { UseSTTOptions } from './hooks/useSpeechToText';
 
 // ── Model catalogue (GET /catalogue) ──
@@ -68,6 +77,7 @@ export type { Catalogue, CatalogueEntry, ModelSelection, ReasoningEffort } from
 export type {
   ChatMessage,
   ToolInvocation,
+  AliaAttachment,
   AliaSuggestion,
   ResearchProgress,
   ResearchSource,

package/src/lib/attachment-intake.ts

@@ -0,0 +1,154 @@
+/**
+ * What the composer will take in, and how far a file has actually got.
+ *
+ * Alia had no answer to either question. A file reached the attachment strip
+ * by exactly one route — a picker that hands back a `uri` and asks nothing —
+ * so there was no size it would refuse, no kind it would separate, and, once
+ * drag-and-drop existed, no shared place to state those rules for a second
+ * route. Worse, a drag is a stateful gesture: the browser fires `dragenter`
+ * and `dragleave` for every element the pointer crosses, so a drop affordance
+ * driven by a boolean flickers off the instant the pointer moves from the bar
+ * onto the textarea INSIDE it. The counter that fixes that is four lines of
+ * arithmetic guarding a visible effect, which is precisely the kind of thing
+ * that is easy to get subtly wrong and almost impossible to watch going wrong.
+ *
+ * So it lives here, beside `turn-selection.ts`, under the same rule: nothing
+ * in this file may import react-native, read a store, or touch the DOM. The
+ * reader that moves the bytes is a platform adapter and lives with the
+ * composer; what can be decided by arithmetic is decided here, where it can be
+ * checked without mounting a composer or staging a drag.
+ */
+
+/**
+ * The largest file the composer will take.
+ *
+ * An attached image is not uploaded anywhere — the app's `attachment-utils.ts`
+ * inlines it into the request as a `data:` URL — so its bytes are carried in
+ * memory as a base64 string roughly a third larger than the file, twice over
+ * while the request is built. 20 MiB is the point past which that stops being
+ * a message and starts being a reason the tab dies.
+ */
+export const MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
+
+export type IntakeKind = 'image' | 'document';
+
+/** Why a file was turned away. Each one has its own sentence to the user. */
+export type IntakeRefusal = 'empty' | 'too-large' | 'unsupported';
+
+export type IntakeVerdict =
+  | { accepted: true; kind: IntakeKind }
+  | { accepted: false; refusal: IntakeRefusal };
+
+export interface IntakeCandidate {
+  name: string;
+  mimeType: string;
+  size: number;
+}
+
+/**
+ * Extensions that name a picture when the browser will not.
+ *
+ * A dragged file's `type` is filled in from the OS, and it comes through empty
+ * often enough to matter — from an archive manager, from a file manager with a
+ * thin mime database, from anything that drops a path rather than a handle.
+ * Falling back to the name is not a nicety: without it a dropped `.png` is
+ * filed as a document, and a document is never inlined into the request at all.
+ */
+const IMAGE_EXTENSIONS = ['png', 'jpg', 'jpeg', 'gif', 'webp', 'bmp', 'avif', 'heic', 'heif'];
+
+/**
+ * Whether a candidate is a picture, by what the browser says first and by its
+ * name only when the browser said nothing.
+ */
+export function intakeKind(candidate: IntakeCandidate): IntakeKind {
+  if (candidate.mimeType.startsWith('image/')) return 'image';
+  const extension = candidate.name.split('.').pop()?.toLowerCase() ?? '';
+  return IMAGE_EXTENSIONS.includes(extension) ? 'image' : 'document';
+}
+
+/**
+ * The one gate both web routes pass through — pasted files and dropped ones —
+ * so a rule cannot hold for one and not the other.
+ *
+ * The zero-byte refusal is not pedantry about empty files. Dropping a FOLDER
+ * on web yields a `File` with size 0 and no type, in every browser; without
+ * this the composer accepts a tile named after a directory whose contents it
+ * will never have, and whose read completes with nothing in it.
+ */
+export function classifyIntake(candidate: IntakeCandidate): IntakeVerdict {
+  if (candidate.size <= 0) return { accepted: false, refusal: 'empty' };
+  if (candidate.size > MAX_ATTACHMENT_BYTES) return { accepted: false, refusal: 'too-large' };
+  return { accepted: true, kind: intakeKind(candidate) };
+}
+
+/** The four things that can happen to the count of drags over the composer. */
+export type DragStep = 'enter' | 'leave' | 'drop' | 'reset';
+
+/**
+ * How many dragged-over elements deep the pointer is.
+ *
+ * `dragenter` and `dragleave` fire per ELEMENT, not per target, and they fire
+ * in that order: moving from the bar onto the textarea inside it produces
+ * `dragenter` (textarea) then `dragleave` (bar). A boolean set by enter and
+ * cleared by leave therefore ends that move switched OFF while the pointer is
+ * still over the composer, and the affordance strobes as the pointer crosses
+ * each child on the way in. Counting elements instead is the standard answer,
+ * and the depth only reaches zero when the pointer has genuinely left
+ * everything.
+ *
+ * `drop` resets rather than decrements: the browser does not send the matching
+ * `dragleave` for the element the file landed on, so a decrement leaves the
+ * count stuck at one and the overlay pinned over the composer for good.
+ */
+export function nextDragDepth(depth: number, step: DragStep): number {
+  switch (step) {
+    case 'enter':
+      return depth + 1;
+    case 'leave':
+      // Clamped, because a `dragleave` can arrive without its `dragenter` — a
+      // drag that began before the listener was attached, or one whose
+      // `dragenter` was swallowed by an element that stopped propagation. A
+      // negative depth would then need two full entries before the overlay
+      // came back.
+      return Math.max(0, depth - 1);
+    case 'drop':
+    case 'reset':
+      return 0;
+  }
+}
+
+/**
+ * Whether this drag is carrying files at all.
+ *
+ * `DataTransfer.types` contains the literal `"Files"` when it is; dragging
+ * selected text or a link gives `"text/plain"` and `"text/uri-list"` instead.
+ * Without the question the composer lights up when the user drags a word
+ * across it, and then swallows the drop.
+ */
+export function dragCarriesFiles(types: readonly string[] | undefined): boolean {
+  return types !== undefined && types.includes('Files');
+}
+
+/**
+ * How far a read has got, as a fraction — or `null` when nothing measurable
+ * was reported.
+ *
+ * `null` is the important return, and it is why this is a function rather than
+ * a division at the call site. #608 §7: "Cuando no hay avance medible, mostrar
+ * actividad indeterminada. No inventar porcentajes." A `ProgressEvent` whose
+ * `lengthComputable` is false carries a `total` of 0, and dividing by it gives
+ * `NaN` or `Infinity` — both of which render as SOMETHING once handed to a
+ * bar, and that something is invented. Bloom's `use-attachment-queue.ts`
+ * invents its number outright, from a `Math.random()` ramp on a 50ms tick;
+ * nothing in this file may grow a timer.
+ */
+export function readFraction(progress: {
+  lengthComputable: boolean;
+  loaded: number;
+  total: number;
+}): number | null {
+  if (!progress.lengthComputable) return null;
+  if (!Number.isFinite(progress.total) || progress.total <= 0) return null;
+  if (!Number.isFinite(progress.loaded) || progress.loaded < 0) return null;
+  return Math.min(1, progress.loaded / progress.total);
+}

package/src/lib/attachment-tiles.ts

@@ -0,0 +1,74 @@
+import type { ComposerPanelAttachment } from '@oxy.so/bloom/composer-panel';
+import type { IntakeItem } from '../hooks/useAttachmentIntake';
+import type { AliaAttachment } from '../types';
+import { MAX_ATTACHMENT_BYTES } from './attachment-intake';
+import type { AliaChatLabels } from './labels';
+
+/**
+ * The composer's tiles: landed files, then the ones the intake still holds.
+ *
+ * A file whose read failed, or that was refused, stays in the strip with the
+ * sentence that says why — a drop of six where one did not make it is a
+ * sentence the user needs beside the five that did, not a toast that slides
+ * away. `retryable` marks the ones a second read could fix: a failed read,
+ * whose `File` the intake kept. A refusal is not: the same 30 MB file reaches
+ * the same verdict — and since Bloom's retry button is the panel's, drawn on
+ * every error tile once `onAttachmentRetry` is set, the composer shows a
+ * refusal as a toast rather than as a tile it would offer to retry.
+ */
+export interface ComposerTile extends ComposerPanelAttachment {
+  error?: string;
+  retryable?: boolean;
+}
+
+/** The words a tile and a refusal use. */
+type TileLabels = Pick<
+  AliaChatLabels,
+  'composerUntitled' | 'fileReadFailed' | 'fileTooLarge' | 'fileEmpty' | 'fileUnsupported'
+>;
+
+/** Why an intake item is not an attachment, or `undefined` while it is being read. */
+export function intakeError(item: IntakeItem, labels: TileLabels): string | undefined {
+  const name = item.name || labels.composerUntitled;
+  switch (item.status) {
+    case 'reading':
+      return undefined;
+    case 'failed':
+      return labels.fileReadFailed(name);
+    case 'refused':
+      if (item.refusal === 'unsupported') return labels.fileUnsupported(name);
+      return item.refusal === 'too-large'
+        ? labels.fileTooLarge(name, `${Math.round(MAX_ATTACHMENT_BYTES / (1024 * 1024))} MB`)
+        : labels.fileEmpty(name);
+  }
+}
+
+export function composerTiles(
+  attachments: readonly AliaAttachment[],
+  items: readonly IntakeItem[],
+  labels: TileLabels,
+): ComposerTile[] {
+  return [
+    ...attachments.map((a) => ({
+      id: a.id,
+      name: a.name,
+      kind: a.type === 'image' ? ('image' as const) : ('document' as const),
+      src: a.type === 'image' ? a.uri : undefined,
+    })),
+    ...items.map((item): ComposerTile => {
+      const tile: ComposerTile = {
+        id: item.id,
+        name: item.name || labels.composerUntitled,
+        kind: item.kind === 'image' ? 'image' : 'document',
+      };
+      if (item.status === 'reading') {
+        // Real progress only; an unmeasured read is an empty ring, not a guess.
+        tile.progress = item.fraction === null ? 0 : Math.round(item.fraction * 100);
+        return tile;
+      }
+      tile.error = intakeError(item, labels);
+      tile.retryable = item.status === 'failed';
+      return tile;
+    }),
+  ];
+}

package/src/lib/labels.tsx

@@ -1,4 +1,5 @@
 import { createContext, type ReactNode, useContext, useMemo } from 'react';
+import { VOICE_ERROR_MESSAGES, type VoiceErrorCode } from './speech-messages';
 import { englishWorkLog, type Translate } from './work-log-copy';
 
 /** Every string the chat UI draws itself. Bloom's own copy follows `BloomProvider locale`. */
@@ -15,6 +16,32 @@ export interface AliaChatLabels {
   addPhotos: string;
   startVoice: string;
   voiceFailed: string;
+  /** The field's accessible name. */
+  composerMessage: string;
+  /** The add button's accessible name. */
+  composerAddMenu: string;
+  /** The mode selector's accessible name (the host's power levels). */
+  composerModes: string;
+  /** The dictation button's accessible name. */
+  composerVoice: string;
+  composerSend: string;
+  composerStop: string;
+  /** A tile's remove button. */
+  composerRemove: string;
+  /** Bloom names a retry button "<this> <file name>". */
+  composerRetry: string;
+  /** What a tile without a file name is called. */
+  composerUntitled: string;
+  fileReadFailed: (name: string) => string;
+  fileTooLarge: (name: string, limit: string) => string;
+  fileEmpty: (name: string) => string;
+  /** A file of a kind the chat cannot send (a document, where only photos go). */
+  fileUnsupported: (name: string) => string;
+  /** Over the composer while a file is dragged onto it. */
+  dropHint: string;
+  dropUnavailable: string;
+  /** Why dictation failed, in the host's language. */
+  voiceError: (code: VoiceErrorCode) => string;
   // Welcome
   /** The empty chat's greeting for a signed-out visitor. */
   greeting: string;
@@ -56,6 +83,22 @@ export const DEFAULT_LABELS: AliaChatLabels = {
   addPhotos: 'Photos',
   startVoice: 'Start voice',
   voiceFailed: "Couldn't start the voice call",
+  composerMessage: 'Message',
+  composerAddMenu: 'Add to chat',
+  composerModes: 'Power level',
+  composerVoice: 'Dictate',
+  composerSend: 'Send message',
+  composerStop: 'Stop generating',
+  composerRemove: 'Remove',
+  composerRetry: 'Retry',
+  composerUntitled: 'untitled',
+  fileReadFailed: (name) => `${name} could not be read — select to try again`,
+  fileTooLarge: (name, limit) => `${name} is larger than ${limit} and was not attached`,
+  fileEmpty: (name) => `${name} is empty — folders can't be attached`,
+  fileUnsupported: (name) => `${name} can't be sent here — only photos can`,
+  dropHint: 'Drop files here to attach them',
+  dropUnavailable: "Files can't be attached right now",
+  voiceError: (code) => VOICE_ERROR_MESSAGES[code],
   greeting: "Hi, what's on your mind?",
   greetingNamed: (name) => `Hi ${name}, what's on your mind?`,
   copy: 'Copy',
@@ -87,7 +130,10 @@ export function AliaChatLabelsProvider({
   labels?: Partial<AliaChatLabels>;
   children: ReactNode;
 }) {
-  const value = useMemo(() => ({ ...DEFAULT_LABELS, ...labels }), [labels]);
+  // Over whatever labels are already in reach, so a part that takes its own `labels` (the
+  // composer) refines the chat's copy instead of resetting it to English.
+  const inherited = useContext(LabelsContext);
+  const value = useMemo(() => ({ ...inherited, ...labels }), [inherited, labels]);
   return <LabelsContext.Provider value={value}>{children}</LabelsContext.Provider>;
 }
 

package/src/lib/speech-messages.ts

@@ -1,4 +1,5 @@
 import type { SpeechRecognitionFailure } from './speech-recognition-types';
+import type { SpeechClipError } from './speech-synthesis';
 
 /**
  * Every way dictation or a voice call can fail that a person is told about,
@@ -20,7 +21,11 @@ export type VoiceErrorCode =
   | 'not-authenticated'
   | 'turn-failed'
   | 'no-answer'
-  | 'not-played';
+  | 'not-played'
+  | 'synthesis-unavailable'
+  | 'synthesis-limited'
+  | 'synthesis-rejected'
+  | 'synthesis-failed';
 
 /**
  * The English copy for each code — the same sentences dictation and voice mode
@@ -39,9 +44,36 @@ export const VOICE_ERROR_MESSAGES: Readonly<Record<VoiceErrorCode, string>> = {
   'not-authenticated': 'Not authenticated',
   'turn-failed': 'Voice request failed',
   'no-answer': 'No answer came back — try saying it again',
-  'not-played': 'The answer could not be played aloud',
+  'not-played': 'The answer could not be played aloud — it is in the chat',
+  'synthesis-unavailable': "Alia's voice is not available right now — the answer is in the chat",
+  'synthesis-limited': "Alia's voice has reached its limit for now — the answer is in the chat",
+  'synthesis-rejected': "Alia's voice could not read this answer — it is in the chat",
+  'synthesis-failed': "Alia's voice failed — the answer is in the chat",
 };
 
+/**
+ * The code for a clip `/v1/audio/speech` could not make, from the typed code
+ * the route answered with. A failure the route did not name (a network
+ * failure, an unknown code) is `synthesis-failed`.
+ */
+export function synthesisFailureCode(failure: SpeechClipError): VoiceErrorCode {
+  switch (failure.code) {
+    case 'NOT_AUTHENTICATED':
+      return 'not-authenticated';
+    case 'SPEECH_UNAVAILABLE':
+      return 'synthesis-unavailable';
+    case 'SPEECH_LIMIT_REACHED':
+      return 'synthesis-limited';
+    case 'SPEECH_REJECTED':
+    case 'INVALID_REQUEST':
+      return 'synthesis-rejected';
+    case 'SPEECH_PROVIDER_FAILED':
+    case 'SPEECH_GENERATION_FAILED':
+    case null:
+      return 'synthesis-failed';
+  }
+}
+
 /**
  * The code for a recognition failure. `null` for the failures that are not
  * errors: `aborted` is a stop the caller asked for, and `no-speech` is a

package/src/lib/speech-synthesis.ts

@@ -26,8 +26,102 @@ export interface SpeechClipRequest {
   readonly signal: AbortSignal;
 }
 
-/** Synthesize `input` and return the private link the route answers with. */
+/**
+ * The codes `/v1/audio/speech` answers a failure with, plus the two this side
+ * knows on its own: `NOT_AUTHENTICATED` (no session token, or the route said
+ * 401) and `INVALID_REQUEST` (the route refused the body).
+ */
+export type SpeechClipErrorCode =
+  | 'SPEECH_UNAVAILABLE'
+  | 'SPEECH_REJECTED'
+  | 'SPEECH_LIMIT_REACHED'
+  | 'SPEECH_PROVIDER_FAILED'
+  | 'SPEECH_GENERATION_FAILED'
+  | 'INVALID_REQUEST'
+  | 'NOT_AUTHENTICATED';
+
+const SERVER_CODES: ReadonlySet<string> = new Set<SpeechClipErrorCode>([
+  'SPEECH_UNAVAILABLE',
+  'SPEECH_REJECTED',
+  'SPEECH_LIMIT_REACHED',
+  'SPEECH_PROVIDER_FAILED',
+  'SPEECH_GENERATION_FAILED',
+  'INVALID_REQUEST',
+]);
+
+/**
+ * A clip that could not be made, with what the route said about it: the HTTP
+ * status (`null` when no request was answered) and its typed `code` (`null`
+ * when the route named none this SDK knows — a network failure, an older or
+ * newer server).
+ */
+export class SpeechClipError extends Error {
+  readonly status: number | null;
+  readonly code: SpeechClipErrorCode | null;
+  readonly retryable: boolean;
+  /** Oxy's request id, for support, when the route gave one. */
+  readonly requestId: string | null;
+
+  constructor(
+    message: string,
+    details: {
+      status: number | null;
+      code: SpeechClipErrorCode | null;
+      retryable?: boolean;
+      requestId?: string | null;
+    },
+  ) {
+    super(message);
+    this.name = 'SpeechClipError';
+    this.status = details.status;
+    this.code = details.code;
+    this.retryable = details.retryable ?? false;
+    this.requestId = details.requestId ?? null;
+  }
+}
+
+function clipErrorFrom(status: number, body: unknown): SpeechClipError {
+  const envelope =
+    body !== null && typeof body === 'object' ? (body as { error?: unknown }).error : undefined;
+  const error =
+    envelope !== null && typeof envelope === 'object'
+      ? (envelope as {
+          code?: unknown;
+          message?: unknown;
+          retryable?: unknown;
+          requestId?: unknown;
+        })
+      : {};
+  const named =
+    typeof error.code === 'string' && SERVER_CODES.has(error.code)
+      ? (error.code as SpeechClipErrorCode)
+      : null;
+  const code = named ?? (status === 401 ? 'NOT_AUTHENTICATED' : null);
+  const message =
+    status === 504
+      ? 'Request timed out — please try again'
+      : typeof error.message === 'string' && error.message !== ''
+        ? error.message
+        : typeof envelope === 'string' && envelope !== ''
+          ? envelope
+          : 'TTS failed';
+  return new SpeechClipError(message, {
+    status,
+    code,
+    retryable: error.retryable === true,
+    requestId: typeof error.requestId === 'string' ? error.requestId : null,
+  });
+}
+
+/**
+ * Synthesize `input` and return the private link the route answers with.
+ *
+ * @throws {SpeechClipError} when the route refuses or answers no link; a
+ *   network failure or an abort is thrown as `fetch` threw it.
+ */
 export async function requestSpeechClip(request: SpeechClipRequest): Promise<string> {
+  if (request.token === '')
+    throw new SpeechClipError('Not authenticated', { status: null, code: 'NOT_AUTHENTICATED' });
   const response = await fetch(`${request.apiUrl}/v1/audio/speech`, {
     method: 'POST',
     signal: request.signal,
@@ -46,16 +140,13 @@ export async function requestSpeechClip(request: SpeechClipRequest): Promise<str
   });
 
   if (!response.ok) {
-    if (response.status === 504) {
-      throw new Error('Request timed out — please try again');
-    }
-    const errData = await response.json().catch(() => ({}));
-    throw new Error(errData.error?.message || errData.error || 'TTS failed');
+    throw clipErrorFrom(response.status, await response.json().catch(() => null));
   }
 
-  const data = (await response.json()) as { audioUrl?: unknown };
+  const data = (await response.json().catch(() => ({}))) as { audioUrl?: unknown };
   request.signal.throwIfAborted();
-  if (typeof data.audioUrl !== 'string' || data.audioUrl === '') throw new Error('TTS failed');
+  if (typeof data.audioUrl !== 'string' || data.audioUrl === '')
+    throw new SpeechClipError('TTS failed', { status: response.status, code: null });
   return data.audioUrl;
 }
 

package/src/tools.ts

@@ -19,6 +19,7 @@ export {
   pendingQuestions,
 } from './lib/questions';
 export type { AskedOption, AskedQuestion, QuestionAnswer } from './lib/questions';
+export { classifyIntake, MAX_ATTACHMENT_BYTES } from './lib/attachment-intake';
 export { toolCallStatus } from './lib/tool-call-status';
 export type { ToolCallStatus } from './lib/tool-call-status';
 export { englishWorkLog } from './lib/work-log-copy';

package/src/types.ts

@@ -9,6 +9,20 @@ export interface AliaSuggestion {
   text: string;
 }
 
+// ── Composer Types ──
+
+/** A file in the composer's draft, on its way into a turn. */
+export interface AliaAttachment {
+  id: string;
+  /** A `data:` URL once read; a picker's `blob:`/`file:` URI for a photo not yet read. */
+  uri: string;
+  type: 'image' | 'document';
+  name: string;
+  size: number;
+  mimeType: string;
+  isLoading?: boolean;
+}
+
 // ── Chat Message Types ──
 
 export interface ResearchSource {

package/src/voice.ts

@@ -22,6 +22,8 @@ export type {
 export type { VoiceLevelSource } from './lib/voice-levels';
 export { VOICE_ERROR_MESSAGES } from './lib/speech-messages';
 export type { VoiceErrorCode } from './lib/speech-messages';
+export { SpeechClipError } from './lib/speech-synthesis';
+export type { SpeechClipErrorCode } from './lib/speech-synthesis';
 export { useAudioLevelMonitor } from './hooks/useAudioLevelMonitor';
 export { useAudioLevels } from './hooks/useAudioLevels';
 export { useAmbientWave } from './hooks/useAmbientWave';