@alia.onl/sdk 15.7.0 → 19.0.0

package/README.md

@@ -1,8 +1,8 @@
 # @alia.onl/sdk
 
-Alia's chat SDK for React Native and Expo apps built on Oxy: the chat sheet and
-screen, the streaming hook, speech in and out, and the primitives they are made
-of. It renders inside the one `OxyProvider` your app already mounts and sends
+Alia's chat SDK for React Native and Expo apps built on Oxy: the conversation (the chat sheet,
+the screen, the thread, the thought panel and the composer), the streaming hook, speech in and
+out, and the primitives they are made of. It renders inside the one `OxyProvider` your app already mounts and sends
 the signed-in user's Oxy session with every request; it never holds a token of
 its own.
 
@@ -17,8 +17,11 @@ a prebuilt library.
 bun add @alia.onl/sdk
 ```
 
-`react`, `react-native`, `@oxy.so/core`, `@oxy.so/services` and the Expo modules
-listed under `peerDependencies` in `package.json` are yours to install. Metro
+`react`, `react-native`, `@oxy.so/core`, `@oxy.so/services`, `@tanstack/react-query`
+(the conversation runtime's cache; `OxyProvider` mounts the client), `react-native-css`
+(the thread's images take `className`) and the Expo modules listed under `peerDependencies` in
+`package.json` — among them `expo-clipboard` and `expo-web-browser`, which the thread's copy
+button and its sources use — are yours to install. Metro
 must resolve package `exports` (`resolver.unstable_enablePackageExports = true`,
 the default in Expo SDK 53+), because every icon import is a subpath.
 
@@ -28,12 +31,25 @@ The chat is built from Bloom (`@oxy.so/bloom`, a peer dependency): mount Bloom's
 Alia's avatar is Bloom's 3D character (`AgentAvatar`). It draws through a runtime of
 static files (about 214 MB), which the chat loads from Alia's own origin
 (`ALIA_CHARACTER_RUNTIME_URL`, served with CORS open), so the app hosts nothing and mounts
-no avatar provider. An app with a strict CSP allows `https://alia.onl` in `script-src` and
-`connect-src` (and `'wasm-unsafe-eval'`). To serve your own copy instead, serve the Bloom
+no avatar provider. To serve your own copy instead, serve the Bloom
 package's `assets/character-runtime/` directory unchanged and pass the URL of `runtime.mjs`
 as `characterRuntimeUrl` to `AliaChatSheet` or `AliaChatScreen`; native avatars run in a
 WebView, so there the URL must be absolute and reachable from the device.
 
+A web app with a Content-Security-Policy composes the SDK's into its own instead of listing
+Alia's origins by hand: `@alia.onl/sdk/csp` exports `ALIA_SDK_CSP` and `withAliaSdkCsp(extensions)`
+in the shape of `@oxy.so/core`'s `OxyCspExtensions` (a leaf entry, safe on a server):
+
+```ts
+import { withAliaSdkCsp } from '@alia.onl/sdk/csp';
+app.use(createOxySecurityHeaders({ csp: withAliaSdkCsp(APP_CSP_EXTENSIONS) }));
+```
+
+It declares the API and its WebSocket (`connect-src`), the avatar runtime and the voice call's
+worklets on `https://alia.onl` (`script-src`, with `'wasm-unsafe-eval'` for the runtime's
+WebAssembly), attachments and read-aloud clips (`img-src`, `media-src`). No `blob:` script:
+the worklets are a content-addressed file on `alia.onl`, not a blob URL.
+
 The empty chat greets the signed-in person by name ("Hi Nate, what's on your mind?"); pass
 `welcomeGreeting` to say something else, or `labels.greeting` / `labels.greetingNamed` to translate it.
 
@@ -44,12 +60,28 @@ The chat's own copy is English. Pass `labels` to `AliaChatSheet` or
 `AliaChatScreen` to translate it (`AliaChatLabels`; anything omitted stays
 English). Bloom's own strings follow `BloomProvider`'s `locale`.
 
