@alia.onl/sdk 15.8.0 → 19.0.0

package/CHANGELOG.md

@@ -1,6 +1,90 @@
 # @alia.onl/sdk
 
-## 15.8.0
+## 19.0.0
+
+Every agent is the same agent, and any app embeds any of them (ADR 0020; the wire contract is
+[`docs/agent-embedding.md`](../../docs/agent-embedding.md), kept with the API). A clean cut: the retired frames and props are deleted, not deprecated,
+and there is no compatibility path — a build on an older SDK cannot read the new stream.
+
+### Added
+
+- **Any agent as lead.** `agent?: { id }` on `AliaChatSheet`, `AliaChatScreen` and
+  `AliaChatContent`. The chat reads `GET /v1/agents/:id/profile`, and that agent's greeting, name,
+  character and starters lead the conversation (`lib/participants.ts`: `lead = profile ?? ALIA_LEAD`);
+  the welcome waits for the profile rather than greeting as Alia. The composer's placeholder and
+  the welcome→header flight (`leadToProfile(lead)`) name the lead.
+- **One participants header, with Bloom's join flight.** `AliaParticipants` draws Bloom's
+  `AgentProfile` with `[lead, ...joined]`. When the lead consults an agent, the agent's reply is
+  drawn under its own `AgentReplyIdentity` (anchor `reply:<agentId>`) and its avatar flies into
+  the header — `centeredLanding(14)`, merging, 950 ms, staggered by 120 ms when several join, one
+  batch at a time — and the header gains it when the flight lands (at once with reduced motion; an
+  agent already in a loaded conversation is simply there). `useParticipants`, `joinFlights`,
+  `AliaParticipantsHeader` (the participants between the AI chat shell's own buttons, for a host
+  whose header slot takes a string title) and `ANCHORS` are exported. `one-thread.test.tsx` fails if
+  any other file imports `AgentProfile` or builds a join flight.
+- **Consult stream events.** `alia.agent_start | agent_delta | agent_tool | agent_end`, read
+  strictly (`parseConsultEvent`): a frame of another version or shape is dropped whole. Each
+  consultation is one message carrying `agentInfo`, named `<assistantMessageId>-agent-<n>` in the
+  order of its start, as the server stores it; its tool calls and results stream into it.
+- **Host tools.** `hostTools?: { app, definitions, execute }` declares the app's UI effects with
+  every request (`host: { app, version: 1, tools, outcomes? }`). An `alia.host_action` is performed
+  once by `execute`; its outcome (`applied | inline | rejected | stale | failed`) rides the next
+  request, and stays queued when a request carrying it does not get through. Screen state is the
+  existing `clientContext`, built by the host per turn.
+- **Tool-result renderers.** `toolRenderers?: Record<'<app>:<tool>', (result) => ReactNode>`, keyed
+  only from `oxy_<app>__<tool>` / `self_<app>__<tool>`, drawn before (and instead of) the generic
+  tool card, for consulted agents' results too.
+- **Feature gates.** `GET /v1/agents/:id/features`; the default attach menu (photos and files)
+  offers a row only where the lead's feature is available or locked, and a locked row calls
+  `onFeatureLocked(key)` instead of a picker. A turn refused with `feature_entitlement_required`
+  (in the stream or before it) calls `onFeatureLocked(feature)` and hands the words back to the
+  composer. Documents are uploaded to the person's Oxy Files (`oxyServices.assets.upload`,
+  private) and sent as a `{ type: 'file', file: { file_id, filename, mime } }` part.
+- **`AliaAskProvider` + `useAskAgent()`.** One mounted sheet; `ask(agentKey?, turn?)` opens it on an
+  agent of `agents: Record<string, { id?: string }>` (no id = Alia), or opens Oxy's sign-in when the
+  session cannot call Alia. It carries `hostTools`, `toolRenderers`, `labels`, `voice`,
+  `clientContext`, `onFeatureLocked` and `onShare` for every agent.
+- **Sharing.** `useShareConversation()` (`POST`/`DELETE /v1/conversations/:id/share`),
+  `useSharedConversation(token)` and `<AliaSharedConversation token>` (`GET /v1/shared/:token`,
+  no session, read-only through the SDK's own thread). `useConversations({ agentId })` lists the
+  conversations with one agent.
+
+### Breaking
+
+- `AliaChatContent`'s `agentId` prop is `agent: { id }`.
+- `AliaChatState.agents` is `AliaChatState.participants` (`{ lead, joined }`); `AliaChatAgent` is
+  gone (`AliaChatAgentRef` names the `agent` prop). `AliaChatHeader` takes `participants`, not
+  `agents`.
+- `AliaChatSheet` / `AliaChatScreen` `onShare` receives the minted share
+  (`{ conversationId, token, expiresAt }`) instead of nothing.
+- `labels.placeholder` is `(leadName) => string`; `labels.addDocuments` is new.
+- `ALIA_ANCHORS` and `ALIA_TO_PROFILE` are `ANCHORS` (`lead:welcome`, `participants`,
+  `reply:<id>`) and `leadToProfile(lead)`.
+- The retired single `alia.agent` frame and the `delta.agent_message` chunk are no longer read.
+- **No agent asks for approval.** Removed: `alia.approval_request` / `alia.approval_result` in the
+  chat stream and on the agent-session socket; `PendingApproval`, `PendingApprovalResult`,
+  `Message.pendingApproval`, `Message.pendingApprovalResult`; `ApprovalDecision`,
+  `AgentApprovalRequest`, the `approval_request` / `approval_result` activity events,
+  `AgentActivityState.approvalRequest` / `approvalResult`, `respondApproval` of `useAgentActivity`;
+  the `waiting_approval` turn lifecycle and the `waiting` thought step (copy
+  `thought.waitingApproval`); the voice protocol's `approval.requested` and
+  `onApprovalRequested`. A question the agent asks (`askUserQuestion`) stays.
+- **A plan is shown, never approved.** `alia.plan_preview` still draws `PlanPreviewCard`, now the
+  steps alone: its Approve and Cancel are gone, and so are what they did. Removed:
+  `approvePlan` / `rejectPlan` of `useConversationStream` and `useConversationThread`,
+  `onApprovePlan` / `onRejectPlan` of `AliaThread`, `PendingPlan.approved` / `rejected`,
+  `PlanPreviewCard`'s `onApprove` / `onReject` / `approved` / `rejected`, and the labels
+  `planApprove`, `planCancel`, `planApproved`, `planCancelled`. The work log's `plan_approved`
+  entry is `plan` (copy `thought.audit.plan`, "Plan"), listed for every plan shown.
+  `Message.pendingPlan` is `Message.plan`, and its type `PendingPlan` is `MessagePlan`
+  (`{ planId, steps }`): nothing about it is pending.
+- **No agent mode.** `AliaTurnRequest.agentMode` is gone and no `agentMode` is sent: Alia consults
+  agents with `consultAgent` whenever she needs to. The work-log copy of `askAgent` /
+  `delegateToAgent` is `consultAgent`'s.
+- `usePhotosMenu` is gone (the default menu is `useAttachMenu`). `buildMessageContent` takes an
+  optional document `upload` as its third argument.
+
+## 18.1.0
 
 - **The SDK declares its CSP, and the voice call needs no `blob:` script.** In an app with a
   Content-Security-Policy (Mention) the call failed twice over: `connect-src` lacked
@@ -14,7 +98,7 @@
   `script-src https://alia.onl` the avatar already needs. The API's URL is defined once (the
   dictation, read-aloud and voice hooks each had their own copy).
 
