@alia.onl/sdk 15.7.0 → 19.0.0

package/src/runtime/host-tools.ts

@@ -0,0 +1,140 @@
+/**
+ * Host tools: UI effects in the embedding client (`docs/agent-embedding.md` §2, ADR 0020 §6).
+ *
+ * A surface declares the effects its own client can perform with every request. The model sees
+ * each as `host_<app>__<name>`; when it calls one, the server records the call and emits
+ * `alia.host_action`, and this client — the only one that declared it — performs it and sends
+ * the outcome with its NEXT request, where it becomes that call's result. A host tool is never
+ * authority over data: it moves the host's own screen.
+ *
+ * Two rules hold here, in a queue that knows nothing of React:
+ *  - an action is performed at most once, whatever the stream repeats;
+ *  - an outcome stays queued until a request carrying it has been accepted, so a turn that ends
+ *    before its outcomes are sent hands them to the next one.
+ */
+
+import type { HostAction } from './stream-events';
+
+export type { HostAction as AliaHostAction } from './stream-events';
+
+/** One effect the host can perform. `name` matches `^[a-z][a-z0-9_]{0,47}$`. */
+export interface AliaHostToolDefinition {
+  name: string;
+  description: string;
+  /** A JSON Schema with an object root. */
+  inputSchema: Record<string, unknown>;
+}
+
+export const HOST_OUTCOMES = ['applied', 'inline', 'rejected', 'stale', 'failed'] as const;
+export type AliaHostOutcomeKind = (typeof HOST_OUTCOMES)[number];
+
+/** What came of an action: the host's own word for it, and a line for the model. */
+export interface AliaHostOutcome {
+  outcome: AliaHostOutcomeKind;
+  /** At most 500 characters; longer is cut. */
+  detail?: string;
+}
+
+/** The host tools a surface declares (`hostTools` on the chat). */
+export interface AliaHostTools {
+  /** The app's slug, `^[a-z][a-z0-9-]{0,31}$`. */
+  app: string;
+  /**
+   * At most 16. What the host's screen shows now is not part of the declaration: it is the chat's
+   * `clientContext`, built by the host per turn.
+   */
+  definitions: readonly AliaHostToolDefinition[];
+  /** Perform `action` and say what came of it. Called once per action. */
+  execute: (action: HostAction) => Promise<AliaHostOutcome>;
+}
+
+/** An outcome as a request carries it. */
+export interface HostOutcomeRecord {
+  toolCallId: string;
+  outcome: AliaHostOutcomeKind;
+  detail?: string;
+}
+
+/** The request's `host` member. */
+export interface HostRequest {
+  app: string;
+  version: 1;
+  tools: AliaHostToolDefinition[];
+  /** Omitted when there is nothing to report. */
+  outcomes?: HostOutcomeRecord[];
+}
+
+const DETAIL_LIMIT = 500;
+
+function record(toolCallId: string, outcome: AliaHostOutcome | undefined): HostOutcomeRecord {
+  const kind = HOST_OUTCOMES.includes(outcome?.outcome as AliaHostOutcomeKind)
+    ? (outcome?.outcome as AliaHostOutcomeKind)
+    : 'failed';
+  const detail = typeof outcome?.detail === 'string' ? outcome.detail.slice(0, DETAIL_LIMIT) : '';
+  return { toolCallId, outcome: kind, ...(detail === '' ? {} : { detail }) };
+}
+
+/** The outcomes of a conversation's host actions, between the stream that asked and the next request. */
+export class HostOutcomeQueue {
+  private readonly performed = new Set<string>();
+  private ready: HostOutcomeRecord[] = [];
+
+  /**
+   * Perform `action` with `tools`, once. Resolves when its outcome is queued; `false` when the
+   * action had already been performed and nothing was done.
+   */
+  async dispatch(action: HostAction, tools: AliaHostTools | undefined): Promise<boolean> {
+    if (this.performed.has(action.toolCallId)) return false;
+    this.performed.add(action.toolCallId);
+    let outcome: AliaHostOutcome;
+    if (tools === undefined || action.app !== tools.app) {
+      outcome = { outcome: 'rejected', detail: 'This app did not declare that tool.' };
+    } else if (!tools.definitions.some((tool) => tool.name === action.name)) {
+      outcome = { outcome: 'rejected', detail: `Unknown tool "${action.name}".` };
+    } else {
+      try {
+        outcome = await tools.execute(action);
+      } catch (error) {
+        outcome = {
+          outcome: 'failed',
+          detail: error instanceof Error ? error.message : 'The app could not do it.',
+        };
+      }
+    }
+    this.ready.push(record(action.toolCallId, outcome));
+    return true;
+  }
+
+  /** The outcomes ready to send, oldest first. */
+  pending(): HostOutcomeRecord[] {
+    return [...this.ready];
+  }
+
+  /** A request carrying `sent` was accepted: those are delivered. */
+  delivered(sent: readonly HostOutcomeRecord[]): void {
+    this.ready = this.ready.filter((outcome) => !sent.includes(outcome));
+  }
+
+  /** A different conversation: its outcomes are not this one's. What was performed stays performed. */
+  clear(): void {
+    this.ready = [];
+  }
+}
+
+/** The `host` member of a request, or nothing for a surface without host tools. */
+export function hostRequest(
+  tools: AliaHostTools | undefined,
+  outcomes: readonly HostOutcomeRecord[],
+): HostRequest | undefined {
+  if (tools === undefined) return undefined;
+  return {
+    app: tools.app,
+    version: 1,
+    tools: tools.definitions.map(({ name, description, inputSchema }) => ({
+      name,
+      description,
+      inputSchema,
+    })),
+    ...(outcomes.length === 0 ? {} : { outcomes: [...outcomes] }),
+  };
+}