-Two entry points:
-
-- `@alia.onl/sdk` — text chat, dictation, read-aloud, catalogue, primitives.
-- `@alia.onl/sdk/voice` — `VoiceSession` and `useVoiceRoom`, the voice call.
-  Pass `VoiceSession` to the shell as `voiceSession` to offer calls; leave it
-  out for text-only chat and the call is never compiled.
+Entry points:
+
+- `@alia.onl/sdk` — the conversation screen (`AliaChatScreen`, `AliaChatSheet`,
+  `AliaChatContent`, the thread `AliaThread`, the work panel `ThoughtPanel`) with its voice call included: the button that opens it, the
+  bar with its honest state, the notices (failure, moved to another device, time
+  limit) and the transcript in the same thread. Also dictation, read-aloud,
+  the conversation runtime, primitives. The call loads on the first call.
+- `@alia.onl/sdk/runtime` — the conversation data layer alone (hooks, cache, stores,
+  `AliaRuntimeProvider`), for a sidebar or a test that must not load the chat UI.
+- `@alia.onl/sdk/model` — the conversation as pure data (the records, the timeline, the thought
+  panel's steps and sources, tool cards, the markdown export): no React, no Oxy client.
+- `@alia.onl/sdk/csp` — the CSP the SDK needs from a host page (above).
+- `@alia.onl/sdk/voice` — the call's parts (`VoiceSession`, `useVoiceRoom`,
+  the audio engine) for a host that builds its own screen.
+
+Voice is on by default; `voice={false}` makes a chat text-only, and
+`voice={{ canStartVoice, onVoiceBlocked, onCallEnded, onNotice, sounds }}` brings
+what only the host knows (the plan and credits gate, what to refresh when a call
+ends, where notices go, the cues it plays). Whether the screen holding the call is the one on
+show is `isFocused` of the chat. The conversation a call lives in is the chat's own. Its words are `labels.voiceControls`,
+`voiceError`, `voiceEnded`, `voiceEndingSoon` and `voiceBlocked`. A host with its
+own screen uses `useVoiceLauncher` and `AliaVoiceCall`, the same pieces.
 
 ## Speech
 