-## 15.7.0
+## 17.1.0
 
 - **`AliaAvatarIcon` is her still until she moves.** At icon size it drew Alia through the live 3D
   runtime, so a header button cost every cold load of the app around it the whole runtime from
@@ -26,23 +110,70 @@
   installed Bloom's runtime; a test fails if `ALIA_AVATAR` changes without it. Peer
   `@oxy.so/bloom` is `>=10.9.0`.
 
-## 15.6.0
+## 17.0.2
 
 - **The composer has its loader again.** While a turn runs, the pill is wrapped in Bloom's
   `ComposerLoader` (the light that laps its rim) with `surface={false}` and `frosted`, as the
   composer had before it became `ComposerPill` (15.1.0) and lost it. A question Alia asks sits
   beside the loader instead of inside the pill's `question` slot, so the light does not ring it.
 
-## 15.5.0
-
-- **Replies are set by Bloom's `Markdown`.** `AliaMarkdown` is a thin wrapper over
-  `@oxy.so/bloom/markdown` at its chat reading size (`lg`, 16/28): the parser, the streaming
-  behaviour and the colours are Bloom's. `react-native-markdown-display` — and with it
-  `markdown-it` and the `linkify-it` ReDoS advisory — is no longer a dependency, so apps stop
-  installing it. `AliaMarkdown` loses its `colors` and `fontFamily` props (nothing used them: the
-  text follows the app's Bloom theme) and gains `streaming`. Peer `@oxy.so/bloom` is `>=10.7.0`.
-
-## 15.4.0
+## 18.0.0
+
+One thread, one conversation screen. The Alia app's thread — its turns, cards, work log, thought
+panel, history, search and scroll window — moves into the SDK, and `AliaChatContent` becomes the
+whole conversation: the bottom sheet, `AliaChatScreen` and the app are frames around it. What the
+app keeps is what is its own: the sidebar, the right panel, the column layout that mounts them,
+its routes and its callbacks.
+
+- **Breaking: the sheet and the screen draw the app's thread.** `AliaChatMessageList` and
+  `ThinkingBlock` are gone, with the avatar-identity reply they drew. The turns are Bloom's AI Chat
+  turns (`AliaThread`, `ThreadRow`), with copy, like/dislike, read aloud, regenerate, edit, the
+  long-press menu, day lines, tool cards, the "Worked for…" line and the failed turn's toast with
+  Retry. `renderMarkdown`, `onEditMessage`, `onThumbsUp`, `onThumbsDown`, `onApprovePlan` and
+  `onRejectPlan` are removed from `AliaChatContent`: the thread edits in the composer, votes through
+  the API (`PATCH /v1/conversations/:id/messages/:id/vote`) and answers plans itself.
+- **Breaking: `AliaChatContent`'s `header` is `chrome`.** `chrome(state)` returns
+  `{ header, title, project, actions }`, the whole of what the container draws around the thread
+  (the breadcrumb included). `AliaChatState.clear` is `startOver`; it also carries `conversationId`,
+  `clearMessages`, `openSearch` and `getMessages`. `AliaVoiceOptions` loses `isFocused` (the chat
+  has one, for the ambient field too) and gains `sounds`.
+- **New: what a host brings to `AliaChatContent`.** `threadHandle` (an agent's permanent thread:
+  history above, search, jump), `ephemeral` (ghost mode), `model` + `onModelChange` +
+  `deviceModels` (the power-level selector: the seven levels from `buildPowerLevelOptions`, then
+  the person's own devices), `addMenu` (the host's rows; photos by default), `composerStatus`,
+  `surface`, `layout`, `isFocused`, `bottomInset` (now gives way to the keyboard,
+  `KeyboardSafeAreaFloor`), `onSignInRequired`, `renderUsageLimit`, `onSuggestionPicked`.
+  `AliaSuggestion.template` marks a line with blanks to fill.
+- **New: where the work of a turn is read.** `ThoughtPanel` draws the selection of
+  `useThoughtStore` (`open`, `setTab`, `sync`, `close`); the host places it. `AliaRuntimeHost`
+  gains `showThought(opening)` (return `false` to decline an automatic opening), `openAutomation`
+  (a scheduled-task card is a link only where the host says where it goes) and `faviconUrl`.
+  `AliaChatSheet` opens it in a sheet over the conversation. `FilesAndSources` takes
+  `outputActions` (`canOpen`/`open`): asking whether a file opens no longer opens it.
+- **New: the weather, market and FairCoin cards are the SDK's.** Their tools are in the pipeline
+  every Alia surface calls and the numbers travel in the message, so any surface that draws Alia's
+  reply draws them.
+- **New: `AliaRuntimeProvider speech`** (`voice`, `tone`, `language`) for read-aloud, dictation and
+  calls; `useTTS` takes its `apiUrl` and preferences from it.
+- **New: the thread's data layer, in `@alia.onl/sdk/runtime`.** `useThreadHistory`,
+  `useThreadSearch`, `useThreadWindow`, `useAgentActivity` (and `applyActivityEvent` /
+  `hydrateActivity` in `/model`), `useThoughtStore`, `aliaQueryKeys.threads`,
+  `AliaApi.patch`, `ConversationThread`, `AgentRun` (`useConversationThread` now
+  returns `agentRun`), and `useConversation(undefined)`. The agent routes are Alia's own clients'
+  (outside `/v1`).
+- **New: `@alia.onl/sdk/model`** also carries the power levels (`POWER_LEVELS`,
+  `resolveModeSelection`…) and `triggerLabel` / `cronLabel`.
+- **Changed: `AliaChatScreen`'s ambient field takes the whole screen's shape** (`layout="screen"`, the default); the sheet keeps its smaller one (`layout="sheet"`).
+- **Changed: `labels.locale`** (the language `labels.t` speaks, for dates, days and prices). The
+  chat's English covers every key the thread asks for (`tests/lib/copy-keys.test.ts` reads the
+  source and fails on one it lacks).
+- **Changed: `AliaMarkdown` defaults its body face to Bloom's** (`MARKDOWN_BODY` is gone), and
+  `ReplyMarkdown` — rich blocks, references list, code card — is the reply's renderer.
+- **New peers:** `expo-web-browser`, `react-native-css`; `expo-clipboard` is no longer optional.
+- **Fixed:** the thought panel asked "can this file open?" by opening it, once per output, while
+  rendering.
+
+## 17.1.0
 
 - **New leaf entry `@alia.onl/sdk/avatar`.** `AliaAvatarIcon`, `AliaAvatar`, `ALIA_AVATAR` and
   `useAliaActivity` without the chat: an app draws Alia's live avatar on a header button and keeps