package/src/runtime/index.ts

@@ -0,0 +1,113 @@
+/**
+ * The conversation runtime: the data layer under the sheet, the screen and the Alia app.
+ *
+ * Layers, each depending only on the ones above it in this list:
+ *
+ *  1. transport — `api` (REST over the signed-in Oxy client), the turn's SSE stream
+ *  2. model and state — `types`, `query-keys`, the zustand stores, the cached conversation lists
+ *  3. hooks — `useConversations`…, `useConversationThread`
+ *
+ * Nothing here draws anything. It is also a leaf entry, `@alia.onl/sdk/runtime`, for a host that
+ * needs the data layer without the chat UI (a sidebar, a test).
+ */
+
+export { AliaRuntimeProvider, useAliaRuntime } from './config';
+export type {
+  AliaArtifact,
+  AliaRuntimeConfig,
+  AliaRuntimeHost,
+  AliaRuntimeProviderProps,
+  AliaTurnRequest,
+  AliaUsageFrame,
+  OfflineConversationStore,
+  SpeechPreferences,
+  ThoughtOpening,
+} from './config';
+export { AliaApiError, useAliaApi } from './api';
+export {
+  ALIA_FEATURES,
+  featureOffer,
+  readAgentFeatures,
+  readAgentProfile,
+  useAgentFeatures,
+  useAgentProfile,
+} from './agents';
+export type { AliaAgentFeature, AliaAgentProfile, AliaAgentStarter, FeatureOffer } from './agents';
+export { HOST_OUTCOMES, HostOutcomeQueue, hostRequest } from './host-tools';
+export type {
+  AliaHostAction,
+  AliaHostOutcome,
+  AliaHostOutcomeKind,
+  AliaHostToolDefinition,
+  AliaHostTools,
+} from './host-tools';
+export { FEATURE_ENTITLEMENT_REQUIRED, parseConsultEvent, parseHostAction } from './stream-events';
+export type { ConsultAgent, ConsultEvent } from './stream-events';
+export {
+  DEFAULT_SHARE_TTL_HOURS,
+  readSharedConversation,
+  SharedConversationGoneError,
+  sharedMessages,
+  useShareConversation,
+  useSharedConversation,
+} from './sharing';
+export type {
+  AliaConversationShare,
+  AliaSharedAgent,
+  AliaSharedConversationData,
+  AliaSharedMessage,
+} from './sharing';
+export { uploadToOxyFiles, useDocumentUpload } from './oxy-files';
+export type { OxyFilesClient } from './oxy-files';
+export type { AliaApi, AliaApiRequest, AliaApiResult } from './api';
+export { aliaQueryKeys } from './query-keys';
+export {
+  ConversationNotFoundError,
+  useClearConversation,
+  useConversation,
+  useConversations,
+  useCreateConversation,
+  useDeleteConversation,
+  usePrefetchConversation,
+  useRenameConversation,
+  useSaveConversation,
+} from './conversations';
+export { useConversationThread, mergeEditedContent } from './use-conversation-thread';
+export type {
+  ConversationThread,
+  EditedContent,
+  UseConversationThreadOptions,
+} from './use-conversation-thread';
+export type { SendOutcome } from './use-conversation-stream';
+export { useConversationStore } from './conversation-store';
+export type { PendingInitialMessage } from './conversation-store';
+export {
+  releaseAttachments,
+  useComposerDraft,
+  useComposerDraftStore,
+  useDraftAddress,
+} from './composer-draft-store';
+export type {
+  ComposerDraft,
+  DraftAddress,
+  DraftTarget,
+} from './composer-draft-store';
+export { useAgentActivity } from './use-agent-activity';
+export type { UseAgentActivityResult } from './use-agent-activity';
+export { useThoughtStore } from './thought-store';
+export type {
+  ThoughtScope,
+  ThoughtScopeStatus,
+  ThoughtSelection,
+  ThoughtTab,
+} from './thought-store';
+export { useThreadHistory } from './use-thread-history';
+export { useThreadSearch, useThreadWindow } from './use-thread-search';
+export { useStartConversation } from './use-start-conversation';
+export type { StartConversationOptions } from './use-start-conversation';
+export { useTurnEdit } from './use-turn-edit';
+export { buildMessageContent } from './attachment-utils';
+export type { BuiltMessageContent, DroppedAttachment, UploadDocument } from './attachment-utils';
+
+// The conversation as data (also the leaf entry `@alia.onl/sdk/model`).
+export * from './model';

