@athenaintel/react 0.42.2 → 0.48.0

package/README.md

@@ -265,7 +265,18 @@ What the statewire transport wires up in `AthenaChat`:
   `isHandledElsewhere`, and `readOnly` seams take host-specific review UIs,
   requests another surface answers, and viewers without edit rights; the
   headless `useStatewireApprovalRequest` behind it is exported for hosts with
-  their own decision UI.
+  their own decision UI. Its `confirmDecision` seam runs the host's passkey
+  decision check ("Confirm with your passkey") before an answer that lets
+  anything run. The token it resolves rides as `decisionCheck` on `run/input`
+  or `run/lane-input`. A reject never asks, and an answer with no token is
+  still sent while checks are report-only. A passkey belongs to the Athena web
+  app's host, so an app on another origin can't run that prompt itself:
+  `useAthenaBrowserDecisionConfirmer()` (inside `<AthenaProvider>`, passed to
+  `<AthenaChat confirmDecision={…}>`) asks agora for a check, opens the web
+  app's check page in a new tab, and collects the token once the person
+  confirmed there. Its `onPending` gets the code and link to show while the
+  tab is open; `useBrowserDecisionConfirmer` takes your own request and opener
+  when the provider's don't fit (an extension, an Office add-in).
 - **Frontend tools:** tools in `frontendTools` with a local `execute` are
   declared to the backend as `client_tools` and executed by the mounted
   client-tool bridge, which resumes the run with each tool's result.
@@ -295,7 +306,14 @@ What the statewire transport wires up in `AthenaChat`:
   slots for the host's text/tool renderers and controls (`renderHeaderActions`,
   `renderRunningMeta`, `summaryDetails`, `waitingTools`, `waitingToolCallIds`,
   `expansionKey`), so Olympus and the Chrome extension mount one card instead
-  of copies.
+  of copies. A host can take a call out of the card's details:
+  `isInlineTool(toolName, part)` keeps its tool UI on screen below the header
+  (the call itself comes second, so the choice can depend on what it did), and
+  `isStepRowTool(toolName)` draws it as its own step's row in the step list,
+  kept mounted while the turn is live or `mountDetails` is set. The tool UI
+  reads where it renders with `useToolPartPlacement()` (`'step'`, `'inline'`,
+  or `null`), so a call rendered in both places draws the part that belongs in
+  each.
 - **In-repo hosts consume the package, not the source.** `@athenaintel/react`
   is a workspace dependency of Olympus, the Chrome extension, and the Office
   add-in, resolved through this package's `exports` to the built `dist/` (the
@@ -324,6 +342,15 @@ What the statewire transport wires up in `AthenaChat`:
   `COLLAB_AGENT_CHANNEL_SESSION_MISMATCH` are exported for hosts with their
   own thread UI. Custom hosts can read all of it via
   `useAthenaStatewireLifecycle`.
+- **Session persistence:** `useAthenaSessionPersistence()` exposes Core's paired
+  `{ threadId, sessionPersisted }` verdict from the same runtime snapshot as
+  the client. No verdict (or no provider) returns `null`; the flag itself is
+  `true`, `false`, or `null` when the state does not declare existence. Its
+  lifetime follows Core's thread, sync host and signed-in principal;
+  credential rotation preserves the verdict. A remembered snapshot may report
+  `true` before fresh server state arrives. This is an existence hint for the
+  session asset, not authorization, workspace identity, or command durability.
+  Actions must still pass their server permission checks.
 - **Thread list:** `enableThreadList` provides the persisted Agora session
   list; switching threads (or starting a new chat) re-attaches the statewire
   session to the selected thread while the host's own `children` stay
@@ -502,6 +529,19 @@ to the approval card (or to the composer when there is none). It never
 duplicates the card's Approve / Reject buttons. `WaitingOnYouBannerView` is
 the pure presenter for hosts that resolve the inputs themselves.
 
+### `DrivingOnChip`
+
+"Driving on your phone": the person's newest message in this conversation came
+from another of their Athena apps (the host's `state.driver`). A hint, never a
+lock — sending here makes this app the driver and the chip goes away. It shows
+nothing while this app drives, once the other app has been quiet for 15
+minutes, during a live call (the call strip says where it is) and outside a
+statewire thread. `AthenaChat` mounts it above the composer when you pass
+`surface` (`"spaces"`, `"mobile"`, `"chrome"`, `"desktop"` or `"office"`, the
+Athena app the chat runs in); a custom layout mounts `<DrivingOnChip here=… />`
+itself. `useDrivingOn(here)` in `@athenaintel/agent-runtime/thread-driver` is the same read
+without the chip.
+
 ### Wake markers
 
 A user turn injected by a GitHub webhook wake carries a provenance envelope
@@ -754,6 +794,23 @@ or revoked voice access releases the microphone. Dictation and realtime voice
 cannot capture together. Model, agent, mode and toolkit changes sync through the
 same model context for the next delegated task.
 
+A call live on another of the person's own devices (the Athena web app, the
+phone app, Chrome, the desktop app) can move to this one: the button reads
+**Move call here** and the voice line reads "Live call on your phone · Move
+here". Only the microphone moves; the realtime model keeps the conversation
+going. The device the call left releases its microphone without ending the call
+and says "Call moved to your …" for a few seconds. A move that cannot complete
+leaves the call where it was. `useAthenaChatVoice` exposes the same as
+`liveElsewhere`, `transferHere()` and `movedTo` for a composer of your own,
+with the shared wording (`describeVoiceLiveElsewhere`, `useVoiceMovedNotice`,
+`VOICE_MOVE_CALL_HERE_LABEL`) in `@athenaintel/react/voice/chat`.
+
+After a handover the person sent in voice mode, a host passes
+`continueByVoice={{ onDone }}` and the composer offers **Continue by voice**:
+one tap starts a call whose model opens by saying where the conversation
+stands (`start({ opening: 'recap' })`). `onDone` runs on the tap, **Not now**,
+or a typed send.
+
 Use `<AthenaChat voice={false} />` to omit realtime voice in a host that cannot
 support it, or `voice={{ model: 'gemini-3.8-live' }}` to request a host-offered
 voice model. A custom `livekit` adapter and `onDiagnostic` observer are accepted
