@alia.onl/sdk 15.7.0 → 19.0.0

package/src/runtime/api.ts

@@ -0,0 +1,123 @@
+import { useOxy } from '@oxy.so/services/ui/client';
+import { useMemo } from 'react';
+import { useAliaRuntime } from './config';
+
+/**
+ * A refusal or failure from Alia's API, shaped so the helpers in
+ * `error-utils.ts` read it: `status`, and the parsed body under
+ * `response.data`.
+ */
+export class AliaApiError extends Error {
+  readonly status: number;
+  readonly response: { status: number; data: unknown };
+
+  constructor(status: number, data: unknown, message?: string) {
+    super(message ?? `Alia request failed with status ${status}.`);
+    this.name = 'AliaApiError';
+    this.status = status;
+    this.response = { status, data };
+  }
+}
+
+export interface AliaApiResult<T> {
+  status: number;
+  data: T;
+}
+
+export interface AliaApiRequest {
+  params?: Record<string, string | number | undefined>;
+  body?: unknown;
+  signal?: AbortSignal;
+}
+
+/**
+ * Alia's REST API for the signed-in person. Authentication, the preflight
+ * refresh and the single 401 replay belong to the linked Oxy client; this
+ * layer never reads or writes a bearer itself.
+ */
+export interface AliaApi {
+  get<T>(path: string, request?: AliaApiRequest): Promise<AliaApiResult<T>>;
+  post<T>(path: string, body?: unknown, request?: AliaApiRequest): Promise<AliaApiResult<T>>;
+  patch<T>(path: string, body?: unknown, request?: AliaApiRequest): Promise<AliaApiResult<T>>;
+  delete<T>(path: string, request?: AliaApiRequest): Promise<AliaApiResult<T>>;
+}
+
+function withParams(path: string, params: AliaApiRequest['params']): string {
+  if (!params) return path;
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined) search.append(key, String(value));
+  }
+  const query = search.toString();
+  return query === '' ? path : `${path}${path.includes('?') ? '&' : '?'}${query}`;
+}
+
+async function readBody(response: Response): Promise<unknown> {
+  const text = await response.text().catch(() => '');
+  if (text === '') return undefined;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+/** The structural slice of `OxyServices` the API layer needs. */
+export interface LinkableOxy {
+  createLinkedClient(config: { baseURL: string }): {
+    client: {
+      requestAuthenticatedResponse(config: {
+        method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+        url: string;
+        body?: string;
+        headers?: Record<string, string>;
+        signal?: AbortSignal;
+        fetch?: typeof fetch;
+      }): Promise<Response>;
+    };
+    dispose(): void;
+  };
+}
+
+/** Build the API over an Oxy client for `apiUrl`. Exposed for tests and for non-React callers. */
+export function createAliaApi(oxyServices: LinkableOxy, apiUrl: string): AliaApi {
+  async function send<T>(
+    method: 'GET' | 'POST' | 'PATCH' | 'DELETE',
+    path: string,
+    request: AliaApiRequest = {},
+  ): Promise<AliaApiResult<T>> {
+    const linked = oxyServices.createLinkedClient({ baseURL: apiUrl });
+    try {
+      const response = await linked.client.requestAuthenticatedResponse({
+        method,
+        url: withParams(path, request.params),
+        ...(request.body === undefined
+          ? {}
+          : {
+              body: JSON.stringify(request.body),
+              headers: { 'Content-Type': 'application/json' },
+            }),
+        ...(request.signal ? { signal: request.signal } : {}),
+      });
+      const data = await readBody(response);
+      if (!response.ok) throw new AliaApiError(response.status, data);
+      return { status: response.status, data: data as T };
+    } finally {
+      linked.dispose();
+    }
+  }
+
+  return {
+    get: (path, request) => send('GET', path, request),
+    post: (path, body, request) => send('POST', path, { ...request, body: body ?? {} }),
+    patch: (path, body, request) => send('PATCH', path, { ...request, body: body ?? {} }),
+    delete: (path, request) => send('DELETE', path, request),
+  };
+}
+
+/** Alia's REST API for the nearest runtime's `apiUrl`, as the signed-in person. */
+export function useAliaApi(): AliaApi {
+  const { oxyServices } = useOxy();
+  const { apiUrl } = useAliaRuntime();
+  return useMemo(() => createAliaApi(oxyServices as LinkableOxy, apiUrl), [oxyServices, apiUrl]);
+}

package/src/runtime/attachment-utils.ts

@@ -0,0 +1,96 @@
+import type { AliaAttachment } from '../types';
+
+export type MessageContentPart =
+  | { type: 'text'; text: string }
+  | { type: 'image_url'; image_url: { url: string } }
+  | { type: 'file'; file: { file_id: string; filename: string; mime: string } };
+
+export interface BuiltMessageContent {
+  content: string | MessageContentPart[];
+  /**
+   * Attachments the request does NOT carry, so the caller can say so.
+   *
+   * Never empty silently: everything here was visibly attached in the composer,
+   * and a file that appears attached and then is not sent is the failure #608
+   * §1.6 is about — a visible state that does not correspond to a real
+   * capability.
+   */
+  dropped: DroppedAttachment[];
+}
+
+export interface DroppedAttachment {
+  name: string;
+  /**
+   * `unsupported` — the chat has no way to send a document (no upload was given).
+   * `unreadable` — an image whose bytes could not be read off the device, or a
+   * document that could not be uploaded.
+   */
+  reason: 'unsupported' | 'unreadable';
+}
+
+/** Puts a document in the person's Oxy Files and answers its id. */
+export type UploadDocument = (attachment: AliaAttachment) => Promise<string>;
+
+/**
+ * The request body for a turn that carries attachments, and an account of what
+ * it could not carry.
+ *
+ * A photo travels inline, as an `image_url` part with its `data:` URL. A
+ * document travels as a `file` part naming an Oxy Files id
+ * (`docs/agent-embedding.md` §5): it is uploaded to the person's Files first,
+ * with `upload`, and a chat given no `upload` cannot send documents and says so.
+ */
+export async function buildMessageContent(
+  text: string,
+  attachments: AliaAttachment[],
+  upload?: UploadDocument,
+): Promise<BuiltMessageContent> {
+  const dropped: DroppedAttachment[] = [];
+
+  const usable = attachments.filter((att) => {
+    if (!att.uri) return false;
+    if (att.type !== 'image' && upload === undefined) {
+      dropped.push({ name: att.name, reason: 'unsupported' });
+      return false;
+    }
+    return true;
+  });
+
+  if (usable.length === 0) return { content: text, dropped };
+
+  const parts: MessageContentPart[] = [{ type: 'text', text }];
+
+  // The readers need the platform's file access, loaded on the first attachment: a turn of plain
+  // text (and everything that imports this module) never touches it.
+  const { imageUriToDataUrl } = await import('../lib/image-data-url');
+  for (const att of usable) {
+    if (att.type !== 'image' && upload !== undefined) {
+      try {
+        const fileId = await upload(att);
+        parts.push({
+          type: 'file',
+          file: { file_id: fileId, filename: att.name, mime: att.mimeType },
+        });
+      } catch {
+        dropped.push({ name: att.name, reason: 'unreadable' });
+      }
+      continue;
+    }
+    try {
+      parts.push({
+        type: 'image_url',
+        image_url: { url: await imageUriToDataUrl(att.uri, att.mimeType) },
+      });
+    } catch {
+      // Reported rather than skipped. A picture that did not arrive is worth
+      // a sentence; it used to be a `continue`.
+      dropped.push({ name: att.name, reason: 'unreadable' });
+    }
+  }
+
+  // Every attachment failed, so the parts array is a text part and nothing
+  // else — which is just the text, said in a more expensive way.
+  if (parts.length === 1) return { content: text, dropped };
+
+  return { content: parts, dropped };
+}

package/src/runtime/composer-draft-store.ts

@@ -0,0 +1,270 @@
+import { useMemo } from 'react';
+import { create } from 'zustand';
+import type { AliaAttachment } from '../types';
+
+/**
+ * What a composer is holding before it is sent: the text, the attachments and
+ * the turn's own choices (connector, skills). One record per account and
+ * composer, and the only place any of it lives.
+ *
+ * ## Why this replaced three owners
+ *
+ * The text was `useState` inside each mounted chat screen, the attachments
+ * were ONE global list in `global-store.ts`, and a draft handed from elsewhere
+ * (a failed send, the memory settings) travelled through a third slot,
+ * `composerDraft`, that every mounted screen read on every render and matched
+ * against its own id with a sequence number. The drawer keeps each visited
+ * chat mounted, so the attachment list was on every one of them at once — a
+ * picture added in one chat was sitting in the composer of the next — and
+ * nothing reset any of it when the account changed, so profile B was handed
+ * profile A's half-written message and files (#608 §4).
+ *
+ * Now each composer names its draft by {@link DraftTarget}, reads only that
+ * one, and a hand-off is a write to the target's record: there is nothing to
+ * broadcast and nothing to "consume".
+ *
+ * ## Accounts
+ *
+ * The store holds the drafts of ONE account, the one bound by the app layout
+ * (`bindAccount`). Moving to a different account, or signing out, drops every
+ * draft and releases what their attachments were holding. The one exception
+ * is signing IN from signed-out: the drafts carry over, because they were
+ * typed by the person now signing in — "continue without an account" leaves
+ * a draft that must still be there after the sign-in its send opened (#608
+ * §3.2).
+ *
+ * Every write names the account it was made for ({@link DraftAddress}). A
+ * write for an account that is no longer bound — a send that fails after the
+ * switch, a picker that resolves after it — is refused and its attachments
+ * released, so a slow answer for A cannot land in B's composer.
+ *
+ * ## Not persisted
+ *
+ * A picture is a `data:` or `blob:` URL; writing megabytes of base64 into
+ * AsyncStorage on every keystroke is not a draft feature worth its cost, and a
+ * `blob:` URL does not survive a reload anyway.
+ */
+
+/**
+ * Which composer: a conversation's id, `null` for the new-chat screen (ghost
+ * included — it is the same screen), or a `surface:` name for a screen that
+ * asks Alia something outside a chat.
+ */
+export type DraftTarget = string | null;
+
+/** A draft's owner at the time the address was taken. */
+export interface DraftAddress {
+  account: string | null;
+  target: DraftTarget;
+}
+
+export interface ComposerDraft {
+  text: string;
+  attachments: AliaAttachment[];
+  /** The connector chosen for the next turn. */
+  mcpServerId: string | null;
+  /** The skills chosen for the next turn. */
+  skillNames: string[];
+  /**
+   * Set while the composer is rewriting a turn already sent rather than
+   * writing a new one: its send replaces that turn and everything after it.
+   * Absent for an ordinary draft.
+   */
+  editing?: DraftEdit;
+}
+
+export type DraftTurn = Pick<ComposerDraft, 'mcpServerId' | 'skillNames'>;
+
+/** What the composer held before an edit took it over, for a cancel to give back. */
+export type DraftBeforeEdit = Pick<ComposerDraft, 'text' | 'mcpServerId' | 'skillNames'>;
+
+export interface DraftEdit {
+  /** The user turn being rewritten. */
+  messageId: string;
+  before: DraftBeforeEdit;
+}
+
+/** The turn an edit loads into the composer: its words and the options it was sent with. */
+export interface EditedTurn extends DraftTurn {
+  messageId: string;
+  text: string;
+}
+
+export const EMPTY_DRAFT: ComposerDraft = Object.freeze({
+  text: '',
+  attachments: [],
+  mcpServerId: null,
+  skillNames: [],
+}) as ComposerDraft;
+
+/**
+ * Give back a temporary URL, if this one is temporary.
+ *
+ * On web both pickers — and a dropped document — hand back
+ * `URL.createObjectURL(file)`, which pins the file's bytes in the page until
+ * it is revoked. `data:` and `file://` URLs are plain strings: nothing to give
+ * back.
+ */
+export function releaseAttachmentUri(uri: string | undefined): void {
+  if (uri === undefined || !uri.startsWith('blob:')) return;
+  if (typeof URL === 'undefined' || typeof URL.revokeObjectURL !== 'function') return;
+  URL.revokeObjectURL(uri);
+}
+
+export function releaseAttachments(attachments: readonly AliaAttachment[]): void {
+  for (const attachment of attachments) releaseAttachmentUri(attachment.uri);
+}
+
+const keyOf = (target: DraftTarget) => target ?? '';
+
+interface DraftStoreState {
+  /** The account whose drafts these are; `null` while signed out. */
+  account: string | null;
+  drafts: Record<string, ComposerDraft>;
+
+  bindAccount: (userId: string | null) => void;
+  /** The address of `target` under the account bound now. */
+  address: (target: DraftTarget) => DraftAddress;
+
+  setText: (address: DraftAddress, text: string) => void;
+  addAttachment: (address: DraftAddress, attachment: AliaAttachment) => void;
+  /** Takes the tile away and releases its URL. */
+  removeAttachment: (address: DraftAddress, id: string) => void;
+  /** Change the turn's connector and skills, from what the draft holds now. */
+  updateTurn: (address: DraftAddress, change: (turn: DraftTurn) => DraftTurn) => void;
+  /**
+   * Put a draft back — a send that failed, or text another screen hands to a
+   * composer. The fields given replace the draft's; attachments given are put
+   * back in front of any added since, which are kept.
+   */
+  restore: (address: DraftAddress, draft: Partial<ComposerDraft>) => void;
+  /**
+   * Empty the draft for a send. The attachments are NOT released: the send
+   * still needs them, and a failed one hands them back through `restore`.
+   */
+  clear: (address: DraftAddress) => void;
+  /**
+   * Load a sent turn into the composer to be rewritten. What the composer held
+   * is kept aside (attachments stay where they are), and a second edit started
+   * before the first is sent or cancelled keeps the ORIGINAL draft aside, not
+   * the first edit's text.
+   */
+  startEdit: (address: DraftAddress, turn: EditedTurn) => void;
+  /** Leave edit mode and give the composer back what it held before. */
+  cancelEdit: (address: DraftAddress) => void;
+}
+
+export const useComposerDraftStore = create<DraftStoreState>((set, get) => {
+  /** Apply `change` to the target's draft, if the address is still current. */
+  const write = (
+    address: DraftAddress,
+    change: (draft: ComposerDraft) => ComposerDraft | null,
+    rejected?: () => void,
+  ) => {
+    if (address.account !== get().account) {
+      rejected?.();
+      return;
+    }
+    set((state) => {
+      const key = keyOf(address.target);
+      const next = change(state.drafts[key] ?? EMPTY_DRAFT);
+      const drafts = { ...state.drafts };
+      if (next === null) delete drafts[key];
+      else drafts[key] = next;
+      return { drafts };
+    });
+  };
+
+  return {
+    account: null,
+    drafts: {},
+
+    bindAccount: (userId) => {
+      const { account, drafts } = get();
+      if (userId === account) return;
+      // Signed out -> signed in: the same person, carrying what they typed.
+      if (account === null) {
+        set({ account: userId });
+        return;
+      }
+      for (const draft of Object.values(drafts)) releaseAttachments(draft.attachments);
+      set({ account: userId, drafts: {} });
+    },
+
+    address: (target) => ({ account: get().account, target }),
+
+    setText: (address, text) => write(address, (draft) => ({ ...draft, text })),
+
+    addAttachment: (address, attachment) =>
+      write(
+        address,
+        (draft) => ({ ...draft, attachments: [...draft.attachments, attachment] }),
+        () => releaseAttachmentUri(attachment.uri),
+      ),
+
+    removeAttachment: (address, id) =>
+      write(address, (draft) => {
+        const removed = draft.attachments.find((a) => a.id === id);
+        if (removed === undefined) return draft;
+        releaseAttachmentUri(removed.uri);
+        return { ...draft, attachments: draft.attachments.filter((a) => a.id !== id) };
+      }),
+
+    updateTurn: (address, change) =>
+      write(address, (draft) => ({
+        ...draft,
+        ...change({ mcpServerId: draft.mcpServerId, skillNames: draft.skillNames }),
+      })),
+
+    restore: (address, restored) =>
+      write(
+        address,
+        (draft) => {
+          const returning = restored.attachments ?? [];
+          const ids = new Set(returning.map((a) => a.id));
+          return {
+            ...draft,
+            ...restored,
+            attachments: [...returning, ...draft.attachments.filter((a) => !ids.has(a.id))],
+          };
+        },
+        () => releaseAttachments(restored.attachments ?? []),
+      ),
+
+    clear: (address) => write(address, () => null),
+
+    startEdit: (address, turn) =>
+      write(address, (draft) => ({
+        ...draft,
+        text: turn.text,
+        mcpServerId: turn.mcpServerId,
+        skillNames: turn.skillNames,
+        editing: {
+          messageId: turn.messageId,
+          before: draft.editing?.before ?? {
+            text: draft.text,
+            mcpServerId: draft.mcpServerId,
+            skillNames: draft.skillNames,
+          },
+        },
+      })),
+
+    cancelEdit: (address) =>
+      write(address, (draft) => {
+        if (draft.editing === undefined) return draft;
+        const { editing, ...rest } = draft;
+        return { ...rest, ...editing.before };
+      }),
+  };
+});
+
+/** The draft of `target`, as a component reads it. */
+export function useComposerDraft(target: DraftTarget): ComposerDraft {
+  return useComposerDraftStore((state) => state.drafts[keyOf(target)] ?? EMPTY_DRAFT);
+}
+
+/** The address of `target` under the account bound now, as a component takes it. */
+export function useDraftAddress(target: DraftTarget): DraftAddress {
+  const account = useComposerDraftStore((state) => state.account);
+  return useMemo(() => ({ account, target }), [account, target]);
+}

package/src/runtime/config.tsx

@@ -0,0 +1,186 @@
+import { createContext, type ReactNode, useContext, useMemo } from 'react';
+import { ALIA_API_URL } from '../lib/origins';
+import type { AgentRun, Message } from './types';
+
+/**
+ * Where a signed-out session keeps its conversations, per account. The host
+ * binds it to the signed-in account; unbound it reads nothing and writes
+ * nothing. `AccountScopedKey` in the Alia app is one.
+ */
+export interface OfflineConversationStore {
+  getItem(): Promise<string | null>;
+  setItem(value: string): Promise<void>;
+}
+
+/** An artifact a tool produced (a generated file, a canvas), for the host to show beside the thread. */
+export interface AliaArtifact {
+  id: string;
+  type: string;
+  content: unknown;
+  title: string;
+  timestamp: number;
+}
+
+/** The usage frame a stream ends with: the balance left and, sometimes, a spending warning. */
+export interface AliaUsageFrame {
+  credits_remaining?: number;
+  credit_warning?: {
+    level?: string;
+    daysRemaining?: unknown;
+    todaySpend?: unknown;
+    avgDailySpend?: unknown;
+    currentModelMultiplier?: unknown;
+  };
+  [key: string]: unknown;
+}
+
+/** What the request carries that the host's own controls decide, read at send time. */
+export interface AliaTurnRequest {
+  /** Only `false` is sent: `true` is the server's default. */
+  webSearch?: boolean;
+  deepResearch?: boolean;
+}
+
+/** Why the thread asks its host to show the thought panel. */
+export type ThoughtOpening =
+  /** The reader pressed a turn's "worked for" line or a sources row. */
+  | 'pressed'
+  /** A running turn began using tools; offered only while the host has nothing else open. */
+  | 'automatic';
+
+/**
+ * How the person speaks and likes to be spoken to: read-aloud, dictation and calls all use it.
+ * Each is the server's or the platform's own default when absent.
+ */
+export interface SpeechPreferences {
+  voice?: 'male' | 'female';
+  tone?: 'brief' | 'chill' | 'default';
+  /** The language spoken and dictated, a BCP 47 tag; the platform's own when absent. */
+  language?: string;
+}
+
+/**
+ * Everything the conversation runtime needs from the app around it, as typed
+ * callbacks. Every member is optional: a host that omits one gets the plain
+ * behaviour (no navigation, no artifacts panel, no credits). The Alia app and
+ * the sheet mount the SAME runtime and differ only in what they put here.
+ */
+export interface AliaRuntimeHost {
+  /** Device facts sent as `X-Device-Info`, so the model's `getDeviceInfo` tool can answer. */
+  deviceInfo?: () => Promise<unknown>;
+  /** The modes the host's composer controls own; read when the turn is sent, not when it is built. */
+  turnRequest?: () => AliaTurnRequest;
+  /** A turn is about to be sent from the composer or a retry. */
+  onTurnStart?: () => void;
+  /** Real answer text just arrived (throttled): a haptic tick. */
+  onOutput?: () => void;
+  /** The stream's usage frame: credits left and the spending warning. */
+  onUsage?: (usage: AliaUsageFrame) => void;
+  /** A tool finished; `name` is the tool, `output` its structural result. */
+  onToolResult?: (result: {
+    toolCallId: string;
+    name: string | undefined;
+    output: unknown;
+  }) => void;
+  /** A tool produced something worth its own panel. */
+  onArtifact?: (artifact: AliaArtifact) => void;
+  /** What this turn put in the context window (`alia.context`), raw. */
+  onContext?: (conversationId: string | null, payload: unknown) => void;
+  /**
+   * An agent's feature gate refused what the person tried (`feature_entitlement_required`, or a
+   * locked row of the attach menu): `key` is the feature, e.g. `attachments.documents`. The host
+   * shows its own upsell; the person's words stay in the composer.
+   */
+  onFeatureLocked?: (key: string) => void;
+  /** A delegated agent started a run of its own for this turn. */
+  onAgentTurn?: (turn: AgentRun & { conversationId: string | null }) => void;
+  /** The agent's row in the host's list, ahead of the server: your line, then her answer. */
+  onTurnPreview?: (agentId: string | null | undefined, text: string) => void;
+  /**
+   * Messages an agent writes into the open conversation by itself (a result, a check-in).
+   * Returns the unsubscribe.
+   */
+  subscribeConversationMessages?: (
+    conversationId: string,
+    listener: (message: Message) => void,
+  ) => () => void;
+  /**
+   * Show where the work of a turn is read — the host's right panel — now that the thread selected
+   * one (`useThoughtStore`; the panel is `ThoughtPanel`). Return `false` to decline an
+   * `automatic` opening because something else is open. A host without it has no thought panel:
+   * the thread draws the "worked for" line as text and never opens one.
+   */
+  showThought?: (opening: ThoughtOpening) => boolean;
+  /** A scheduled-task card in the thread was pressed: show that task. Omitted, the card is not pressable. */
+  openAutomation?: (automationId: string) => void;
+  /** The URL of a site's cached icon for the work log's sources, or nothing for Bloom's quiet dot. */
+  faviconUrl?: (url: string) => string | null | undefined;
+  /** The runtime created or chose a conversation: show it. Omitted, the host shows nothing new. */
+  openConversation?: (conversationId: string) => void;
+  /** The open conversation is gone (deleted elsewhere, or a first send failed): leave it. */
+  closeConversation?: () => void;
+}
+
+export interface AliaRuntimeConfig {
+  /** Alia's API origin. Every route the SDK calls hangs off it, under `/v1` (`routes.ts`). */
+  apiUrl: string;
+  /** The offline copy of the conversations, when the host keeps one. */
+  offline: OfflineConversationStore | null;
+  /**
+   * The `fetch` a turn is streamed with. React Native's own cannot stream a
+   * body; Expo's (`expo/fetch`) can. Omitted, the platform's.
+   */
+  streamFetch: typeof fetch | undefined;
+  /** How read-aloud, dictation and calls speak; omitted, the server's and the platform's defaults. */
+  speech: SpeechPreferences;
+  host: AliaRuntimeHost;
+}
+
+export interface AliaRuntimeProviderProps extends Partial<Omit<AliaRuntimeConfig, 'host'>> {
+  host?: AliaRuntimeHost;
+  children: ReactNode;
+}
+
+const DEFAULT_CONFIG: AliaRuntimeConfig = {
+  apiUrl: ALIA_API_URL,
+  offline: null,
+  streamFetch: undefined,
+  speech: {},
+  host: {},
+};
+
+const AliaRuntimeContext = createContext<AliaRuntimeConfig>(DEFAULT_CONFIG);
+
+/**
+ * Configure the conversation runtime for everything below. Providers nest and
+ * merge: what a nearer one leaves out, the outer one (or the default) answers.
+ * The sheet and the screen mount one from their own props; the Alia app mounts
+ * one above its routes, so its sidebar and its conversation read the same
+ * conversations through the same hooks.
+ */
+export function AliaRuntimeProvider({
+  apiUrl,
+  offline,
+  streamFetch,
+  speech,
+  host,
+  children,
+}: AliaRuntimeProviderProps) {
+  const parent = useContext(AliaRuntimeContext);
+  const value = useMemo<AliaRuntimeConfig>(() => {
+    const nextApiUrl = apiUrl ?? parent.apiUrl;
+    return {
+      apiUrl: nextApiUrl,
+      offline: offline === undefined ? parent.offline : offline,
+      streamFetch: streamFetch ?? parent.streamFetch,
+      speech: speech ?? parent.speech,
+      host: host === undefined ? parent.host : { ...parent.host, ...host },
+    };
+  }, [apiUrl, offline, streamFetch, speech, host, parent]);
+  return <AliaRuntimeContext.Provider value={value}>{children}</AliaRuntimeContext.Provider>;
+}
+
+/** The runtime's configuration: the nearest provider's, or the defaults. */
+export function useAliaRuntime(): AliaRuntimeConfig {
+  return useContext(AliaRuntimeContext);
+}