package/src/runtime/message-history.ts

@@ -0,0 +1,124 @@
+import type { Message, ToolInvocation } from './types';
+
+/** Message shape accepted by the chat-completions endpoint. */
+export interface OutboundMessage {
+  /**
+   * The id this screen draws the message under. The server stores the turn
+   * with the ids it was sent (`packages/api/src/lib/conversation-saver.ts`), so
+   * a vote or a read-aloud addressed by `Message.id` finds the row without a
+   * reload in between.
+   */
+  id: string;
+  role: string;
+  content: Message['content'];
+  toolInvocations?: Array<{
+    toolCallId: string;
+    toolName: string;
+    state: ToolInvocation['state'];
+    args?: Record<string, unknown>;
+    result?: unknown;
+  }>;
+}
+
+function formatOutboundMessage(message: Message): OutboundMessage {
+  const outbound: OutboundMessage = {
+    id: message.id,
+    role: message.role,
+    content: message.content,
+  };
+
+  if (message.role === 'assistant' && message.toolInvocations?.length) {
+    outbound.toolInvocations = message.toolInvocations.map((invocation) => ({
+      toolCallId: invocation.toolCallId,
+      toolName: invocation.toolName,
+      state: invocation.state,
+      args: invocation.args,
+      result: invocation.result,
+    }));
+  }
+
+  return outbound;
+}
+
+/**
+ * The id of the `index`-th consulted agent's answer (`alia.agent_start`, in the
+ * order the consultations started) in the turn whose reply is `assistantMessageId`.
+ *
+ * Derived, not received: the frames name a consultation (`consultId`), not a
+ * message. The server stores the same answer under the same derivation
+ * (`conversation-saver.ts` `agentMessageId`).
+ */
+export function agentMessageId(assistantMessageId: string, index: number): string {
+  return `${agentMessagePrefix(assistantMessageId)}${index}`;
+}
+
+/** Whether `id` is one of the agent answers {@link agentMessageId} names for this reply. */
+export function isAgentMessageOf(id: string, assistantMessageId: string): boolean {
+  return id.startsWith(agentMessagePrefix(assistantMessageId));
+}
+
+function agentMessagePrefix(assistantMessageId: string): string {
+  return `${assistantMessageId}-agent-`;
+}
+
+/** Build a turn from the history captured before optimistic UI updates. */
+export function buildOutboundMessages(
+  historySnapshot: readonly Message[],
+  userMessage: Message,
+): OutboundMessage[] {
+  return [...historySnapshot, userMessage].map(formatOutboundMessage);
+}
+
+function sameContent(a: Message['content'], b: Message['content']): boolean {
+  if (a === b) return true;
+  try {
+    return JSON.stringify(a) === JSON.stringify(b);
+  } catch {
+    return false;
+  }
+}
+
+function isEmptyAssistantPlaceholder(message: Message | undefined): boolean {
+  return (
+    message?.role === 'assistant' &&
+    message.content === '' &&
+    !message.thinking &&
+    !message.toolInvocations?.length &&
+    !message.agentInfo
+  );
+}
+
+/**
+ * Hide histories written by the former optimistic-send race.
+ *
+ * That race persisted one exact sequence: user, empty assistant placeholder,
+ * the same user again. Only that signature is collapsed; intentional repeated
+ * prompts separated by a real assistant response remain untouched. The next
+ * successful turn rewrites divergent server history from this clean view.
+ */
+export function normalizeConversationMessages(messages: readonly Message[]): Message[] {
+  const normalized: Message[] = [];
+  // A host's client context travels as a system message and is never part of the thread.
+  messages = messages.filter((message) => message.role !== 'system');
+
+  for (let index = 0; index < messages.length; index += 1) {
+    const current = messages[index];
+    const placeholder = messages[index + 1];
+    const duplicate = messages[index + 2];
+
+    if (
+      current.role === 'user' &&
+      isEmptyAssistantPlaceholder(placeholder) &&
+      duplicate?.role === 'user' &&
+      sameContent(current.content, duplicate.content)
+    ) {
+      normalized.push(current);
+      index += 2;
+      continue;
+    }
+
+    normalized.push(current);
+  }
+
+  return normalized;
+}