@@ -883,6 +940,78 @@ Both use the same bearer / API key as session creation. The full recipe
 template skill `voice-session-guide.md`. `createAthenaVoiceSession` is also
 exported if you hold the bridge state yourself.
 
+## What's new in 0.48.0
+
+**Scrolling back through a long session no longer flashes.** Opening a long session loads its newest messages, and scrolling to the top loads older pages. When a session's first loaded turn was one long run, each page of its earlier steps joined that same turn and gave it a new id. `ChatThreadShell` (and so `AthenaChat`) keyed rows by message id, so the turn remounted on every page: it replayed its entrance animation once per page, closed anything you had opened in it, and lost the browser's scroll anchor. A 74-minute run took 16 pages and flashed 16 times. Rows are now keyed by the row key the deep-agent conversion keeps for a turn that grows at its head (`deepAgentRowKey`), so the page lands in the mounted row. `AthenaChat`'s message rows also animate in only when they arrive live (the newest message, mounted while its run is running), never when a session opens or older history loads, and they respect reduced motion. The "Loading earlier messages" row is centred on the thread column. Nothing to change in your app.
+
+**Attached pictures show as pictures and open full screen.** A picture you attach to a draft (paperclip, drop or paste) now shows as a thumbnail above the composer instead of a name pill; other files keep their pill. Clicking a thumbnail, or a picture in a sent message, opens a full-screen viewer, as Devin does: the page dims, the picture fits the window, and a toolbar pages through the set (← →), names the file, zooms (− / + / fit), downloads and closes (Esc, or a click on the backdrop). Pictures in a sent message now preview at most 20rem tall instead of at full height. The thumbnail is a local preview (`UploadedAsset.previewUrl`, a `blob:` URL the draft frees when it lets the attachment go). `ImageViewer` is exported for your own surfaces, as are `MessageImageGallery` and `MessageImagePart` (`@athenaintel/react/chat-ui`) for a custom user message:
+
+```tsx
+const [viewing, setViewing] = useState<number | null>(null);
+<ImageViewer images={[{ src, name: 'chart.png' }]} index={viewing} onIndexChange={setViewing} />
+```
+
+**Each answer names the agent that answered and whom it worked for.** Once a conversation's answers come from more than one agent (your own assistant and a team agent, or two team agents a message named, answering in turn) or work for more than one person, `AthenaChat` shows a small muted line above every answer: "Finance · for you", "Athena · for Priya Shah". An answer that worked for someone other than the signed-in person is labelled even when one agent answered. A 1:1 chat with your own assistant looks as it did. The line reads the stamp Athena puts on each answer (`metadata.custom.answered_by`, identity v7 D13); an answer written before Athena stamped it shows nothing. chat-ui's `createAssistantMessage` bubble shows the same line under `ChatThreadShell`, whose new optional `viewerUserId` (the viewer's Athena user id, `user_…`) makes the viewer's own answers read "for you"; `AthenaChat` passes it for you. A custom `AssistantMessage` renders the line with `AnswerLabel` from `@athenaintel/react/chat-ui` (a host without `ChatThreadShell` mounts `AnswerLabelScope` around its messages). Nothing to change in your app.
+
+**Each agent that answers a message gets its own row.** When a message names several agents, each answers in turn, and each answer is now its own assistant message, with its own label, action bar and status, instead of one row joining them. The agent still answering has its row from its first token (a "Thinking" row before it), so nothing jumps between rows while it streams. Your `AssistantMessage` renders once per answer; nothing to change in your app.
+
+## What's new in 0.47.0
+
+**A host that is also a device an agent operates stamps its approval answers.** Athena refuses a decision sent from a device while an agent is operating it: the answer may be the agent's, driving the device the person signed in on (identity v7, D11). Wrap your chat in `DeviceOperationProvider` with a `read` function that returns the device id while your app runs a tool call Athena's device tunnel sent it, and `undefined` otherwise. Every approval answer the chat sends (`run/input`, `run/lane-input`) then carries `deviceOperation`, read at the moment it is sent, and Athena refuses an approve that carries it with `device_operated`. A reject still goes through. A `read` that throws stamps `unreadable`, so an approve is refused rather than sent from a device that may be operated. Apps that aren't a device (a web app, an Office add-in) change nothing.
+
+```tsx
+<DeviceOperationProvider read={() => tunnel.operatingDeviceId()}>
+  <AthenaChat />
+</DeviceOperationProvider>
+```
+
+## What's new in 0.46.1
+
+**A moved call plays on the device that took it.** While a call moves, both of the person's devices are briefly in the call's room. The voice room join attached every remote audio track to the call's one `<audio>` element, so the other device's microphone took the agent's place there, and once that device left, the element was empty: the device that took the call heard nothing for the rest of the call. A device now plays the agent only, and never receives the person's other device's microphone. `createDeepAgentVoiceLiveKitAdapter` hosts get this without changes; a custom `roomFactory` keeps working, and `DeepAgentVoiceLiveKitRoom` now also describes the publication and participant `trackSubscribed` passes.
+
+## What's new in 0.46.0
+
+**Continue by voice after a handover.** When a conversation arrives in your app from another of the person's devices and they sent it in voice mode, pass `continueByVoice={{ onDone }}` to `AthenaChat`. The composer then shows one button above the editor, **Continue by voice**, while voice is enabled and idle. Tapping it starts a call whose model opens by saying where the conversation stands, then listens. `onDone` runs once the person answers the offer (the tap, **Not now**, or a typed or dictated send). Clear the offer then, and when the conversation changes. Nothing starts the microphone without the tap, and while the call is still live on the other device the composer offers **Move call here** instead. For a composer of your own, `useAthenaChatVoice().start({ opening: 'recap' })` starts the same call; the opening rides that start only, never an automatic reconnect. `VOICE_CONTINUE_BY_VOICE_LABEL` is the shared button label. An Athena that predates the opening ignores it and the call opens as before.
+
+## What's new in 0.45.0
+
+**Move a live call to this device.** When the conversation's voice call is live on another of the person's own devices and Athena can move it, `AthenaChat`'s voice button reads **Move call here** and the voice line above the composer reads "Live call on your phone · Move here" (browser, Chrome, desktop app or Office for the others). Either one takes the call over without restarting it: this device joins the call's room, Athena moves the microphone to it at a turn boundary, and the realtime model carries on. The device the call left lets go of its microphone without ending the call and shows "Call moved to your …" for a few seconds; it can take the call back the same way. A move that cannot complete (refused, the room could not be joined, the microphone was blocked) leaves the call on the other device and says so in the voice line (`failure.kind: 'transfer_failed'`). For a composer of your own, `useAthenaChatVoice` returns `liveElsewhere`, `transferHere()` and `movedTo`, and `@athenaintel/react/voice/chat` exports the shared wording (`describeVoiceLiveElsewhere`, `describeVoiceMovedTo`, `useVoiceMovedNotice`, `VOICE_MOVE_CALL_HERE_LABEL`, `VOICE_MOVE_HERE_ACTION`). Only the same person can take a call, which Athena checks; an Athena that cannot move calls never offers it, and nothing changes there. Nothing to change in your app.
+
+## What's new in 0.44.3
+
+**After the D12 refusal date, an agent's picker names the model a run takes.** From the date a deployment sets for it (`CHANNEL_REPLACEMENTS_REFUSED_FROM`; unset everywhere today), Athena no longer applies a channel's or mode's model: a run on that channel takes the agent's own model. `ChatModelPicker` and `useAthenaAgentModelOptions({ agent, channel })` used to keep showing the channel's model as the default. With a `channel`, they now read the date (`featureGateEnv.channelReplacementsRefusedFrom`) and, from it, name the agent's own model as the default (`defaultModel`, the `isDefault` option). A channel's model is offered only when the agent lists it, or the session pins it. An open picker turns at UTC midnight of the day. Before the date, and against an Athena that predates the field, nothing changes. Nothing to change in your app. See [Offering an agent's own models](#offering-an-agents-own-models).
+
+## What's new in 0.44.0
+
+**One Stop for everything.** While a voice session is connecting or live, the composer's Stop control stands in for Send whenever the draft is empty, even with no run in flight. One press ends the voice session and, when a run is live (work the voice model delegated, or a typed run), stops that run too. The voice status strip no longer has an end button of its own, so there is one way to stop. While you type during a call, Stop stays beside Send: it ends the call and leaves the draft in the composer, and Send still puts the words into the live voice conversation. Hosts that build their own composer pass `liveSession={voice}` to `ComposerSendOrStop` to get the same behaviour.
+
+**Ending a voice session never shows "Message was not sent".** A `voice/*` command the host refuses (most often an end that arrives just after the session closed on its own) no longer raises the chat's error banner; the voice controller already handles those outcomes. Agora also now answers an end of an already-closed session as done instead of refusing it.
+
+**`AthenaTurnEndStatus`, `useAthenaTurnEnded` and `useAthenaVoiceLive`.** A quiet line under the last reply ("Athena went to sleep" by default; pass your own words as children) that shows only once the reply is complete and no run *and no voice session* is live. A live voice session is a conversation still under way between runs, so it never reads as asleep. Mount it in an `AssistantActionBar` override instead of writing your own; `useAthenaTurnEnded()` gives the same verdict as a boolean, and `useAthenaVoiceLive()` says whether a voice session is live on the thread.
+
+```tsx
+import { AthenaAssistantActionBar, AthenaChat, AthenaTurnEndStatus } from '@athenaintel/react';
+
+const Footer = (props) => (
+  <>
+    <AthenaTurnEndStatus />
+    <AthenaAssistantActionBar {...props} />
+  </>
+);
+
+<AthenaChat components={{ AssistantActionBar: Footer }} />;
+```
+
+## What's new in 0.43.0
+
+**Asset and citation chips look and read like Olympus's.** A chip is now Olympus's mention pill in your theme's colours (grey on the default theme, still legible on a dark one): the asset's icon, its name, then the cited place in brackets (`Q4 report [p.5]`). Like Olympus's chips, it looks the asset up and shows the asset's own title and its type's icon instead of the link's label and `type=`. The lookup is agora's `getAssetsByIds` with the chat's credentials, which returns only the assets the viewer may read. Chips that render together ask in one request. Each answer is cached for a minute per backend and per signed-in person or API key (TanStack Query, on the host's `QueryClient` when there is one); a credential that names neither shares nothing beyond its own chat. Until the answer arrives, and for an asset the viewer may not read, the chip keeps the link's label and `type=`. A chip asks only where the answer changes it: never for a repository file's catalog (the chip reads as the file either way) or for a session (agora would read its whole row, transcript ledgers included). A chip with no credential to send (no token, API key or session cookie) asks for nothing.
+
+**A repository file citation reads as the file and its lines, with GitHub's mark.** A citation of a GitHub repository's lines (`type=catalog&anchor=file_line_range`) now reads `route.ts:18-24` whatever label the model wrote: the repository's name, a long path, or a label in backticks. A long file name shortens before its lines do. The tooltip carries what the chip leaves out: the model's label when it says something else, the repository, the whole path and the cited passage.
+
+**A place is drawn once.** A label that already ends with its place (`Q4 report p.5`, `olympus/…/route.ts:18-24`) is no longer followed by the place again. Nothing to change in your app.
+
+Also first on npm in 0.43.0 (0.42.3 was tagged, not published): an asset link whose text markdown split shows its text, not `[object Object]` (#48739); a new chat's title poll waits for a session-list read already in flight (#48730); shared voice commands are scoped to their call (#48761).
+
 ## What's new in 0.42.2
 
 **A message one signed-in user queued is never sent as the next user who signs in to the same chat.** The chat keeps each conversation's unconfirmed commands in this browser under the signed-in user, so a reload can resend them. When the signed-in user changed while the chat stayed mounted (a sign-in provider of your own that signs a signed-out person in, or `AthenaSSOProvider` with `revalidateOnWindowFocus` picking up another account), the conversation moved to the new user's key and took the previous user's client id, command numbers and unsent commands with it. A message the previous user sent while offline, or that had not yet reached Athena, could then go out on the new user's connection, as the new user. With the chat connected at the time, the reverse happened: the new user's messages went out on the connection the previous user had opened, and Athena ran them as the previous user.
@@ -1572,6 +1701,15 @@ Pass them only when you deliberately want to override the agent — an explicit
 `model` is honoured as a caller override, with the agent's model as the default
 beneath it.
 
+Overrides apply only for a person who can **edit** the agent. Someone who can
+only view a published agent always runs its published version: the server
+ignores the `systemPrompt`, `tools` (with the backend-bound `frontendTools`;
+`frontendTools` with an `execute` still bind), `workbench` and `knowledgeBase`
+you pass for them, and their `model` applies only when the agent lets people pick it
+(one of its own models, or any model while **Allow any workspace model** is
+on). Settings that narrow the agent (excluded tools, a lower budget, read-only)
+still apply.
+
 ### Offering an agent's own models
 
 An agent's author lists the models it may run (the agent editor's Models
@@ -1604,7 +1742,8 @@ For an agent with the switch off:
   automatic name shows the model's catalog name. A legacy agent with no list
   offers its single model.
 - The channel's model override is that channel's default, added when the list
-  lacks it. Picking the default hands you `null`: pass `model={undefined}` to
+  lacks it, until the deployment's refusal date (below). Picking the default
+  hands you `null`: pass `model={undefined}` to
   the provider, so the agent's (or the channel's) default runs and a session
   that pinned another model is unpinned. Picking it while the session pins
   nothing writes nothing. A choice of yours that names the default model is a
@@ -1618,6 +1757,18 @@ For an agent with the switch off:
 - Until the agent has been read, the workspace menu shows but replaces nothing
   on your behalf, since your model may be one only the agent offers.
 
+**A channel's model, after the deployment's refusal date.** An agent is its
+published version: a channel or mode may narrow it, and from a date each
+deployment sets (`CHANNEL_REPLACEMENTS_REFUSED_FROM`, UTC midnight; unset by
+default) Athena no longer applies a channel's model, so a run on the channel
+takes the agent's own. With a `channel`, the picker reads that date
+(`featureGateEnv.channelReplacementsRefusedFrom`, every minute while it shows)
+and from it names the agent's own model as the default on every channel, in
+both modes; a channel's model is then offered only when the agent lists it, or
+the session pins it. It turns at UTC midnight without a reload. Before the
+date, and against an Athena that predates it, nothing changes. The date is
+display only: Athena decides from its own setting at every run.
+
 `useAthenaAgentModelOptions({ agent, channel })` is the same data for a picker
 of your own: `{ status, options: [{ model, label, isDefault, pinnedOutside }],
 defaultModel, allowAnyModel }`. Offer only `options` when `allowAnyModel` is
@@ -1865,6 +2016,8 @@ Use `AthenaAssetEmbed` to render a native Athena asset without chat, thread hist
 
 With `displayMode="minimal"`, where the viewer does not sign in, pass `allowQuickEdit` (and `readOnly={false}`) to let the viewer Quick Edit a spreadsheet or Word document with ⌘J. Its runs are billed to the asset's workspace, with an hourly cap per link.
 
+A minimal embed shows the asset's comment threads, read-only, only to a signed-in viewer with their own access to the asset (the bearer the component hands the frame, or an Athena session). Pass `allowComments` to show them to everyone holding the link, anonymous viewers included. No embed writes a comment. The request carries `allow_comments: true` only when you ask.
+
 ```tsx
 import { useState } from 'react';
 import {
@@ -2057,6 +2210,43 @@ provider's credentials and re-mint before expiry on their own.
   `isRetryableMintError`: network errors, timeouts, 408, 429, 5xx) leaves the
   handle `disconnected` and is retried, immediately when the browser comes back
   online; a refusal (401/403/404) still ends it with `status: 'error'`.
+- `readDocumentStatus({ grant })` lets a host that can read Keryx's document
+  status with the room's grant (`GET /document-status/{org}/{doc_id}?yauth=&branch=`,
+  which answers no cross-origin page, so it is read from a privileged side: a
+  desktop app's main process, a phone app's native code) say whether Keryx takes
+  the room's writes: `handle.writesRefused` is `true` while it says the room is
+  quarantined, when its socket drops every edit unconfirmed. The handle asks on
+  its first connection, on the connection after a 4401 re-check close, after an
+  outage longer than `offlineGateAfterMs`, once edits wait unconfirmed for 15 s
+  (`UNCONFIRMED_EDITS_STALL_MS`), and every five minutes (every minute while
+  refused) while connected and shown; one read at a time, given up after
+  `DOCUMENT_STATUS_READ_TIMEOUT_MS`, none on a read-only grant. Resolve `null`
+  when you can't answer: it reads as "takes writes".
+
+A write your app makes on its own, not for the person (an editor tidying what
+an older version stored, a value restored), can be sent as housekeeping: make
+it inside `runWithDocUpdateAttributions` for the handle's document.
+
+```ts
+import {
+  BACKGROUND_UPDATE_ATTRIBUTIONS,
+  runWithDocUpdateAttributions,
+} from '@athenaintel/react/collab';
+
+runWithDocUpdateAttributions({
+  doc: handle.doc,
+  attributions: BACKGROUND_UPDATE_ATTRIBUTIONS,
+  run: () => handle.doc.get('meta').setAttr('normalized', true),
+});
+```
+
+The handle's socket sends that write's update with `origin: background`, so
+Athena counts it as automatic work: it is not shown as the person's edit and
+does not notify subscriptions that follow people's edits. Only a synchronous
+write inside `run` is marked, and only while the handle is connected; a write
+made offline is sent with the reconnect's sync, as the person's. On a read-only
+grant the handle's socket sends nothing that carries document content (presence
+still goes out); Athena would refuse it anyway.
 
 ### Workspace presence (admin only)
 
@@ -2275,6 +2465,38 @@ function WorkflowButton() {
 }
 ```
 
+## Controls that need a connection
+
+A host that knows Athena can't be reached (from its own reachability: a health
+read, the OS's network events) can tell the composer, so the controls that need
+Athena show off with a reason instead of failing once used:
+
+```tsx
+const NEEDS_CONNECTION =
+  'Needs a connection. This needs Athena. It’s available again when you’re back online.';
+
+<AthenaChat composer={{ needsConnectionReason: reachable ? null : NEEDS_CONNECTION }} />
+```
+
+While it is set, the paperclip, the `@` button, the dictation mic and voice are
+disabled with the reason as their tooltip. They stay focusable, so the reason
+reads on focus as well as on hover, and pressing one starts nothing. Typing `@`
+still opens the mention menu, but it asks Athena nothing: what it can list
+without Athena (your tools, what it already loaded) shows, and a search or a
+category that would load from Athena says it needs a connection instead of
+spinning. A voice session already
+connecting or live keeps its Cancel and Mute. Typing goes on, and Send follows
+the chat outbox (`chatOutbox` on `AthenaProvider`): a host that has one holds
+what is sent until Athena is back. A file pasted or dropped meanwhile is refused
+by that outbox, as before. Cleared (`null`), each control works again at once.
+
+The composer's pickers take the same reason: `ChatAgentPicker`,
+`ChatModelPicker` and `ChatModePicker` show `disabledReason` as their tooltip
+while `disabled`, where the pointer reaches it (a disabled button gets no
+pointer events). A menu that is open when its picker turns disabled closes and
+takes no choice, and it opens again only on the next press. `FileUploadButton`
+takes `disabledReason` too, for a composer of your own.
+
 ## Debugging and Diagnostics
 
 The SDK emits structured diagnostic events — auth handshake, thread list,

package/dist/agent-runtime/src/answer-label.cjs

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const core = require("@assistant-ui/core");
+const ATHENA_ANSWERED_BY_KEY = "answered_by";
+const ATHENA_ASSISTANT_NAME = "Athena";
+const ASSISTANT_AGENT_PREFIX = "assistant:";
+const PERSON_PRINCIPAL_PREFIX = "user_";
+const UNNAMED_AGENT_NAME = "Agent";
+const LABEL_SEPARATOR = " · ";
+const NO_ANSWERS = Object.freeze([]);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const optionalId = (value) => typeof value === "string" && value.length > 0 ? value : null;
+const optionalName = (value) => {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+};
+function readAnsweredBy(value) {
+  if (!isRecord(value)) return null;
+  const agent = optionalId(value.agent);
+  if (agent === null) return null;
+  return {
+    agent,
+    agent_name: optionalName(value.agent_name),
+    for_id: optionalId(value.for_id),
+    for_name: optionalName(value.for_name)
+  };
+}
+const ANSWER_ROW_RUN_ID_PREFIX = "answered_by:";
+function answerRowRunId(agent, forId) {
+  return `${ANSWER_ROW_RUN_ID_PREFIX}${agent}|${forId ?? ""}`;
+}
+function isSplitAnswerRow(message) {
+  var _a;
+  const runId = message.role === "assistant" ? (_a = message.metadata) == null ? void 0 : _a.runId : void 0;
+  return typeof runId === "string" && runId.startsWith(ANSWER_ROW_RUN_ID_PREFIX);
+}
+const isSameAnswerer = (a, b) => a.agent === b.agent && a.for_id === b.for_id;
+const isPersonPrincipal = (id) => id !== null && id.startsWith(PERSON_PRINCIPAL_PREFIX);
+function readLangChainAnswer(source) {
+  var _a;
+  if ((source == null ? void 0 : source.type) !== "ai") return null;
+  const bag = (_a = source.additional_kwargs) == null ? void 0 : _a.metadata;
+  return isRecord(bag) ? readAnsweredBy(bag[ATHENA_ANSWERED_BY_KEY]) : null;
+}
+function collectMessageAnswers(message) {
+  var _a, _b;
+  if (message.role !== "assistant") return NO_ANSWERS;
+  const sources = core.getExternalStoreMessages(message);
+  if (sources.length === 0) {
+    const joined = readAnsweredBy((_b = (_a = message.metadata) == null ? void 0 : _a.custom) == null ? void 0 : _b[ATHENA_ANSWERED_BY_KEY]);
+    return joined === null ? NO_ANSWERS : [joined];
+  }
+  let answers = null;
+  for (const source of sources) {
+    const answer = readLangChainAnswer(source);
+    if (answer === null || (answers == null ? void 0 : answers.some((seen) => isSameAnswerer(seen, answer)))) continue;
+    answers ?? (answers = []);
+    answers.push(answer);
+  }
+  return answers ?? NO_ANSWERS;
+}
+const answersByMessage = /* @__PURE__ */ new WeakMap();
+function readMessageAnswers(message) {
+  const cached = answersByMessage.get(message);
+  if (cached !== void 0) return cached;
+  const answers = collectMessageAnswers(message);
+  answersByMessage.set(message, answers);
+  return answers;
+}
+function threadShowsAnswerLabels(messages) {
+  let first = null;
+  for (const message of messages) {
+    if (isSplitAnswerRow(message)) return true;
+    for (const answer of readMessageAnswers(message)) {
+      if (first === null) {
+        first = answer;
+      } else if (!isSameAnswerer(first, answer)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function showsAnswerLabel({
+  answers,
+  threadShowsLabels,
+  viewerId
+}) {
+  if (answers.length === 0) return false;
+  if (threadShowsLabels) return true;
+  return viewerId !== null && answers.some((answer) => isPersonPrincipal(answer.for_id) && answer.for_id !== viewerId);
+}
+function answererName(answer) {
+  if (answer.agent_name !== null) return answer.agent_name;
+  return answer.agent.startsWith(ASSISTANT_AGENT_PREFIX) ? ATHENA_ASSISTANT_NAME : UNNAMED_AGENT_NAME;
+}
+function forWhomName(answer, viewerId) {
+  if (answer.for_id !== null && answer.for_id === viewerId) return "you";
+  if (answer.for_name !== null && isPersonPrincipal(answer.for_id)) return answer.for_name;
+  return null;
+}
+function joinNames(names) {
+  if (names.length <= 1) return names[0] ?? "";
+  return `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`;
+}
+function answerLabelText({
+  answers,
+  viewerId
+}) {
+  if (answers.length === 0) return null;
+  const groups = [];
+  for (const answer of answers) {
+    const name = answererName(answer);
+    const forWhom = forWhomName(answer, viewerId);
+    const group = groups.find((candidate) => candidate.forId === answer.for_id);
+    if (group === void 0) {
+      groups.push({ forId: answer.for_id, names: [name], forWhom });
+      continue;
+    }
+    if (!group.names.includes(name)) group.names.push(name);
+    group.forWhom ?? (group.forWhom = forWhom);
+  }
+  return groups.map(
+    ({ names, forWhom }) => forWhom === null ? joinNames(names) : `${joinNames(names)}${LABEL_SEPARATOR}for ${forWhom}`
+  ).join(", ");
+}
+exports.ATHENA_ANSWERED_BY_KEY = ATHENA_ANSWERED_BY_KEY;
+exports.ATHENA_ASSISTANT_NAME = ATHENA_ASSISTANT_NAME;
+exports.answerLabelText = answerLabelText;
+exports.answerRowRunId = answerRowRunId;
+exports.readAnsweredBy = readAnsweredBy;
+exports.readLangChainAnswer = readLangChainAnswer;
+exports.readMessageAnswers = readMessageAnswers;
+exports.showsAnswerLabel = showsAnswerLabel;
+exports.threadShowsAnswerLabels = threadShowsAnswerLabels;
+//# sourceMappingURL=answer-label.cjs.map

package/dist/agent-runtime/src/answer-label.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"answer-label.cjs","sources":["../../../../agent-runtime/src/answer-label.ts"],"sourcesContent":["import { getExternalStoreMessages, type ThreadMessage } from '@assistant-ui/core';\nimport type { LangChainMessage } from '@assistant-ui/react-langgraph';\n\n/**\n * `metadata.custom` key naming the agent that answered an AI message and whom\n * its run worked for (identity v7 D13: \"each answer is labelled with its\n * agent, 'for <author>'\").\n *\n * The backend stamps it on every answer a deep-agent run's model produces\n * (`agora/.../conversation_agents/answer_label.py`), under the\n * `additional_kwargs.metadata` bag the converter exposes as\n * `message.metadata.custom`, and mirrors it onto the live wire once the\n * model's turn lands. Only the server writes it. Answers written before the\n * stamp existed carry none, and get no label.\n */\nexport const ATHENA_ANSWERED_BY_KEY = 'answered_by';\n\n/** The agent that answered and whom its run worked for, as the backend stamps them. */\nexport interface DeepAgentAnsweredBy {\n  /** `collab_agent:<asset id>` for a team agent, `assistant:<principal id>` for someone's own assistant. */\n  agent: string;\n  /** The collab agent's name when it answered; `null` for an assistant, which clients name. */\n  agent_name: string | null;\n  /** Whom the run worked for: a person (`user_…`), an agent's or automation's own run, or nobody (`null`). */\n  for_id: string | null;\n  /** That person's display name when it answered, else `null`. */\n  for_name: string | null;\n}\n\n/** What a label calls someone's own assistant: the managed default agent's product name. */\nexport const ATHENA_ASSISTANT_NAME = 'Athena';\n\nconst ASSISTANT_AGENT_PREFIX = 'assistant:';\nconst PERSON_PRINCIPAL_PREFIX = 'user_';\nconst UNNAMED_AGENT_NAME = 'Agent';\nconst LABEL_SEPARATOR = ' · ';\nconst NO_ANSWERS: readonly DeepAgentAnsweredBy[] = Object.freeze([]);\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value);\n\nconst optionalId = (value: unknown): string | null =>\n  typeof value === 'string' && value.length > 0 ? value : null;\n\nconst optionalName = (value: unknown): string | null => {\n  if (typeof value !== 'string') return null;\n  const trimmed = value.trim();\n  return trimmed.length > 0 ? trimmed : null;\n};\n\n/**\n * Parse an `answered_by` stamp off a wire value.\n *\n * A stamp without a string `agent` is no stamp at all; absent or malformed\n * optional fields read as `null`, so a partly malformed stamp still names its\n * agent and never names a person it can't.\n */\nexport function readAnsweredBy(value: unknown): DeepAgentAnsweredBy | null {\n  if (!isRecord(value)) return null;\n  const agent = optionalId(value.agent);\n  if (agent === null) return null;\n  return {\n    agent,\n    agent_name: optionalName(value.agent_name),\n    for_id: optionalId(value.for_id),\n    for_name: optionalName(value.for_name),\n  };\n}\n\n/**\n * The run id an answer's row carries when the deep-agent conversion split a\n * turn several answerers wrote into one row per answerer (`answer-rows.ts`):\n * one per agent and principal.\n */\nconst ANSWER_ROW_RUN_ID_PREFIX = 'answered_by:';\n\n/** The row run id of an answer by `agent` for `forId` (see `withAnswerRows`). */\nexport function answerRowRunId(agent: string, forId: string | null): string {\n  return `${ANSWER_ROW_RUN_ID_PREFIX}${agent}|${forId ?? ''}`;\n}\n\n/**\n * Whether a converted row is one of a turn the conversion split by answerer.\n * Reads `metadata` optionally, as `collectMessageAnswers` does: a message\n * another runtime (or a test) builds may carry none.\n */\nfunction isSplitAnswerRow(message: ThreadMessage): boolean {\n  const runId = message.role === 'assistant' ? message.metadata?.runId : undefined;\n  return typeof runId === 'string' && runId.startsWith(ANSWER_ROW_RUN_ID_PREFIX);\n}\n\nconst isSameAnswerer = (a: DeepAgentAnsweredBy, b: DeepAgentAnsweredBy): boolean =>\n  a.agent === b.agent && a.for_id === b.for_id;\n\nconst isPersonPrincipal = (id: string | null): id is string =>\n  id !== null && id.startsWith(PERSON_PRINCIPAL_PREFIX);\n\n/** The `answered_by` stamp an AI message as the wire carries it holds; `null` for any other message. */\nexport function readLangChainAnswer(\n  source: LangChainMessage | undefined\n): DeepAgentAnsweredBy | null {\n  if (source?.type !== 'ai') return null;\n  const bag = source.additional_kwargs?.metadata;\n  return isRecord(bag) ? readAnsweredBy(bag[ATHENA_ANSWERED_BY_KEY]) : null;\n}\n\nfunction collectMessageAnswers(message: ThreadMessage): readonly DeepAgentAnsweredBy[] {\n  if (message.role !== 'assistant') return NO_ANSWERS;\n  const sources = getExternalStoreMessages<LangChainMessage>(message);\n  if (sources.length === 0) {\n    const joined = readAnsweredBy(message.metadata?.custom?.[ATHENA_ANSWERED_BY_KEY]);\n    return joined === null ? NO_ANSWERS : [joined];\n  }\n  let answers: DeepAgentAnsweredBy[] | null = null;\n  for (const source of sources) {\n    const answer = readLangChainAnswer(source);\n    if (answer === null || answers?.some((seen) => isSameAnswerer(seen, answer))) continue;\n    answers ??= [];\n    answers.push(answer);\n  }\n  return answers ?? NO_ANSWERS;\n}\n\nconst answersByMessage = new WeakMap<ThreadMessage, readonly DeepAgentAnsweredBy[]>();\n\n/**\n * The answers one thread message holds: each agent that answered in it and\n * whom it worked for, in the order they answered, one entry per agent and\n * principal.\n *\n * Read off the message's bound source messages, not its joined\n * `metadata.custom`: assistant-ui joins consecutive AI messages into one\n * turn, and its joined metadata keeps only the last stamp. The deep-agent\n * conversion gives each agent that answers one message in turn (D13 several\n * agents, one message) a row of its own (`answer-rows.ts`), so a row\n * normally holds one answer; a conversion without that split (another\n * pipeline, a stamp that never landed) still names every agent of the row.\n * A message with no bound sources (another runtime) falls back to the joined\n * value. Cached per message object: a settled message keeps its object\n * across a streamed token, so a thread-wide scan per token reads only the\n * message that changed.\n */\nexport function readMessageAnswers(message: ThreadMessage): readonly DeepAgentAnsweredBy[] {\n  const cached = answersByMessage.get(message);\n  if (cached !== undefined) return cached;\n  const answers = collectMessageAnswers(message);\n  answersByMessage.set(message, answers);\n  return answers;\n}\n\n/**\n * The thread-wide half of the label decision: whether the transcript's\n * answers name two or more agents, or two or more principals they worked\n * for. Then every answer is labelled; a 1:1 chat with one agent working for\n * one person looks as it did before labels. Unstamped answers count for\n * nothing.\n *\n * It decides over the messages the client holds (on a windowed wire, the\n * pages loaded so far), as the human-author avatars do: a page of older\n * history that brings another agent or person turns the labels on. Each\n * label still names its own answer's stamp, so loading history never changes\n * what an answer is attributed to, only whether the line shows.\n *\n * A turn the conversion split into one row per answerer turns the labels on\n * too, before the next agent's stamp lands: while several agents answer one\n * message, the host's record already says a second agent is answering, so\n * the first agent's answer is labelled from the moment the second one's row\n * appears.\n */\nexport function threadShowsAnswerLabels(messages: readonly ThreadMessage[]): boolean {\n  let first: DeepAgentAnsweredBy | null = null;\n  for (const message of messages) {\n    if (isSplitAnswerRow(message)) return true;\n    for (const answer of readMessageAnswers(message)) {\n      if (first === null) {\n        first = answer;\n      } else if (!isSameAnswerer(first, answer)) {\n        return true;\n      }\n    }\n  }\n  return false;\n}\n\n/**\n * Whether a message's answers are labelled: always once the thread's answers\n * name several agents or principals (`threadShowsLabels`), and otherwise when\n * one of them worked for a person other than the viewer. Without a known\n * viewer that last rule is off, so a 1:1 chat never flashes labels while the\n * viewer loads.\n */\nexport function showsAnswerLabel({\n  answers,\n  threadShowsLabels,\n  viewerId,\n}: {\n  answers: readonly DeepAgentAnsweredBy[];\n  threadShowsLabels: boolean;\n  viewerId: string | null;\n}): boolean {\n  if (answers.length === 0) return false;\n  if (threadShowsLabels) return true;\n  return (\n    viewerId !== null &&\n    answers.some((answer) => isPersonPrincipal(answer.for_id) && answer.for_id !== viewerId)\n  );\n}\n\nfunction answererName(answer: DeepAgentAnsweredBy): string {\n  if (answer.agent_name !== null) return answer.agent_name;\n  return answer.agent.startsWith(ASSISTANT_AGENT_PREFIX)\n    ? ATHENA_ASSISTANT_NAME\n    : UNNAMED_AGENT_NAME;\n}\n\nfunction forWhomName(answer: DeepAgentAnsweredBy, viewerId: string | null): string | null {\n  if (answer.for_id !== null && answer.for_id === viewerId) return 'you';\n  if (answer.for_name !== null && isPersonPrincipal(answer.for_id)) return answer.for_name;\n  return null;\n}\n\nfunction joinNames(names: readonly string[]): string {\n  if (names.length <= 1) return names[0] ?? '';\n  return `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`;\n}\n\n/**\n * The label's words: who answered, then whom for. \"Finance · for you\",\n * \"Athena · for Priya Shah\", \"Finance\" (a run that worked for nobody, or for\n * an agent's own run). The agent is the collab agent's name, else\n * {@link ATHENA_ASSISTANT_NAME} for someone's own assistant, else \"Agent\".\n * Several agents answering for the same principal read \"Finance and Legal ·\n * for you\"; answers for different principals are listed apart, even when the\n * people share a name (\"Finance · for Alex, Legal · for Alex\"). `null` when\n * the message holds no answers.\n */\nexport function answerLabelText({\n  answers,\n  viewerId,\n}: {\n  answers: readonly DeepAgentAnsweredBy[];\n  viewerId: string | null;\n}): string | null {\n  if (answers.length === 0) return null;\n  // One group per principal (nobody is one too), never per displayed name: two\n  // people who share a name stay two recipients.\n  const groups: { forId: string | null; names: string[]; forWhom: string | null }[] = [];\n  for (const answer of answers) {\n    const name = answererName(answer);\n    const forWhom = forWhomName(answer, viewerId);\n    const group = groups.find((candidate) => candidate.forId === answer.for_id);\n    if (group === undefined) {\n      groups.push({ forId: answer.for_id, names: [name], forWhom });\n      continue;\n    }\n    if (!group.names.includes(name)) group.names.push(name);\n    // A recipient one answer left unnamed takes the name a later answer for\n    // the same principal carries. The first name found wins: answers stamped\n    // under two names for one id (a rename between runs) read as the first.\n    group.forWhom ??= forWhom;\n  }\n  return groups\n    .map(({ names, forWhom }) =>\n      forWhom === null ? joinNames(names) : `${joinNames(names)}${LABEL_SEPARATOR}for ${forWhom}`\n    )\n    .join(', ');\n}\n"],"names":["getExternalStoreMessages"],"mappings":"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"}

package/dist/agent-runtime/src/answer-label.d.ts

@@ -0,0 +1,104 @@
+import { type ThreadMessage } from '@assistant-ui/core';
+import type { LangChainMessage } from '@assistant-ui/react-langgraph';
+/**
+ * `metadata.custom` key naming the agent that answered an AI message and whom
+ * its run worked for (identity v7 D13: "each answer is labelled with its
+ * agent, 'for <author>'").
+ *
+ * The backend stamps it on every answer a deep-agent run's model produces
+ * (`agora/.../conversation_agents/answer_label.py`), under the
+ * `additional_kwargs.metadata` bag the converter exposes as
+ * `message.metadata.custom`, and mirrors it onto the live wire once the
+ * model's turn lands. Only the server writes it. Answers written before the
+ * stamp existed carry none, and get no label.
+ */
+export declare const ATHENA_ANSWERED_BY_KEY = "answered_by";
+/** The agent that answered and whom its run worked for, as the backend stamps them. */
+export interface DeepAgentAnsweredBy {
+    /** `collab_agent:<asset id>` for a team agent, `assistant:<principal id>` for someone's own assistant. */
+    agent: string;
+    /** The collab agent's name when it answered; `null` for an assistant, which clients name. */
+    agent_name: string | null;
+    /** Whom the run worked for: a person (`user_…`), an agent's or automation's own run, or nobody (`null`). */
+    for_id: string | null;
+    /** That person's display name when it answered, else `null`. */
+    for_name: string | null;
+}
+/** What a label calls someone's own assistant: the managed default agent's product name. */
+export declare const ATHENA_ASSISTANT_NAME = "Athena";
+/**
+ * Parse an `answered_by` stamp off a wire value.
+ *
+ * A stamp without a string `agent` is no stamp at all; absent or malformed
+ * optional fields read as `null`, so a partly malformed stamp still names its
+ * agent and never names a person it can't.
+ */
+export declare function readAnsweredBy(value: unknown): DeepAgentAnsweredBy | null;
+/** The row run id of an answer by `agent` for `forId` (see `withAnswerRows`). */
+export declare function answerRowRunId(agent: string, forId: string | null): string;
+/** The `answered_by` stamp an AI message as the wire carries it holds; `null` for any other message. */
+export declare function readLangChainAnswer(source: LangChainMessage | undefined): DeepAgentAnsweredBy | null;
+/**
+ * The answers one thread message holds: each agent that answered in it and
+ * whom it worked for, in the order they answered, one entry per agent and
+ * principal.
+ *
+ * Read off the message's bound source messages, not its joined
+ * `metadata.custom`: assistant-ui joins consecutive AI messages into one
+ * turn, and its joined metadata keeps only the last stamp. The deep-agent
+ * conversion gives each agent that answers one message in turn (D13 several
+ * agents, one message) a row of its own (`answer-rows.ts`), so a row
+ * normally holds one answer; a conversion without that split (another
+ * pipeline, a stamp that never landed) still names every agent of the row.
+ * A message with no bound sources (another runtime) falls back to the joined
+ * value. Cached per message object: a settled message keeps its object
+ * across a streamed token, so a thread-wide scan per token reads only the
+ * message that changed.
+ */
+export declare function readMessageAnswers(message: ThreadMessage): readonly DeepAgentAnsweredBy[];
+/**
+ * The thread-wide half of the label decision: whether the transcript's
+ * answers name two or more agents, or two or more principals they worked
+ * for. Then every answer is labelled; a 1:1 chat with one agent working for
+ * one person looks as it did before labels. Unstamped answers count for
+ * nothing.
+ *
+ * It decides over the messages the client holds (on a windowed wire, the
+ * pages loaded so far), as the human-author avatars do: a page of older
+ * history that brings another agent or person turns the labels on. Each
+ * label still names its own answer's stamp, so loading history never changes
+ * what an answer is attributed to, only whether the line shows.
+ *
+ * A turn the conversion split into one row per answerer turns the labels on
+ * too, before the next agent's stamp lands: while several agents answer one
+ * message, the host's record already says a second agent is answering, so
+ * the first agent's answer is labelled from the moment the second one's row
+ * appears.
+ */
+export declare function threadShowsAnswerLabels(messages: readonly ThreadMessage[]): boolean;
+/**
+ * Whether a message's answers are labelled: always once the thread's answers
+ * name several agents or principals (`threadShowsLabels`), and otherwise when
+ * one of them worked for a person other than the viewer. Without a known
+ * viewer that last rule is off, so a 1:1 chat never flashes labels while the
+ * viewer loads.
+ */
+export declare function showsAnswerLabel({ answers, threadShowsLabels, viewerId, }: {
+    answers: readonly DeepAgentAnsweredBy[];
+    threadShowsLabels: boolean;
+    viewerId: string | null;
+}): boolean;
+/**
+ * The label's words: who answered, then whom for. "Finance · for you",
+ * "Athena · for Priya Shah", "Finance" (a run that worked for nobody, or for
+ * an agent's own run). The agent is the collab agent's name, else
+ * {@link ATHENA_ASSISTANT_NAME} for someone's own assistant, else "Agent".
+ * Several agents answering for the same principal read "Finance and Legal ·
+ * for you"; answers for different principals are listed apart, even when the
+ * people share a name ("Finance · for Alex, Legal · for Alex"). `null` when
+ * the message holds no answers.
+ */
+export declare function answerLabelText({ answers, viewerId, }: {
+    answers: readonly DeepAgentAnsweredBy[];
+    viewerId: string | null;
+}): string | null;