@@ -72,7 +104,7 @@ transcript content.
 
 On iOS and Android a call needs
 [`react-native-audio-api`](https://github.com/software-mansion/react-native-audio-api)
-(an optional peer of `@alia.onl/sdk/voice`; the root entry never reaches it)
+(a peer of the SDK: the conversation screen includes the call)
 and its config plugin, then a new native build:
 
 ```json
@@ -103,22 +135,59 @@ On iOS and Android its composer rises with the keyboard through
 `react-native-keyboard-controller`, which needs the app wrapped in its
 `KeyboardProvider` (re-exported here).
 
-Or the hook on its own, with your own UI:
+The sheet, the screen and the Alia app are three frames around ONE conversation runtime
+(see [The conversation runtime](#the-conversation-runtime)): they list, open, create, send,
+stop, retry, edit and clear conversations through the same hooks, and a conversation started in
+one is the same conversation in the others.
 
-```tsx
-import { useAliaChat } from '@alia.onl/sdk';
+## Any agent, from any app
 
-const { messages, send, isStreaming, stop, error } = useAliaChat({
-  clientContext: 'The user is looking at their order history.',
-});
+Every agent — Alia included — is the same agent (ADR 0020), and any Oxy app opens any agent the
+person can reach. The wire contract is [`docs/agent-embedding.md`](../../docs/agent-embedding.md).
+
+```tsx
+import { AliaAskProvider, useAskAgent } from '@alia.onl/sdk';
+
+<AliaAskProvider
+  agents={{ alia: {}, sindi: { id: SINDI_AGENT_ID } }}  // no id = Alia
+  clientContext={`Homiio — viewing listing ${listing.id}`}   // the screen, built per turn
+  hostTools={{
+    app: 'homiio',
+    definitions: [{ name: 'apply_search', description: '…', inputSchema: { type: 'object' } }],
+    execute: async (action) => applySearch(action.input),  // → { outcome: 'applied' | … }
+  }}
+  toolRenderers={{ 'homiio:searchListings': (r) => <ListingCards data={r.output} /> }}
+  onFeatureLocked={(key) => showHomiioPlus(key)}
+  onShare={({ token }) => shareSheet(`https://homiio.com/shared/${token}`)}
+>
+  {children}
+</AliaAskProvider>;
+
+const { ask } = useAskAgent();
+ask('sindi', { text: 'Is this flat a good price?' }); // signed out: Oxy's sign-in instead
 ```
 
-`useAliaChat` streams a turn as Server-Sent Events and switches on Alia's
-product events — `alia.reasoning`, `alia.tool_result`, `alia.research_progress`,
-`alia.plan_preview`, delegated-agent answers — into `ChatMessage` fields your
-components render. Those events are the product runtime's, not part of the Oxy
-generic inference contract, and this package is written against them on
-purpose: it is a **product** client.
+- **The lead.** `agent={{ id }}` (on `AliaChatSheet`, `AliaChatScreen` and `AliaChatContent`) makes
+  that agent the conversation's lead: its greeting, name, character and starters
+  (`GET /v1/agents/:id/profile`) and the header's first avatar. Omitted, Alia.
+- **The participants.** `AliaChatState.participants` is `{ lead, joined }`; draw it with
+  `AliaParticipants` (or `AliaParticipantsHeader` inside Bloom's AI chat shell) wherever the
+  chrome puts the conversation's title. When the lead consults an agent (`alia.agent_start`), the
+  agent's reply is drawn under its own identity and its avatar flies from there into the header —
+  Bloom's multi-agent join — which gains the agent when it lands.
+- **Host tools** are UI effects the app's own client performs. An `alia.host_action` is executed
+  once, by `execute`, and its outcome is sent with the next request; an outcome whose request did
+  not get through goes with the one after. They are never authority over data.
+- **Tool renderers** are keyed `<app>:<tool>`, parsed only from `oxy_<app>__<tool>` /
+  `self_<app>__<tool>`, and drawn before the generic tool card — for consulted agents too.
+- **Feature gates.** The attach menu offers photos and files as the lead offers them
+  (`GET /v1/agents/:id/features`); a locked row, and a turn refused with
+  `feature_entitlement_required`, call `onFeatureLocked(key)`. Documents are uploaded to the
+  person's Oxy Files (`oxyServices.assets.upload`) and sent as a `file` part.
+- **Sharing.** `onShare` receives `{ conversationId, token, expiresAt }` once the SDK has minted
+  the link; `useShareConversation()` mints and revokes, and `<AliaSharedConversation token>` reads
+  one, signed in or not. `useConversations({ agentId })` lists the person's conversations with one
+  agent.
 
 ## An "Ask Alia" button with her avatar
 
@@ -139,7 +208,7 @@ you do); run it too when a Bloom upgrade changes how the runtime draws her.
 
 `useAliaActivity()` is the busiest of two sources, so a button reacts even with the sheet closed:
 
-- a turn running in this app: every `useAliaChat` publishes its lifecycle to a shared store;
+- a turn running in this app: every `useConversationThread` publishes its lifecycle to a shared store;
 - her runs for the signed-in person elsewhere (background work, another device): the API's
   `alia:activity` event on the person's `user:<id>` room, over ONE Socket.IO connection per
   API origin, opened with the Oxy session's token only while someone is signed in and a
@@ -148,13 +217,52 @@ you do); run it too when a Bloom upgrade changes how the runtime draws her.
 `socket.io-client` is a regular dependency, not a peer: the SDK owns this connection and an
 app should not have to install a transport to use a button.
 
+## The thread
+
+The sheet, the screen and the Alia app draw ONE thread, `AliaThread` (inside `AliaChatContent`),
+and nothing else draws turns: Bloom's AI Chat turns with their reveal, the feedback row and the
+long-press menu; the reply's Markdown with its rich blocks, its code card and its references;
+the work log (`WebSearch`, `TaskList`) and the "Worked for…" line; tool cards; the questions Alia
+asked; the plan an agent shows; the failed turn's toast with its Retry; day lines; the window over a long
+history with the scroll that goes with it; and the card of an agent's run. What a frame adds is
+around it, never in it (`tests/components/thread/one-thread.test.tsx` mounts it both ways and
+holds the rows equal, and fails if anything else imports Bloom's thread).
+
+An agent's permanent thread is `threadHandle`: the conversations behind the open one are paged in
+above it, the thread can be searched (`state.openSearch`), and a hit opens the stretch around it.
+Those routes (`/agents/thread/:handle/…`) answer Alia's own origins only, as `/conversations` did
+before `/v1`: an embedding Oxy app has no agents of its own and passes no handle.
+
+### The work panel, and where it goes
+
+A turn that used tools has a "Worked for…" line; pressing it selects the turn (`useThoughtStore`)
+and asks the host to show it (`runtime.showThought`). `ThoughtPanel` — steps, sources, activity —
+draws the selection wherever the host puts it: the Alia app's right panel, the sheet's own sheet
+over the conversation. A host without `showThought` has no panel, and the line is plain text. A
+running turn's first tool opens the panel by itself (`showThought('automatic')`) unless the host
+declines because something else is open. A file the turn generated opens where the host keeps its
+files (`ThoughtPanel`'s `outputActions`).
+
+### Cards: why weather, market and FairCoin are the SDK's
+
+The weather, market quote and FairCoin price cards are the thread's. Their tools
+(`getWeather`, `getMarketQuote`, `getFairCoin`) are in the pipeline every Alia surface calls, and
+the card's numbers travel in the message itself (the whole of every range is in the snapshot, so a
+thread reopened next month shows the figures it was answered with). So any surface that draws
+Alia's reply draws them. The scheduled-task card is the same card with one difference: it points at
+a screen of the host's, so it is a link only where `runtime.openAutomation` says where it goes.
+
 ## The composer
 
 The sheet, the screen and the Alia app share one composer, `AliaComposer`: Bloom's
 `ComposerPill` with files by paste and drop (read with real progress, retried, refused with a
 sentence), dictation, suggestions over the field and Alia's questions docked above it.
 `AliaChatSheet` and `AliaChatScreen` render it with photos, voice and suggestions, and
-`AliaChatSheet` focuses it once the sheet has presented. To build your own surface, mount it and
+`AliaChatSheet` focuses it once the sheet has presented. The conversation also owns the draft
+(per conversation and account), sending, rewriting a question already sent, the questions Alia
+asked and the power-level selector: give `AliaChatContent` an `onModelChange` and the composer
+offers the seven levels (`auto` … `ultra`) with `deviceModels` of the person's own after them;
+give it an `addMenu` (rows and what pressing one does) and that menu replaces the photos one. To build your own surface, mount it and
 pass what the surface has:
 
 ```tsx
@@ -179,151 +287,129 @@ import { AliaComposer } from '@alia.onl/sdk';
 />;
 ```
 
-## Which endpoint the SDK calls, and why
-
-The hook sends its turns to `POST {apiUrl}/v1/chat/completions`, with `apiUrl`
-defaulting to `EXPO_PUBLIC_ALIA_API_URL` or `https://api.alia.onl`. It also
-reads `GET {apiUrl}/catalogue` once per base URL when a `model` is passed, to
-check that `publisher/model` against the real models the server offers. With no
-`model`, the request carries none and the server's default model answers — the
-SDK ships no model identifier of its own.
-
-That is the compatibility surface, not the product route. `POST /alia/chat` is
-the same handler with the same authentication, and it is where Alia's own
-clients go — but the two mounts answer browsers differently:
-
-| Preflight | `access-control-allow-origin` |
-| --- | --- |
-| `OPTIONS /alia/chat` from `https://alia.onl` or `https://console.alia.onl` | that origin, with credentials |
-| `OPTIONS /alia/chat` from an origin Alia does not enumerate | **absent** |
-| `OPTIONS /v1/chat/completions` from anywhere | `*` |
-
-`/alia/chat` takes Alia's exact-origin allowlist (`packages/api/src/lib/cors-origins.ts`);
-`/v1` is public CORS. Because this package compiles into *your* app on *your*
-origin, defaulting the hook to `/alia/chat` would fail every consumer's
-preflight on web. So it stays on `/v1/chat/completions`, which is Alia's
-**permanent product API** — it does not sunset
-([ADR 0010](https://github.com/OxyHQ/Alia/blob/main/docs/adr/0010-alia-keeps-a-product-api-credentials-come-from-oxy-console.md)).
-Generic model access is a different product, Kaana through Oxy; this package
-is written against Alia's, and the credential a consumer presents is an Oxy
-one — the signed-in user's session today. A change of default to `/alia/chat`
-would be a semver-major of this package, would reach only consumers who upgrade
-**and** rebuild, and is not needed to escape a sunset; it is taken only if the
-per-application origin policy below makes it worthwhile
-([#244](https://github.com/OxyHQ/Alia/issues/244), closed on that decision).
-
-Native apps are not subject to CORS at all — React Native sends no `Origin`
-header — so the table above is about web builds and the backend path below.
-
-## Using the SDK from your own product: the consumer-backend path
-
-The supported way for an application outside Alia's origins to use this SDK
-today is to put your own backend between the SDK and Alia. Your backend
-receives the SDK's request, calls Alia's product route server-to-server — a
-server sends no `Origin` header, so `/alia/chat` answers it on its credential
-alone — and streams the SSE body back unchanged. Then point the hook at that
-backend:
+## The conversation runtime
+
+Everything that is a conversation lives in `src/runtime`, in layers that depend only downward:
+
+| Layer | What | Public names |
+| --- | --- | --- |
+| Transport | Alia's REST API over the signed-in person's Oxy client (token, refresh and the single 401 replay are Oxy's); the turn's SSE stream | `useAliaApi`, `AliaApiError` |
+| Model and state | the records, React Query keys and the cached lists; zustand stores for the composer drafts and the hand-off of a first message | `Message`, `Conversation`, `aliaQueryKeys`, `useComposerDraftStore`, `useConversationStore` |
+| Hooks | `useConversations` (the list, paginated), `useConversation` (one, with its history), `useCreateConversation`, `useRenameConversation`, `useDeleteConversation`, `useClearConversation`, and `useConversationThread`: the live thread of one conversation — messages, `sendMessage`, `createNewConversation`, `editMessage`, `regenerateMessage`, `retryFailedTurn`, `stopGeneration`, `clearConversation`, `startOver`, `ensureConversation` | `use…` |
+| UI | `AliaChatContent` (the conversation screen), `AliaChatScreen`, `AliaChatSheet`, `AliaThread`, `ThoughtPanel` | components |
+
+Between the hooks and the components are the hooks of what a person does with a conversation —
+`useChatComposer` (the draft, send, edit, suggestions), `useChatVoice` (the call and its
+transcript in the thread), `useThreadView` (the present or a moment of an agent's thread),
+`useOpenThought`, `useReadAloud`, `useMessageVote` — each used by exactly one layer above it.
+
+An agent's thread and runs (`useThreadHistory`, `useThreadSearch`, `useThreadWindow`,
+`useAgentActivity`) read the agent routes through the same API and cache.
+
+A turn goes to `POST {apiUrl}/v1/chat/completions`; conversations to `{apiUrl}/v1/conversations`.
+`apiUrl` defaults to `EXPO_PUBLIC_ALIA_API_URL`, then `https://api.alia.onl`. A failure to
+answer is a typed error that keeps the person's turn in the thread with a retry (`FailedTurn`),
+never a filler message; running out of credits or hitting a rate limit is a `UsageLimitError`.
+
+### Configure it once: `AliaRuntimeProvider`
+
+Providers nest and merge, so the sheet works with no provider at all and the Alia app mounts
+one above its routes. Everything is optional.
+
+```tsx
+import { AliaRuntimeProvider, type AliaRuntimeHost } from '@alia.onl/sdk';
+
+const host: AliaRuntimeHost = {
+  // navigation: the runtime created or chose a conversation / the open one is gone
+  openConversation: (id) => router.push(`/c/${id}`),
+  closeConversation: () => router.replace('/'),
+  // what only the host can show: credits, an artifact panel, a haptic tick
+  onUsage: (frame) => updateCredits(frame.credits_remaining),
+  onArtifact: (artifact) => rightPanel.show(artifact),
+  turnRequest: () => ({ webSearch: composerMenu.webSearch, deepResearch: composerMenu.deepResearch }),
+  // where the work of a turn is read; return false to decline an automatic opening
+  showThought: (opening) => (opening === 'automatic' && panel.isOpen ? false : panel.show('thought')),
+  openAutomation: (id) => router.push(`/automations/${id}`), // a scheduled-task card is a link
+  faviconUrl: (url) => favicons.of(url), // the work log's source icons
+};
+
+<AliaRuntimeProvider
+  apiUrl="https://api.alia.onl"
+  offline={accountScopedStore}  // optional: where a 401-ed session keeps its conversations
+  streamFetch={expoFetch}       // optional: a fetch that can stream a body on native
+  speech={{ voice: 'female', tone: 'brief', language: 'es-ES' }} // read-aloud, dictation, calls
+  host={host}                   // memoise it
+>
+  {children}
+</AliaRuntimeProvider>;
+```
+
+The sheet and the Alia app differ ONLY in what they put there:
 
 ```tsx
-useAliaChat({ apiUrl: 'https://your-backend.example' });
+// The sheet: nothing to configure; the chat keeps its own conversation.
+<AliaChatSheet ref={sheet} />
+
+// The Alia app: its route owns the conversation, its sidebar reads the same list.
+<AliaChatContent
+  surface                       // the container draws the page's card
+  conversationId={id}
+  threadHandle={handle}         // an agent's thread: history above, search
+  model={powerLevel}
+  onModelChange={setPowerLevel} // the composer offers the levels
+  addMenu={{ groups, onSelect }} // the host's rows
+  chrome={(chat) => ({ header, title, project, actions: <Actions chat={chat} /> })}
+  renderUsageLimit={({ error, dismiss }) => <UsageLimitDialog error={error} onDismiss={dismiss} />}
+/>
+function Sidebar() {
+  const { data } = useConversations(); // the very query the thread keeps up to date
+  …
+}
 ```
 
-The hook keeps its paths, so your backend answers
-`POST /v1/chat/completions` and `GET /catalogue` under whatever base URL you
-give it. Nothing about the stream changes: the SDK's parser reads the bytes Alia
-wrote.
+### Voice lives in the conversation
 
-**Which credential.** The SDK attaches the signed-in user's Oxy access token as
-`Authorization: Bearer …` on the request your backend receives. Forward that
-header as it is. `POST /alia/chat` authenticates with
-`authenticateTokenOrApiKey` (`packages/api/src/routes/chat.ts`,
-`packages/api/src/middleware/auth.ts`), which accepts an Oxy session token —
-verified with Oxy, the same way it would be if the browser had called Alia
-directly — and the turn is metered to that user's Alia entitlement, the same as
-a direct call. The other credentials the middleware recognises are
-Alia-internal. There is no consumer-application credential for this route yet — that is Oxy Applications' to issue (OxyHQ/oxy#972).
+A call always has a home. With a conversation open the call lives in it; on a new-chat screen
+the conversation is created when the call starts (after the plan/credits gate) and the call
+opens on the screen that shows it. That is one code path for the sheet, `AliaChatScreen` and the
+Alia app (`useVoiceLauncher`'s `resolveConversation` and `useVoiceCallRequests`):
 
-A minimal relay, Node 18+ and Express:
+- the sheet has no routes, so the chat itself switches to the new conversation and the call opens
+  in place;
+- the Alia app's new-chat route is replaced by the conversation's (`host.openConversation`), and
+  the call opens on that screen, which takes the pending request.
 
-```ts
-import express from 'express';
-
-const ALIA = 'https://api.alia.onl';
-const app = express();
-app.use(express.json({ limit: '1mb' }));
-
-/** Relay one request to Alia and stream the answer back unchanged. */
-async function relay(
-  req: express.Request,
-  res: express.Response,
-  method: 'GET' | 'POST',
-  path: string,
-): Promise<void> {
-  const controller = new AbortController();
-  req.on('close', () => controller.abort());
-
-  const authorization = req.get('authorization');
-  const upstream = await fetch(`${ALIA}${path}`, {
-    method,
-    headers: {
-      ...(authorization ? { Authorization: authorization } : {}),
-      Accept: req.get('accept') ?? 'application/json',
-      ...(method === 'POST' ? { 'Content-Type': 'application/json' } : {}),
-    },
-    body: method === 'POST' ? JSON.stringify(req.body) : undefined,
-    signal: controller.signal,
-  });
-
-  res.status(upstream.status);
-  res.setHeader('Content-Type', upstream.headers.get('content-type') ?? 'application/json');
-  res.setHeader('Cache-Control', 'no-cache');
-  res.setHeader('X-Accel-Buffering', 'no'); // keep proxies from buffering the SSE stream
-  res.flushHeaders();
-
-  if (upstream.body === null) {
-    res.end();
-    return;
-  }
-  try {
-    for await (const chunk of upstream.body) res.write(chunk);
-  } catch (error) {
-    if (!controller.signal.aborted) throw error;
-  } finally {
-    res.end();
-  }
-}
+**Who decides which conversation is open:** the host, when it navigates (it passes
+`runtime.openConversation`, or an outer `AliaRuntimeProvider` has one); otherwise the chat.
 
-// The SDK's turn: answered by Alia's PRODUCT route, server-to-server.
-app.post('/v1/chat/completions', (req, res) => relay(req, res, 'POST', '/alia/chat'));
+## Which API the SDK calls
 
-// The SDK's model check. Without this the hook still works — an unreadable
-// catalogue leaves the requested identifier alone — but it never learns what
-// the server offers.
-app.get('/catalogue', (req, res) => relay(req, res, 'GET', '/catalogue'));
+The SDK is Alia's product client and speaks **only to `/v1`**, Alia's product API: a bearer of
+the signed-in person's Oxy session, no cookies, and public CORS — so it works in the browser of
+every Oxy app, on that app's own origin, with nothing to configure and no backend in between.
 
-app.listen(3000);
-```
+- A turn: `POST {apiUrl}/v1/chat/completions` — the same handler `/alia/chat` mounts, with every
+  `alia.*` stream event, `conversationId` and the stored history.
+- Conversations: `{apiUrl}/v1/conversations` (list, open, create, save, rename, delete, clear,
+  vote). A person's session only: an application key or a bot secret is refused, because a
+  conversation is somebody's private history.
+- Dictation, read-aloud and the voice call: `/v1/audio/*` and `/v1/voice/session`.
 
-The request body the SDK sends is `{ model?, messages, stream: true }` and the
-response Alia writes is `text/event-stream`; the relay forwards both without
-reading them. CORS between your web app and your backend is yours to configure,
-as it would be for any of your own routes.
+`apiUrl` defaults to `EXPO_PUBLIC_ALIA_API_URL`, then `https://api.alia.onl`. `routes.ts` holds
+the paths, and `tests/runtime/v1-only.test.ts` fails if the transport builds a URL outside `/v1`.
+The one exception is the agent routes (`AGENT_ROUTES`: an agent's thread and its runs), which only
+Alia's own clients use.
 
-**The trade-off.** This is one more hop, and one more process in the path of a
-stream. Some consumers will not want it, which is why it is documented as the
-path that works today rather than chosen as the only one. The other two shapes
-— a CORS policy on `/alia/chat` for registered consumer origins, and the SDK
-default moving to `/alia/chat` in a major — are recorded in #244: the first is
-blocked on Oxy Applications carrying an origin registry (OxyHQ/oxy#972), and
-the second is an adoption window rather than a switch, for the raw-source
-reason above.
+`model` is a power level (`auto`, `instant`, `medium`, `high`, `xhigh`, `pro`, `ultra`) or an
+exact `publisher/model`; it is sent as given, and omitted the server's default answers. The SDK
+ships no model identifier of its own.
 
 ## Scripts
 
 ```sh
 bun run typecheck       # tsc --noEmit
 bun run test            # vitest
-bun run check:entries   # the root entry must not reach the voice call
+bun run check:entries   # the root entry reaches the call only through its lazy import; no retired modules
 ```
 
 ## Licence

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@alia.onl/sdk",
-  "version": "15.7.0",
+  "version": "19.0.0",
+  "description": "Alia AI chat SDK — the conversation runtime, chat UI, voice calls and dictation for Oxy apps",
   "main": "src/index.ts",
   "react-native": "src/index.ts",
   "source": "src/index.ts",
@@ -9,17 +10,26 @@
     ".": "./src/index.ts",
     "./avatar": "./src/avatar.ts",
     "./content": "./src/lib/content-utils.ts",
+    "./csp": "./src/csp.ts",
+    "./model": "./src/runtime/model.ts",
+    "./runtime": "./src/runtime/index.ts",
     "./tools": "./src/tools.ts",
     "./voice": "./src/voice.ts",
     "./package.json": "./package.json"
   },
   "files": [
     "src",
+    "worklets",
     "NOTICE",
     "tsconfig.json",
     "CHANGELOG.md"
   ],
   "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OxyHQ/Alia.git",
+    "directory": "packages/alia-chat"
+  },
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -28,10 +38,12 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "check:entries": "node scripts/check-entry-isolation.mjs",
-    "render:avatar-still": "bun scripts/render-avatar-still.ts"
+    "render:avatar-still": "bun scripts/render-avatar-still.ts",
+    "prepublishOnly": "bun run typecheck && bun run test && bun run check:entries"
   },
   "dependencies": {
     "clsx": "^2.1.1",
+    "react-native-markdown-display": "^7.0.2",
     "socket.io-client": "^4.8.3",
     "tailwind-merge": "^3.7.0",
     "zustand": "^5.0.15"
@@ -43,6 +55,7 @@
     "@oxy.so/bloom": ">=10.9.0",
     "@oxy.so/core": ">=3.0.0",
     "@oxy.so/services": ">=8.0.0",
+    "@tanstack/react-query": "^5.101",
     "@react-native-async-storage/async-storage": "^2.2.0",
     "expo-blur": "^57.0.0",
     "react-native-reanimated": "^4.5.0",
@@ -58,6 +71,8 @@
     "nativewind": "^5.0.0-preview.3",
     "expo-clipboard": "^57.0.0",
     "expo-file-system": "^57.0.0",
+    "expo-web-browser": "^57.0.0",
+    "react-native-css": "^3.0.7",
     "react-native-audio-api": "^0.13.6"
   },
   "peerDependenciesMeta": {
@@ -66,9 +81,6 @@
     },
     "expo-clipboard": {
       "optional": true
-    },
-    "react-native-audio-api": {
-      "optional": true
     }
   },
   "devDependencies": {

package/src/animations.ts

@@ -3,4 +3,3 @@ import { Easing, FadeInUp } from 'react-native-reanimated';
 const easeOut = Easing.bezier(0.16, 1, 0.3, 1);
 
 export const planPreviewEnter = FadeInUp.duration(220).easing(easeOut);
-export const chatMessageEnter = FadeInUp.duration(220).easing(easeOut);