package/src/runtime/model.ts

@@ -0,0 +1,39 @@
+/**
+ * The conversation as data: the records, and what a list of messages becomes before anything
+ * draws it (the timeline, the thought panel's steps and sources, tool cards, day lines,
+ * the agent thread's windows, the markdown export), plus the typed ways a turn fails.
+ *
+ * Pure: no React, no React Native, no Oxy client. It is a leaf entry (`@alia.onl/sdk/model`) for
+ * code that only reads conversations, and the runtime re-exports all of it.
+ */
+
+export { API_ROUTES as ALIA_API_ROUTES } from './routes';
+export * from './power-levels';
+export { englishCopy } from '../lib/copy';
+export type { Translate } from '../lib/copy';
+export * from './thread/agent-activity';
+export * from './thread/automation-labels';
+export * from './thread/conversation-export';
+export * from './thread/message-days';
+export * from './thread/message-processor';
+export * from './thread/task-utils';
+export * from './thread/thought-utils';
+export * from './thread/thread-history';
+export * from './thread/timeline';
+export * from './thread/tool-cards';
+export { failureDetail } from './turn-failure';
+export type { FailedTurn } from './turn-failure';
+export type {
+  AgentRun,
+  AutomationResource,
+  AutomationTrigger,
+  Conversation,
+  ConversationsInfiniteData,
+  ConversationsPage,
+  Message,
+  MessageContent,
+  SendOptions,
+  ToolInvocation,
+} from './types';
+export { UsageLimitError } from './usage-limit-error';
+export type { UsageLimitDetails, UsageLimitType } from './usage-limit-error';

package/src/runtime/oxy-files.ts

@@ -0,0 +1,37 @@
+import { useOxy } from '@oxy.so/services/ui/client';
+import { useMemo } from 'react';
+import type { AliaAttachment } from '../types';
+import type { UploadDocument } from './attachment-utils';
+
+/** The slice of `OxyServices` an upload needs: Oxy Files' own `assets.upload` (`POST /assets/upload`). */
+export interface OxyFilesClient {
+  assets: {
+    upload(
+      file: { uri: string; type?: string; name?: string; size?: number },
+      options?: { visibility?: 'private' | 'public' | 'unlisted' },
+    ): Promise<{ file: { id: string } }>;
+  };
+}
+
+/** Put `attachment` in the person's Oxy Files, private, and answer its id. */
+export function uploadToOxyFiles(oxy: OxyFilesClient): UploadDocument {
+  return async (attachment: AliaAttachment) => {
+    const { file } = await oxy.assets.upload(
+      {
+        uri: attachment.uri,
+        type: attachment.mimeType,
+        name: attachment.name,
+        size: attachment.size,
+      },
+      { visibility: 'private' },
+    );
+    if (typeof file?.id !== 'string' || file.id === '') throw new Error('Oxy Files gave no id');
+    return file.id;
+  };
+}
+
+/** The signed-in person's document upload, for a turn's `file` parts. */
+export function useDocumentUpload(): UploadDocument {
+  const { oxyServices } = useOxy();
+  return useMemo(() => uploadToOxyFiles(oxyServices as unknown as OxyFilesClient), [oxyServices]);
+}