@@ -50,6 +181,104 @@
   `check:entries` holds the leaf free of the sheet, the composer, the markdown renderer and the
   voice call. The root entry still exports the same four.
 
+## 17.0.1
+
+- The task labels follow the API's tool loader: `loadTools` ("Loading tools" / "Loaded tools")
+  replaces `useApps`, which the API no longer has. A conversation stored with `useApps` calls
+  still replays; the call just shows its raw name.
+
+## 17.0.0
+
+One conversation runtime. The sheet, `AliaChatScreen` and the Alia app are frames around the
+same data layer and the same conversation screen: conversations are persisted, listed, opened,
+renamed, deleted and cleared through the same hooks, a turn is the same stream, and a
+conversation started in one surface is the same conversation in the others. The runtime is the
+app's, moved and generalised (`src/runtime`).
+
+- **Breaking: the sheet and the screen have conversations.** Turns are stored, and the SDK
+  speaks only to `/v1` (`POST /v1/chat/completions`, `/v1/conversations`): bearer, no cookies,
+  public CORS, so it works from every Oxy app's web origin with no backend in between. The API
+  gained `/v1/conversations` (the same router as `/conversations`, behind a person's session
+  only) for this. The consumer-backend relay the README used to document is no longer needed.
+- **Breaking: `useAliaChat`, `UseAliaChatOptions`, `UseAliaChatReturn`, `AliaChatStreamError`,
+  `AliaChatFailure` are removed.** Use `useConversationThread`.
+- **Breaking: the `agents` prop is gone** from the sheet, the screen and `AliaChatContent`
+  (the pre-opened agent message of a delegation is the thread's agent run now).
+- **Breaking: `model`** is sent as given (a power level — `auto`, `instant`, `medium`, `high`,
+  `xhigh`, `pro`, `ultra` — or an exact `publisher/model`) instead of being checked against
+  `GET /catalogue` first. The catalogue helpers (`fetchCatalogue`, `parseCatalogue`,
+  `resolveSelection`, `resolveModelId`, `clearCatalogueCache` and their types) are removed: the
+  SDK itself no longer reads the catalogue, and people choose power levels, not model names.
+- **Changed: the header's Clear starts a new conversation** in the sheet and the screen (the
+  thread empties and the next turn opens a fresh conversation); nothing is deleted, the old one
+  stays in the list. Deleting or emptying a stored conversation is `useDeleteConversation` /
+  `useClearConversation`.
+- **Breaking: `ChatMessage` is the runtime `Message`:** `createdAt` is an ISO string, and a
+  `ToolInvocation` always has a `toolCallId`. Agent answers use the server's ids
+  (`<reply id>-agent-<n>`).
+- **Breaking: voice.** `openElsewhere` and `owner` are gone from `useVoiceLauncher` and
+  `AliaVoiceOptions`; `conversationId` and `agentId` belong to the chat. A call always lives in a
+  conversation: the open one, or — on a new-chat screen — one created when the call starts (after
+  the gate) and shown, and it opens on the screen that shows that conversation — in place in the
+  sheet, on the destination route in a navigating host (`useVoiceCallRequests`). `start()` is
+  async. New options `resolveConversation` and `accountId`; a live call now ends when the screen
+  shows another conversation, loses focus or changes account.
+- **Who owns the open conversation:** a host that navigates (`runtime.openConversation`, or one
+  from an outer `AliaRuntimeProvider`) decides; with none, `AliaChatContent` keeps its own.
+- **Breaking: `labels.workLog` is `labels.t`, and `englishWorkLog` is `englishCopy`.** One translator
+  keyed like the Alia app's catalogue asks for every string that is not a fixed `labels` field
+  (the work log, the thread, the thought panel…); the app hands its own `t` in, a host without one
+  reads English (`src/lib/copy-en.ts`).
+- **Breaking: `ChatMessage` is `Message`** (and `ToolInvocation` always has a `toolCallId`).
+- **New leaf entries.** `@alia.onl/sdk/model` is the conversation as pure data — the records and
+  what a list of messages becomes before anything draws it (`timelinePositions`, `buildSteps`,
+  `extractSources`, `cardOf`, `daySeparators`, `buildConversationMarkdown`…), no React, no Oxy
+  client. `@alia.onl/sdk/runtime` is the data layer (hooks, cache, stores) and re-exports the model.
+  `check:entries` holds both leaves free of the UI and the call.
+- **New peer: `@tanstack/react-query`** (the runtime's cache; `OxyProvider` already mounts it).
+- **New:** `AliaRuntimeProvider` / `useAliaRuntime` (`apiUrl`, `chatUrl`, `offline`, `streamFetch`,
+  and `host: AliaRuntimeHost`: navigation, `onUsage`, `onArtifact`, `onToolResult`, `onContext`,
+  `onAgentTurn`, `onTurnPreview`, `turnRequest`, `deviceInfo`, `subscribeConversationMessages`),
+  `useConversations`, `useConversation`, `usePrefetchConversation`, `useCreateConversation`,
+  `useRenameConversation`, `useDeleteConversation`, `useClearConversation`, `useSaveConversation`,
+  `useConversationThread`, `useTurnEdit`, `useComposerDraftStore` (+ `useComposerDraft`,
+  `useDraftAddress`), `useConversationStore`, `aliaQueryKeys`, `useAliaApi`, `AliaApiError`,
+  `buildMessageContent`, `UsageLimitError`, `FailedTurn`; `AliaChatContent` takes
+  `conversationId`, `onConversationChange`, `agentId` and `runtime`.
+- **New labels:** `newChat`, `sendFailed`, `signInRequired`, `conversationSaveFailed`,
+  `conversationDeleteFailed`, `conversationCreateFailed`, `conversationClearFailed`,
+  `attachmentNotSent`, `attachmentUnreadable`.
+- The composer's text and photos are the shared per-conversation draft (they survive closing the
+  sheet and failed sends restore them).
+
+## 16.0.0
+
+Voice is part of the conversation screen. The sheet, `AliaChatScreen` and the Alia app now run
+the same call, with the same words and the same behaviour, instead of each orchestrating it.
+
+- **Breaking: the `voiceSession` prop is gone** from `AliaChatContent`, `AliaChatScreen` and
+  `AliaChatSheet`, together with the `VoiceSessionComponent` type. Voice is on by default; pass
+  `voice={false}` for a text-only chat. `voice={{ ... }}` (`AliaVoiceOptions`) brings the host's
+  part: `canStartVoice` (answers `'sign-in' | 'plan-required' | 'credits-exhausted' | null`;
+  the SDK tells the person, `onVoiceBlocked` adds navigation or sign-in), `onCallEnded` (refresh
+  credits and the thread), `onNotice` (default: Bloom's toast), `conversationId`, `agentId`,
+  `locale`, `voice` (`'male' | 'female'`), `onMessagesSaved`, `owner` and `isFocused` (a live
+  call ends when the screen is no longer on show or the account/conversation changes) and
+  `openElsewhere` (a screen with no conversation to hold the call opens one and hands over).
+- **Breaking: `VoiceSessionProps.onEnd` takes no argument.** `VoiceSession` itself says why a
+  call failed (`labels.voiceError(code)`), that it ended without failing
+  (`labels.voiceEnded(reason)`: moved to another device, time limit, silence, credits, server
+  shutdown; a hang-up says nothing) and, once, that it is about to end
+  (`labels.voiceEndingSoon`, also shown in the bar), through `onNotice`. New `onMessagesSaved`
+  and `onNotice` props.
+- **Breaking: labels.** `voiceFailed` is replaced by `voiceControls`, `voiceEnded`,
+  `voiceEndingSoon` and `voiceBlocked`. `AliaChatLabelsProvider` and `useLabels` are exported.
+- **New:** `useVoiceLauncher` (the host side of a call: gate, state, ownership), `AliaVoiceCall`
+  (the call bar, loaded on its first use), `toastNotice`, `VoiceNotice`, `VoiceBlockReason`.
+- **Breaking: `react-native-audio-api` is a required peer** (it was optional): the conversation
+  screen includes the call. It is still only evaluated on the first call (one lazy `import()`),
+  and `check:entries` now holds that, not the old isolation.
+
 ## 15.3.0
 
 - **The composer is Bloom's `ComposerPill`.** `AliaComposer` (the sheet's, the screen's and the