@alia.onl/sdk 15.8.0 → 19.1.0

package/src/lib/voice-protocol.ts

@@ -13,7 +13,11 @@
  *   `session.accepted` carries `seq`; a resume replays from `afterSeq`.
  */
 
-export const VOICE_PROTOCOL_VERSION = 1;
+/**
+ * 2: every transcript and tool event names `messageId`, the message it belongs
+ * to as it is stored.
+ */
+export const VOICE_PROTOCOL_VERSION = 2;
 
 export const VOICE_SESSION_PATH = '/v1/voice/session';
 
@@ -81,7 +85,8 @@ const CLOSE_REASONS: ReadonlySet<string> = new Set<VoiceCloseReason>([
 export type VoiceRole = 'user' | 'assistant';
 
 export type VoiceClientEvent =
-  | { type: 'auth'; token: string }
+  /** `appAssertion`: the host's Oxy app assertion (ADR 0021); a socket cannot carry the header. */
+  | { type: 'auth'; token: string; appAssertion?: string }
   | {
       type: 'session.start';
       protocol: number;
@@ -107,17 +112,20 @@ export type VoiceServerEvent =
   | { type: 'input.ready' }
   | { type: 'user.speech_started'; itemId: string }
   | { type: 'user.speech_stopped'; itemId: string }
-  | { type: 'transcript.delta'; role: VoiceRole; itemId: string; text: string }
-  | { type: 'transcript.done'; role: VoiceRole; itemId: string; text: string }
+  /**
+   * `messageId` is the message the text belongs to, the id it is stored and
+   * announced under: an assistant turn's items are one message.
+   */
+  | { type: 'transcript.delta'; role: VoiceRole; messageId: string; itemId: string; text: string }
+  | { type: 'transcript.done'; role: VoiceRole; messageId: string; itemId: string; text: string }
   | { type: 'assistant.audio_done'; itemId: string }
   | {
       type: 'assistant.done';
       itemId: string | null;
       status: 'completed' | 'cancelled' | 'incomplete' | 'failed';
     }
-  | { type: 'tool.started'; callId: string; name: string }
-  | { type: 'tool.finished'; callId: string; name: string; ok: boolean }
-  | { type: 'approval.requested'; toolName: string }
+  | { type: 'tool.started'; messageId: string; callId: string; name: string }
+  | { type: 'tool.finished'; messageId: string; callId: string; name: string; ok: boolean }
   | { type: 'messages.saved'; conversationId: string; messageIds: string[] }
   | { type: 'session.warning'; code: 'ending-soon'; remainingMs: number }
   | { type: 'session.reconnecting' }
@@ -196,9 +204,17 @@ export function parseVoiceServerEvent(raw: string): ReceivedVoiceEvent | null {
     case 'transcript.delta':
     case 'transcript.done':
       return (event.role === 'user' || event.role === 'assistant') &&
+        isString(event.messageId) &&
         isString(event.itemId) &&
         isString(event.text)
-        ? { type: event.type, role: event.role, itemId: event.itemId, text: event.text, ...seq }
+        ? {
+            type: event.type,
+            role: event.role,
+            messageId: event.messageId,
+            itemId: event.itemId,
+            text: event.text,
+            ...seq,
+          }
         : null;
     case 'assistant.done':
       return event.itemId === null || isString(event.itemId)
@@ -215,23 +231,26 @@ export function parseVoiceServerEvent(raw: string): ReceivedVoiceEvent | null {
           }
         : null;
     case 'tool.started':
-      return isString(event.callId) && isString(event.name)
-        ? { type: 'tool.started', callId: event.callId, name: event.name, ...seq }
+      return isString(event.messageId) && isString(event.callId) && isString(event.name)
+        ? {
+            type: 'tool.started',
+            messageId: event.messageId,
+            callId: event.callId,
+            name: event.name,
+            ...seq,
+          }
         : null;
     case 'tool.finished':
-      return isString(event.callId) && isString(event.name)
+      return isString(event.messageId) && isString(event.callId) && isString(event.name)
         ? {
             type: 'tool.finished',
+            messageId: event.messageId,
             callId: event.callId,
             name: event.name,
             ok: event.ok === true,
             ...seq,
           }
         : null;
-    case 'approval.requested':
-      return isString(event.toolName)
-        ? { type: 'approval.requested', toolName: event.toolName, ...seq }
-        : null;
     case 'messages.saved':
       return isString(event.conversationId) && Array.isArray(event.messageIds)
         ? {

package/src/lib/work-log.ts

@@ -8,12 +8,12 @@ import {
 } 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 type { ToolInvocation } from '../runtime/types';
 import { extractCitationSources } from './citations';
 import { domainOf } from './domain';
 import { getToolDoneLabel, getToolPillLabel } from './task-labels';
 import { toolCallStatus } from './tool-call-status';
-import { englishWorkLog, type Translate } from './work-log-copy';
+import { englishCopy, type Translate } from './copy';
 
 /**
  * A turn's tool calls, as the two Bloom logs draw them.
@@ -32,7 +32,7 @@ import { englishWorkLog, type Translate } from './work-log-copy';
 
 /** 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. */
+  /** Translator for the log's words (see `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;
@@ -154,7 +154,7 @@ function webStep(
   live: LiveResearch | undefined,
   options: WorkLogOptions,
 ): MappedStep {
-  const t = options.t ?? englishWorkLog;
+  const t = options.t ?? englishCopy;
   const arrived = inv.state !== 'partial-call';
   const ok = succeeded(inv);
   const res = resultOf(inv);
@@ -256,7 +256,7 @@ export function webSearchLog(
   research: LiveResearch | undefined,
   options: WorkLogOptions = {},
 ): WebSearchLog {
-  const t = options.t ?? englishWorkLog;
+  const t = options.t ?? englishCopy;
   const web = (invocations ?? []).filter(isWebInvocation);
   const mapped = web.map((inv) => webStep(inv, research, options));
 
@@ -333,7 +333,7 @@ export function taskListLog(
   live: boolean,
   options: WorkLogOptions = {},
 ): TaskListLog {
-  const t = options.t ?? englishWorkLog;
+  const t = options.t ?? englishCopy;
   let revealed = 0;
   let open = true;
   const tasks = (invocations ?? [])

package/src/runtime/agents.ts

@@ -0,0 +1,151 @@
+import { useOxy } from '@oxy.so/services/ui/client';
+import { useQuery } from '@tanstack/react-query';
+import { useAliaApi } from './api';
+import { aliaQueryKeys } from './query-keys';
+import { API_ROUTES } from './routes';
+
+/**
+ * The agent a chat is opened on, as `GET /v1/agents/:id/profile` answers it
+ * (`docs/agent-embedding.md` §1). Alia herself has no profile: she is the lead when no agent is
+ * named.
+ */
+export interface AliaAgentProfile {
+  id: string;
+  name: string;
+  handle?: string;
+  /** Its look, as Oxy stores a character (JSON); drawn through `readAgentCharacter`. */
+  character?: unknown;
+  color?: string;
+  description?: string;
+  /** What the empty chat says; omitted, the chat's own greeting. */
+  greeting?: string;
+  /** The lines offered over the composer of an empty chat. */
+  starters: AliaAgentStarter[];
+  access?: 'private' | 'public';
+  /** Which of Alia's features this agent gates behind an app's own check. */
+  features: Array<{ key: string; gated: boolean }>;
+}
+
+export interface AliaAgentStarter {
+  title: string;
+  prompt: string;
+}
+
+/** One of Alia's features, for one agent and the person present (`GET /v1/agents/:id/features`). */
+export interface AliaAgentFeature {
+  key: string;
+  state: 'available' | 'locked';
+  /** How many uses are left, when the publishing app counts them. */
+  remaining?: number;
+}
+
+/** The feature keys the chat itself reads: the attach menu's two rows. */
+export const ALIA_FEATURES = {
+  documents: 'attachments.documents',
+  images: 'attachments.images',
+} as const;
+
+const FIVE_MINUTES = 1000 * 60 * 5;
+
+/** A string, or nothing: the profile is read field by field rather than cast. */
+const text = (value: unknown): string | undefined =>
+  typeof value === 'string' && value !== '' ? value : undefined;
+
+/** The profile the server sent, kept only where it has the shape the contract names. */
+export function readAgentProfile(value: unknown): AliaAgentProfile | null {
+  if (value === null || typeof value !== 'object') return null;
+  const raw = value as Record<string, unknown>;
+  const id = text(raw.id);
+  const name = text(raw.name);
+  if (id === undefined || name === undefined) return null;
+  const starters = Array.isArray(raw.starters)
+    ? raw.starters.flatMap((starter): AliaAgentStarter[] => {
+        if (starter === null || typeof starter !== 'object') return [];
+        const { title, prompt } = starter as Record<string, unknown>;
+        const line = text(prompt);
+        return line === undefined ? [] : [{ title: text(title) ?? line, prompt: line }];
+      })
+    : [];
+  const features = Array.isArray(raw.features)
+    ? raw.features.flatMap((feature): Array<{ key: string; gated: boolean }> => {
+        if (feature === null || typeof feature !== 'object') return [];
+        const { key, gated } = feature as Record<string, unknown>;
+        return typeof key === 'string' ? [{ key, gated: gated === true }] : [];
+      })
+    : [];
+  return {
+    id,
+    name,
+    handle: text(raw.handle),
+    character: raw.character ?? undefined,
+    color: text(raw.color),
+    description: text(raw.description),
+    greeting: text(raw.greeting),
+    starters,
+    access: raw.access === 'public' || raw.access === 'private' ? raw.access : undefined,
+    features,
+  };
+}
+
+/** The feature states the server sent; an entry of any other shape is not a state. */
+export function readAgentFeatures(value: unknown): AliaAgentFeature[] {
+  const list =
+    value !== null && typeof value === 'object'
+      ? (value as { features?: unknown }).features
+      : undefined;
+  if (!Array.isArray(list)) return [];
+  return list.flatMap((feature): AliaAgentFeature[] => {
+    if (feature === null || typeof feature !== 'object') return [];
+    const { key, state, remaining } = feature as Record<string, unknown>;
+    if (typeof key !== 'string' || (state !== 'available' && state !== 'locked')) return [];
+    return [{ key, state, ...(typeof remaining === 'number' ? { remaining } : {}) }];
+  });
+}
+
+/** The profile of the agent `agentId`, or nothing for Alia (no id) and while it loads. */
+export function useAgentProfile(agentId: string | undefined) {
+  const { isAuthenticated } = useOxy();
+  const api = useAliaApi();
+  return useQuery({
+    queryKey: aliaQueryKeys.agents.profile(agentId ?? ''),
+    queryFn: async () =>
+      readAgentProfile((await api.get<unknown>(API_ROUTES.agents.profile(agentId ?? ''))).data),
+    enabled: agentId !== undefined && isAuthenticated,
+    staleTime: FIVE_MINUTES,
+    retry: 1,
+  });
+}
+
+/**
+ * What of Alia's features the agent `agentId` offers the person present. Alia (no id) gates
+ * nothing, so she has no answer to wait for; see `featureRows` for what the chat makes of it.
+ */
+export function useAgentFeatures(agentId: string | undefined) {
+  const { isAuthenticated } = useOxy();
+  const api = useAliaApi();
+  return useQuery({
+    queryKey: aliaQueryKeys.agents.features(agentId ?? ''),
+    queryFn: async () =>
+      readAgentFeatures((await api.get<unknown>(API_ROUTES.agents.features(agentId ?? ''))).data),
+    enabled: agentId !== undefined && isAuthenticated,
+    // A gate's state moves with the person's plan in another app: read it each time the chat opens.
+    staleTime: 0,
+    retry: 1,
+  });
+}
+
+/** How an attachment feature is offered: attached, an upsell, or not at all. */
+export type FeatureOffer = 'available' | 'locked' | 'absent';
+
+/**
+ * What the attach menu offers for `key`. Alia's own chat (`features === undefined`) offers every
+ * attachment; an agent offers what its feature answer lists — `locked` is still offered, as the
+ * host's upsell — and nothing it does not list.
+ */
+export function featureOffer(
+  features: readonly AliaAgentFeature[] | undefined,
+  key: string,
+): FeatureOffer {
+  if (features === undefined) return 'available';
+  return features.find((feature) => feature.key === key)?.state ?? 'absent';
+}

package/src/runtime/api.ts

@@ -0,0 +1,141 @@
+import { useOxy } from '@oxy.so/services/ui/client';
+import { useMemo } from 'react';
+import {
+  type AppAssertionHeaders,
+  NO_APP_ASSERTION,
+  useAppAssertionHeaders,
+} from './app-assertion';
+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.
+ *
+ * @param appAssertionHeaders the host's `X-Oxy-App-Assertion` (`app-assertion.ts`), on every request
+ */
+export function createAliaApi(
+  oxyServices: LinkableOxy,
+  apiUrl: string,
+  appAssertionHeaders: AppAssertionHeaders = NO_APP_ASSERTION,
+): AliaApi {
+  async function send<T>(
+    method: 'GET' | 'POST' | 'PATCH' | 'DELETE',
+    path: string,
+    request: AliaApiRequest = {},
+  ): Promise<AliaApiResult<T>> {
+    const assertion = await appAssertionHeaders();
+    const linked = oxyServices.createLinkedClient({ baseURL: apiUrl });
+    try {
+      const headers = {
+        ...assertion,
+        ...(request.body === undefined ? {} : { 'Content-Type': 'application/json' }),
+      };
+      const response = await linked.client.requestAuthenticatedResponse({
+        method,
+        url: withParams(path, request.params),
+        ...(request.body === undefined ? {} : { body: JSON.stringify(request.body) }),
+        ...(Object.keys(headers).length === 0 ? {} : { headers }),
+        ...(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();
+  const appAssertionHeaders = useAppAssertionHeaders();
+  return useMemo(
+    () => createAliaApi(oxyServices as LinkableOxy, apiUrl, appAssertionHeaders),
+    [oxyServices, apiUrl, appAssertionHeaders],
+  );
+}

package/src/runtime/app-assertion.ts

@@ -0,0 +1,53 @@
+// `@oxy.so/services/ui`, not the root barrel (which ships the sign-in panels, `check:entries`):
+// `ui/client` does not export `useAppAssertion`.
+import { useAppAssertion } from '@oxy.so/services/ui';
+import { useMemo } from 'react';
+
+/**
+ * Which Oxy app this conversation is in, for Alia (Alia ADR 0021, Oxy ADR 0045).
+ *
+ * An Oxy app may confine its own agent to itself — Clarity's assistant opens
+ * only inside Clarity — and the official apps share one session that names no
+ * app, so Alia reads the app from the Oxy-signed assertion the host's
+ * `OxyProvider` obtains and keeps current. Every request the SDK makes to Alia
+ * carries it as `X-Oxy-App-Assertion` when there is one; without one (an app
+ * Oxy cannot recognise yet, a signed-out person) nothing is sent, and only a
+ * confined agent is affected.
+ *
+ * The SDK never builds, stores or inspects the assertion: it is the host's
+ * provider's, read at send time so it is never stale.
+ */
+export type AppAssertionHeaders = () => Promise<Record<string, string>>;
+
+/** No app assertion: what a caller outside a React tree, or a test, passes. */
+export const NO_APP_ASSERTION: AppAssertionHeaders = async () => ({});
+
+/** The host's app assertion as request headers, `{}` when it has none or cannot get one. */
+export function useAppAssertionHeaders(): AppAssertionHeaders {
+  const { getAppAssertionHeaders } = useAppAssertion();
+  return useMemo(
+    () => async () => {
+      try {
+        return await getAppAssertionHeaders();
+      } catch {
+        return {};
+      }
+    },
+    [getAppAssertionHeaders],
+  );
+}
+
+/** The host's app assertion itself, for the voice socket, which cannot carry a header. */
+export function useAppAssertionToken(): () => Promise<string | null> {
+  const { getAppAssertion } = useAppAssertion();
+  return useMemo(
+    () => async () => {
+      try {
+        return await getAppAssertion();
+      } catch {
+        return null;
+      }
+    },
+    [getAppAssertion],
+  );
+}

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 };
+}