package/src/runtime/power-levels.ts

@@ -0,0 +1,66 @@
+/**
+ * Power levels — what a person chooses in Alia instead of a model.
+ *
+ * A level is one of Oxy's routing profiles (a slug with no `/`). The chat sends
+ * it as the request's `model`; Oxy picks an available model of that level for
+ * each request, cheapest first, and fails over inside the level. The chat never
+ * names a hosted model. The one exception is a model running on one of the
+ * person's OWN devices (`local/<runtime>/<model>`): that is their machine, not
+ * a model Alia offers, and it stays selectable while the device is connected.
+ *
+ * The seven slugs are Oxy's fixed vocabulary, so the chat can put words to
+ * each one in every language it speaks.
+ */
+
+export const POWER_LEVELS = ['auto', 'instant', 'medium', 'high', 'xhigh', 'pro', 'ultra'] as const;
+export type PowerLevel = (typeof POWER_LEVELS)[number];
+
+/** Where everyone starts, and what any choice no longer offered becomes. */
+export const DEFAULT_POWER_LEVEL: PowerLevel = 'auto';
+
+export function isPowerLevel(value: unknown): value is PowerLevel {
+  return typeof value === 'string' && (POWER_LEVELS as readonly string[]).includes(value);
+}
+
+/** A model served by one of the person's own devices. */
+export function isDeviceModelId(value: unknown): value is string {
+  return typeof value === 'string' && value.startsWith('local/') && value.length > 'local/'.length;
+}
+
+export interface ModeSelection {
+  /** What the selector shows as chosen: a level, or a connected device model. */
+  readonly shown: string;
+  /** What a request carries as `model`. Always present: the chat always says. */
+  readonly send: string;
+  /**
+   * `requested`: the stored choice is sent. `replaced`: it is not offered right
+   * now (a device that is not connected, or a value from an older build), so
+   * `auto` answers and the selector says so.
+   */
+  readonly source: 'requested' | 'replaced';
+}
+
+/**
+ * Resolve a stored choice against what can be sent now.
+ *
+ * `deviceModelIds` is `undefined` while the person's devices are still being
+ * listed: a device model is then kept rather than replaced, so a slow cold
+ * start never moves the person off their own machine.
+ */
+export function resolveModeSelection(
+  stored: string | null | undefined,
+  deviceModelIds: readonly string[] | undefined,
+): ModeSelection {
+  if (isPowerLevel(stored)) return { shown: stored, send: stored, source: 'requested' };
+  if (
+    isDeviceModelId(stored) &&
+    (deviceModelIds === undefined || deviceModelIds.includes(stored))
+  ) {
+    return { shown: stored, send: stored, source: 'requested' };
+  }
+  return {
+    shown: DEFAULT_POWER_LEVEL,
+    send: DEFAULT_POWER_LEVEL,
+    source: stored === null || stored === undefined || stored === '' ? 'requested' : 'replaced',
+  };
+}

package/src/runtime/query-keys.ts

@@ -0,0 +1,34 @@
+/**
+ * The React Query keys of the conversation runtime. The host's persister and its sidebar read
+ * the same keys the hooks write, so a list shown anywhere is the list the chat updates.
+ */
+export const aliaQueryKeys = {
+  conversations: {
+    all: ['conversations'] as const,
+    detail: (id: string) => ['conversation', id] as const,
+    /** The person's conversations with one agent: under `all`, so every write to the list reaches it. */
+    withAgent: (agentId: string) => ['conversations', { agentId }] as const,
+  },
+  /** An agent the chat is opened on: its profile and the state of its feature gates. */
+  agents: {
+    profile: (id: string) => ['alia-agent-profile', id] as const,
+    features: (id: string) => ['alia-agent-features', id] as const,
+  },
+  /** A conversation somebody shared, by its token. */
+  shared: (token: string) => ['alia-shared-conversation', token] as const,
+  /** An agent's permanent thread: the stretches behind the open conversation, and finding in them. */
+  threads: {
+    /** The thread itself (which conversation is active): the host's own query lives under it. */
+    all: (handle: string) => ['agent-thread', handle] as const,
+    /**
+     * The history, kept apart from the thread itself: re-reading which conversation is active is
+     * cheap and happens whenever a new stretch starts, while the pages behind it are immutable and
+     * expensive to refetch.
+     */
+    messages: (handle: string) => ['agent-thread-messages', handle] as const,
+    /** Keyed by the query as typed, so each one is cached and none is re-asked. */
+    search: (handle: string, query: string) => ['agent-thread-search', handle, query] as const,
+    /** One window of the thread, addressed by the cursor a search hit carries. */
+    window: (handle: string, cursor: string) => ['agent-thread-window', handle, cursor] as const,
+  },
+};

package/src/runtime/random-uuid.ts

@@ -0,0 +1,25 @@
+/**
+ * A UUID v4 that does not rely on `crypto.randomUUID()`.
+ *
+ * Web Crypto exposes `getRandomValues()` in every browsing context, while
+ * `randomUUID()` is restricted to secure contexts (a LAN-hosted development
+ * build is not one), and React Native has neither until a polyfill installs
+ * them. The last resort is `Math.random`: these ids name messages in a thread,
+ * they are not secrets.
+ */
+export function createRandomUuid(): string {
+  const bytes = new Uint8Array(16);
+  const webCrypto = (globalThis as { crypto?: Crypto }).crypto;
+  if (webCrypto?.getRandomValues) {
+    webCrypto.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < bytes.length; i += 1) bytes[i] = Math.floor(Math.random() * 256);
+  }
+
+  // RFC 4122 version 4 and variant 1 bits.
+  bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x40;
+  bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/src/runtime/routes.ts

@@ -0,0 +1,51 @@
+/**
+ * The routes the SDK calls — all of them on Alia's product API, `/v1`.
+ *
+ * The SDK is embedded by every Oxy app on its own web origin, so it may only call a surface that
+ * answers a browser from any origin with a bearer and no cookies: `/v1` (public CORS). The
+ * cookie-era routes (`/conversations`, `/alia/chat`) answer Alia's own origins alone and are not
+ * for the SDK. `tests/runtime/v1-only.test.ts` fails if the transport builds a URL outside `/v1`.
+ *
+ * `/v1/chat/completions` is the product's turn route: the same handler `/alia/chat` mounts, with
+ * every `alia.*` event, `conversationId` and the stored history.
+ */
+export const API_ROUTES = {
+  chat: '/v1/chat/completions',
+  conversations: {
+    list: '/v1/conversations',
+    save: '/v1/conversations',
+    create: '/v1/conversations/new',
+    get: (id: string) => `/v1/conversations/${id}`,
+    remove: (id: string) => `/v1/conversations/${id}`,
+    /**
+     * Empty a thread without removing it: every message goes, the row and its
+     * title stay. A sub-resource DELETE rather than a `/clear` verb, because
+     * what is being deleted is the message collection and nothing else.
+     */
+    clearMessages: (id: string) => `/v1/conversations/${id}/messages`,
+    vote: (id: string, messageId: string) => `/v1/conversations/${id}/messages/${messageId}/vote`,
+    /** Mint (`POST { ttlHours }`) or revoke (`DELETE`) the conversation's read-only share link. */
+    share: (id: string) => `/v1/conversations/${id}/share`,
+  },
+  /** An agent any app can open: who it is, and which of Alia's features it gates. */
+  agents: {
+    profile: (id: string) => `/v1/agents/${encodeURIComponent(id)}/profile`,
+    features: (id: string) => `/v1/agents/${encodeURIComponent(id)}/features`,
+  },
+  /** A shared conversation, read without a session. */
+  shared: (token: string) => `/v1/shared/${encodeURIComponent(token)}`,
+} as const;
+
+/**
+ * An agent's thread and its runs. These belong to Alia's own clients (the app), which are the only
+ * ones with agents of their own: `agentId`, `threadHandle` and the agent panel are not for an
+ * embedding Oxy app, and these routes answer Alia's origins alone, like `/conversations` does.
+ */
+export const AGENT_ROUTES = {
+  /** A page of the thread, oldest-first, crossing the seams between its conversations. */
+  threadMessages: (handle: string) => `/agents/thread/${encodeURIComponent(handle)}/messages`,
+  /** Everything said in the thread that matches, across every conversation in it. */
+  threadSearch: (handle: string) => `/agents/thread/${encodeURIComponent(handle)}/search`,
+  /** What a run of an agent has done so far, to hydrate the live feed. */
+  sessionStatus: (sessionId: string) => `/agents/sessions/${sessionId}/status`,
+} as const;