@athenaintel/react 0.28.1 → 0.32.0

package/README.md

@@ -16,6 +16,18 @@ npm install @propelauth/react
 
 ## Upgrading
 
+SDK0.29.0 uses native Statewire wire2026-09-30 with Athena application2026-09-13
+when installed with public, unpatched dependencies, over HTTP/SSE: published
+statewire0.20.0 pings a WebSocket with empty frames that Athena's hosts reject,
+so the SDK opens a socket only over the patched client the monorepo's own apps
+install. It requires a compatible backend. Publication is temporarily withheld until production HTTP+WebSocket
+and authorization tests pass and a compatible backend rollback release is
+retained. The publish workflow requires a manual
+`PRODUCTION_NATIVE_CONTEXT_AND_ROLLBACK_QUALIFIED` acknowledgement; dry runs
+remain available. Computer templates keep SDK0.28.0 until the qualified
+release is published. The qualification steps and gate removal condition are
+in the [coordinated release runbook](../../docs/runbooks/coordinated-client-releases.md#public-native-context-publication-gate).
+
 The SDK pins its assistant-ui runtime (`@assistant-ui/tap`, `store`, `core`,
 `react`, `react-statewire`, `statewire`) at exact versions, and those packages
 carry React contexts and module singletons: an app must resolve exactly **one**
@@ -104,6 +116,78 @@ function App() {
 
 `config` accepts `apiKey`, `token`, `getToken`, `apiUrl`, `backendUrl`, `appUrl`, `statewireSyncUrl`, `trustedParentOrigins`, `environment`, `extraRunConfig`, and `posthog`. Top-level `apiKey`, `token`, `apiUrl`, `backendUrl`, `appUrl`, and `environment` props remain supported as compatibility aliases, but `config` is now the preferred API.
 
+### Several chats side by side
+
+A host can show several chats at once: one `AthenaProvider` with `enableThreadList` drives the
+session list and its chat, and each further chat is an `AthenaProvider` of its own, bound to one
+thread with `threadId`, mounted anywhere in the tree (under the first one too):
+
+```tsx
+const [thread] = useState(() => ({ threadId: mintThreadId(), isNew: true }));
+
+<AthenaProvider config={config} threadId={thread.threadId} threadIsNew={thread.isNew}>
+  <AttachmentProvider store={attachments}>
+    <QuoteProvider store={quote}>
+      <AthenaChat />
+    </QuoteProvider>
+  </AttachmentProvider>
+</AthenaProvider>
+```
+
+- `threadIsNew` says the host minted `threadId` (`mintThreadId`) for a chat that has not started:
+  it attaches as new until the host turns it false, once the session list has the thread.
+- Each provider's assistant client is its own root, and one without a thread list hides any list
+  above it, so a chat never defines another's tools or follows its thread.
+- `createAttachmentStore()` / `createQuoteStore()` give each chat's composer its own staged
+  attachments and quote (`<AttachmentProvider store>`, `<QuoteProvider store>`), kept outside React
+  so they survive the chat remounting in another window.
+- ⌘L quotes a selection into the chat it was made in, and one made outside every chat (or an
+  embedded frame's text) into the chat the person last focused.
+- `SessionList`'s `onOpenInNewTab` hands the host a session to open in such a chat.
+
+### A model picker, and a session's own model
+
+Pass the picked model as `model`. Changing it while a session is open applies
+to that session's next turn:
+
+- On a session that has not run yet, the next send carries it, and the server
+  keeps it as the session's model.
+- On a session that has run, the server runs every turn with the model the
+  session's server config holds (another client, such as Athena itself, can
+  change it too), so the SDK writes the new model there
+  (`config/patch {model}`). Setting `model` back to `undefined` clears it, so
+  the collab agent's own model, or the default, applies again.
+- The model a session is opened with is never written: opening a session never
+  overrides the model someone chose for it.
+
+Show the session's real model when it opens with `useAthenaThreadModel()`
+(inside `<AthenaProvider>`):
+
+```tsx
+import { useAthenaThreadModel, useAthenaStatewireThreadId } from '@athenaintel/react';
+import { useEffect, useRef } from 'react';
+
+function SessionModelSeed({ onSessionModel }: { onSessionModel: (model: string | null) => void }) {
+  const threadId = useAthenaStatewireThreadId();
+  const { model, configured, ready } = useAthenaThreadModel();
+  const seededFor = useRef<string | null>(null);
+  useEffect(() => {
+    // Once per session, after its snapshot lands; a session without server
+    // config keeps the picker's current value.
+    if (!ready || seededFor.current === threadId) return;
+    seededFor.current = threadId;
+    if (configured) onSessionModel(model); // null: the agent's / default model ("Auto")
+  }, [threadId, model, configured, ready, onSessionModel]);
+  return null;
+}
+```
+
+`model` is `null` when the session pins no model; `configured` is `false` for
+a session without server config yet; wait for `ready` before reading either. A
+refused write (a view-only collaborator, or a workspace whose sessions cannot
+hold server config) is reported as a `statewire.config` diagnostics event, and
+the session keeps running with its own model.
+
 If `config.appUrl` is omitted, the provider resolves it from the parent bridge or from the matching Athena environment defaults. Known Athena staging and production `apiUrl` and `backendUrl` values automatically fall back to the corresponding frontend origin.
 
 Use `trustedParentOrigins` when the SDK runs inside an iframe on a private-cloud or custom parent domain and you want to explicitly allow postMessage auth/config from that parent. Only the window that frames the app is heard. By default `athenaintel.com` hosts, localhost and your own origin are trusted, except the hosts that serve customer-written code (`*.app.athenaintel.com`, `*.code-sandpack.athenaintel.com` and friends; see "What's new in 0.28.0").
@@ -174,8 +258,9 @@ What the statewire transport wires up in `AthenaChat`:
   `icon`, `extraAction`, `notice`, `renderResult`, `onOpenAsset`,
   `hideInternalIdArgs`) instead of being copied. `@athenaintel/react/super-grouping`
   exports the grouped ("conversational") view of an assistant turn —
-  `SuperGroupingCard`, `SuperGroupingFinalText`, `CollapsibleGroup`, the
-  activity-timeline derivation, and the tool-based grouping function — with
+  `SuperGroupingTranscript` (what `AthenaChat` renders), `SuperGroupingCard`,
+  `SuperGroupingFinalText`, `CollapsibleGroup`, the activity-timeline
+  derivation, and the tool-based grouping function — with
   slots for the host's text/tool renderers and controls (`renderHeaderActions`,
   `renderRunningMeta`, `summaryDetails`, `waitingTools`, `expansionKey`), so
   Olympus and the Chrome extension mount one card instead of copies.
@@ -196,7 +281,17 @@ What the statewire transport wires up in `AthenaChat`:
   paywall refusals) render as a dismissible banner; a degraded connection
   shows a reconnect strip; a send into a thread created by the retired legacy
   runtime is refused with a dismissible read-only notice (start a new chat).
-  Custom hosts can read all of it via `useAthenaStatewireLifecycle`.
+  A send the server admits but refuses to START — a session keeps the
+  collab-agent channel (the app's mode) it began on, so a send in the other
+  mode is refused with `collab_agent_channel_session_mismatch` — leaves the
+  message queued and the run in `error`; `StatewireRunRefusalNotice` (mounted
+  by `AthenaChat` above the queue) shows the server's `detail.message` and, for
+  that code, a "Start a new session" action (the thread list's `newThread`).
+  The same code on a rejected command reaches `StatewireErrorBanner` with the
+  same action (`AthenaStatewireErrorNotice.code`). `readRunStartRefusal` and
+  `COLLAB_AGENT_CHANNEL_SESSION_MISMATCH` are exported for hosts with their
+  own thread UI. Custom hosts can read all of it via
+  `useAthenaStatewireLifecycle`.
 - **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
@@ -248,6 +343,7 @@ server omits them and the SDK reads `undefined`):
 | `attention_source` | `attentionSource` | `interrupt` · `run` · `pull_request` · `termination` · `wake` · `handoff` |
 | `is_favorited` | `isFavorited` | boolean — toggled through `setFavorited` / `POST /api/conversations/threads/favorite` |
 | `last_wake` | `lastWake` | `{ source, reason, at }` |
+| `created_by_me` | `createdByMe` | boolean — the viewer started the session (`false`: shared with them) |
 | `pull_requests` (opt-in: `include_pull_requests`) | `pullRequests` | `[{ repoFullName, number, url, title, state OPEN/CLOSED/MERGED, isDraft, reviewDecision, checksState SUCCESS/FAILURE/PENDING/NONE, updatedAt }]` — `[]` none, `null` unreadable right now |
 
 The per-user conversation index pushes `attention`, `next_action`,
@@ -277,6 +373,10 @@ Same visual language as `ThreadList` (Tailwind via `cn`, lucide icons), plus:
 - a trailing action cluster per row, revealed on hover / focus (a pinned pin
   and any action whose write is in flight stay visible) — every action a
   labelled `<button>` that is a sibling of the row control, never nested:
+  - **Open in new tab** (prop `onOpenInNewTab`, absent by default): hands the
+    host `{ threadId, title }` instead of selecting the row, as does a
+    ⌘-click (Ctrl-click) or middle-click on the row (see "Several chats side
+    by side");
   - **Rename** (prop `showRename`, default `true`): the title becomes an
     input in place; Enter commits, Escape cancels, blur commits; an unchanged
     or empty title is never sent; the row shows the new title at once and
@@ -315,7 +415,10 @@ Same visual language as `ThreadList` (Tailwind via `cn`, lucide icons), plus:
   answer (`hasResolvedFirstPage`); a background refresh keeps the rows it has;
 - a search box wired to the server-side `search` (prop `showSearch`, default
   `true`), `Load more` over the shared pager, and `New Chat` / refresh as in
-  `ThreadList`.
+  `ThreadList` (prop `showNewChat`, default `true`; `false` for a host with
+  its own new-session control);
+- an origin badge per row (prop `originBadges`: `'all'` by default,
+  `'external'` to leave sessions started in the web app unbadged, `'none'`).
 
 The pin writes `POST /api/conversations/threads/favorite`
 (`{ thread_id, is_favorited }` → the server's state after the write) with the
@@ -385,6 +488,193 @@ only when it is an `https://github.com/<repo>/…` URL for that repository
 The full message text always reaches the model; the marker is provenance for
 rendering only.
 
+## Sessions page and inbox
+
+A full-page, Devin-style session list and a notifications inbox, both on top
+of `enableThreadList` and live through the same conversation index as
+`SessionList`:
+
+```tsx
+import { AthenaProvider, InboxButton, SessionsPage } from '@athenaintel/react';
+
+<AthenaProvider enableThreadList config={{ token }}>
+  <header><InboxButton onOpenSession={() => showChat()} /></header>
+  <SessionsPage
+    onOpenSession={() => showChat()}
+    labels={{ agents: { asset_123: 'Athena Engineer' }, channels: { ask: 'Ask' } }}
+  />
+</AthenaProvider>
+```
+
+### `SessionsPage`
+
+- **Filters the server applies.** A Filter menu (status, pull requests,
+  unread, pinned, creator, who started it, agent, mode, origin, created /
+  updated date) and a title search. Each filter travels to
+  `POST /api/conversations/threads/list` as a predicate of the server's one
+  page statement, ANDed onto the list's unchanged permission gate — a filter
+  only narrows what the viewer already sees, and `Load more` continues the
+  filtered set. Active filters show as removable chips; **Save as default**
+  remembers them in this browser (`storageKey` namespaces it), **Reset to
+  default** goes back.
+- **Display options.** Sort by last update or creation, newest or oldest
+  first; group by what each session needs (Needs you, Working, Ready,
+  Waiting, Error, Done), by run status, or not at all; show or hide the
+  Status, Origin, Mode, Pull requests, Creator, Created and Updated columns
+  (remembered per browser).
+- **A status column that says what to do.** `sessionStatusChip`: the server's
+  next action where the person must act ("Approve send email", "Merge #12"),
+  else Working / Sleeping (a follow-up is pending) / Waiting / Error /
+  PR merged / Done — an orange, blue, green, violet, red or grey dot by
+  attention.
+- **Row actions** (revealed on hover / focus): mark read / unread
+  (`setReadState` → `POST /api/conversations/threads/read-state`), pin,
+  archive — the provider's writes, so the row flips in every list at once.
+- **Export CSV** of the loaded rows (`sessionsCsv`; cells a spreadsheet would
+  run as a formula are prefixed with `'`).
+
+### `Inbox` / `InboxButton`
+
+The inbox is the viewer's own sessions, newest activity first, minus the ones
+dismissed from it — read through the same route with `created_by_me` +
+`exclude_dismissed` (`INBOX_QUERY`; the Unread tab adds `unread_only`). No
+endpoint of its own. Each row: an unread dot, the title, the latest message
+(two lines), a state chip (`inboxStateChip`: Needs you, Working, PR ready,
+Sleeping, Waiting, Error, PR merged, PR closed, Answered) and the time.
+Opening a row selects the session and marks it read; **Mark all read** marks
+the loaded unread rows; **Dismiss** uses
+`POST /api/conversations/threads/notifications/dismiss` (EDIT on the
+session — a dismissed session comes back with its next message).
+`InboxButton` is a bell with the unread count (`useAthenaInboxUnreadCount`,
+the Unread tab's first page: `50+` past one page) that opens the inbox in a
+popover.
+
+### Server filters and older servers
+
+`useAthenaSessions({ query })` is the data layer both components use, for
+hosts drawing their own rows. `query` is an `AthenaSessionsQuery`:
+
+| Field | Server field | Meaning |
+|---|---|---|
+| `search` | `search` | case-insensitive title match |
+| `runStatuses` / `sessionStatuses` | `run_statuses` / `session_statuses` | status_v2 planes (`running` leaves out runs silent for 12 hours, as every list does) |
+| `unreadOnly` | `unread_only` | not read since it last changed (the read receipt) |
+| `favoritesOnly` | `favorites_only` | pinned by the viewer |
+| `hasPullRequests` | `has_pull_requests` | opened a pull request (`true`) or none (`false`) |
+| `createdByMe` | `created_by_me` | the viewer's own (`true`) or shared with them (`false`) |
+| `collabAgentIds` / `collabChannelIds` | `collab_agent_ids` / `collab_channel_ids` | the collab agent and its channel (mode); `'default'` (`DEFAULT_COLLAB_CHANNEL`) is the agent's default channel; channels need an agent |
+| `startChannels` | `start_channels` | where it started (`web`, `github`, `email`, …) |
+| `createdAfter` / `createdBefore` / `updatedAfter` / `updatedBefore` | same, snake_case | ISO bounds, after inclusive, before exclusive |
+| `excludeDismissed` / `excludeTriggered` | `exclude_dismissed` / `exclude_triggered` | not dismissed from the inbox / started by a person |
+| `sort` / `direction` | `sort` / `direction` | `updated` or `created`, `desc` or `asc` |
+
+An agora ignores request fields it does not know, so every list response now
+names the filters it applies (`supported_filters`). The hook reads that once
+per identity (a one-row probe) and splits the query (`planSessionsQuery`):
+fields the server applies are sent; fields it cannot are applied to the
+loaded rows instead (`degradedFields` — exact per page, but a page can come
+back short, and `SessionsPage` says so); fields the rows carry nothing to
+test on (creator, dismissed; pull requests when the list does not fetch
+them) are reported in `unsupportedFields` / `unavailableFields` and not
+applied, so `SessionsPage` disables them rather than show wrong rows.
+Server-applied filters are still checked on rows a live push changed, so a
+session you just read leaves "Unread" and a finished one leaves "Running".
+`listThreads` takes the server filters as `filters` (`ThreadListFilterBody`),
+and `app_ids` (`additionalListAppIds`) now reaches the server: the request
+body used to drop it.
+
+## Session workbench
+
+A Devin-style workspace pane beside the chat for the active session: a tab
+strip of panes, a "+" menu right after the tabs to open more (with a search
+box; Enter opens the first match), closable tabs, a collapse to a rail, a
+maximize that gives the workspace the chat's width (the chat stays mounted,
+hidden), and a resizable edge. With every tab closed, the column lists each
+pane with its `description`, centred, to open one.
+
+```tsx
+import { AthenaChat, AthenaLayout, AthenaProvider, SessionList, SessionWorkbench } from '@athenaintel/react';
+
+<AthenaProvider enableThreadList config={{ token }}>
+  <aside><SessionList /></aside>
+  <AthenaLayout workbench={<SessionWorkbench />}>
+    <AthenaChat />
+  </AthenaLayout>
+</AthenaProvider>
+```
+
+`AthenaLayout`'s `workbench` prop puts it in a right-hand column
+(`defaultWorkbenchPercent`, default 40; `defaultWorkbenchCollapsed`). With a
+workbench the layout opens no asset column of its own: assets the agent or the
+person opens show as the workbench's **Open assets** tab (closing the tab
+closes the asset panel). Maximize is offered only inside `AthenaLayout`, which
+owns the column's width; collapsing a maximized workspace brings the chat back
+beside the rail. `SessionWorkbench` also works on its own anywhere under
+`<AthenaProvider>`; it then keeps its collapsed state itself.
+
+Built-in panes and what each reads:
+
+| Pane | id | Source |
+|---|---|---|
+| Tasks | `tasks` | The thread state's `todos` channel (the deepagents plan), else the newest `write_todos` call in the loaded transcript — "N/M done" and numbered steps with their status |
+| Shell | `shell` | Every `execute` call in the loaded transcript, newest first: first line of the command, the machine it ran on (`sandbox_asset_id` named through the workspace's computers, else "Session sandbox"), the exit status parsed from `[Command succeeded/failed with exit code N]`, the time; searchable; a row expands to its output (first 4,000 characters) |
+| Computer | `computer` | `GET /api/conversations/threads/{id}/workspace`: the session computer, else the most recent computer — its state (`GET /api/sandbox/computer/{id}/status`, a read that never wakes it, re-read every 30 s while shown), "Open in Athena", and "Copy SSH command" (`GET /api/v0/computer/{id}/ssh-access`, offered only when the viewer may edit the computer); the other computers it used below |
+| Pull requests | `pull-requests` | The thread list's live pull-request state for the session (`enableThreadList`): number, title, state, checks and review decision, each a link to GitHub |
+| Attachments | `attachments` | The workspace's assets — what the session created or edited — with type, last update, "Open in Athena", and a click that opens it in the asset panel when an `AthenaLayout` hosts one |
+
+"Open in Athena" links go to the deployment's Athena frontend
+(`athenaLinkAppUrl`): in an app a computer serves, Marathon's `/_athena/auth`
+mints the app's own origin as `appUrl`, so a known Athena backend's frontend is
+used instead. Every workspace read is gated server-side (thread access, then
+each asset's own permission), so a pane lists only what the viewer may open. One query
+serves every pane; it is idle for a never-started chat, re-reads every 15 s
+while the run is live and once more as it settles, and is keyed by the
+signed-in principal and a one-way credential fingerprint, so one account's
+cached workspace is never shown to another. Open assets stay mounted (hidden)
+while another pane shows or the workbench is a rail, so their viewers keep
+their state.
+
+**Tabs per thread.** Each thread keeps its open tabs and its active tab for as
+long as the workbench stays mounted (in memory only — nothing is written to
+storage); a thread it has not seen opens `defaultOpenPaneIds` (Tasks, Shell,
+Computer).
+
+**Custom panes.** `panes` is a registry: spread the built-ins and add your own.
+A pane is `{ id, title, description?, icon?, render(context) }` (`description`
+is the one line the empty column shows under the title), where `context` is
+`{ threadId, isPersisted, isRunning }`; inside a pane,
+`useSessionWorkbench()` reads the same context and
+`useSessionWorkbenchWorkspace()` the shared workspace query.
+
+```tsx
+import {
+  DEFAULT_SESSION_WORKBENCH_PANES,
+  SessionWorkbench,
+  type SessionWorkbenchPane,
+} from '@athenaintel/react';
+import { ScaleIcon } from 'lucide-react';
+
+const MATTER_PANE: SessionWorkbenchPane = {
+  id: 'matter',
+  title: 'Matter',
+  icon: ScaleIcon,
+  render: ({ threadId, isPersisted }) =>
+    isPersisted && threadId ? <MatterSummary threadId={threadId} /> : <p>No matter yet.</p>,
+};
+
+<SessionWorkbench
+  panes={[...DEFAULT_SESSION_WORKBENCH_PANES, MATTER_PANE]}
+  defaultOpenPaneIds={['matter', 'tasks']}
+/>
+```
+
+The built-in pane bodies (`SessionTasksPane`, `SessionShellPane`, …), their
+registry entries (`SESSION_WORKBENCH_TASKS_PANE`, …), the data hooks
+(`useAthenaSessionWorkspace`, `useAthenaComputerStatus`,
+`useAthenaComputerSshAccess`) and the pure derivations behind them
+(`deriveShellRows`, `filterShellRows`, `deriveTaskSteps`, `taskProgress`,
+`workspaceComputers`) are exported for hosts composing their own.
+
 ## Voice Sessions (`@athenaintel/react/voice`)
 
 `useAthenaVoiceSession` runs a real-time voice conversation with an Athena
@@ -420,10 +710,10 @@ const voice = useAthenaVoiceSession({
 **Voice tools.** `enabled_tools` takes voice tool names (`AthenaVoiceToolId`),
 not the chat `Toolkits` ids — `'web_search_browse_toolkit'` is not a voice tool,
 `'web_search'` is. Available: `web_search` (`search_web` is a legacy alias),
-`browse` (read a URL), `search_knowledge_base` and `search_knowledge_base_lr`
-(the workspace knowledge base; `_lr` is the thorough long-running retrieval),
-`read_full_asset` and `search_assets` (as the viewer), `ask_agent` (hand a
-question to the general agent), `save_note`, `get_current_time_est`. Tools that
+`browse` (read a URL), `read_full_asset` and `search_assets` (as the viewer),
+`ask_agent` (hand a question to the general agent), `save_note`,
+`get_current_time_est`. `search_knowledge_base` and `search_knowledge_base_lr`
+are retired: still accepted, and ignored. Tools that
 call back into the client over room RPC (`write_to_clipboard`, the desktop and
 mobile tools) are not part of the hook's contract. Omit the field for the
 server's default set; pass `[]` for pure conversation. The server refuses
@@ -470,6 +760,56 @@ 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.32.0
+
+**A model picked after mount reaches the server.** The provider registered its run config once per thread attach, so a `model` (or `channel`, `tools`, `systemPrompt`, …) changed after mount never reached the next send unless something else happened to re-sync the context. The registration is now keyed by the built run config's value: a changed value re-syncs before the next send, while fresh array literals per render still change nothing.
+
+**A model changed on a session that has run applies.** Once a session has server config, the server runs every turn with the model that config holds and ignores the one a send carries, so a picker change after the first turn used to be dropped. Changing `model` while such a session is open now writes it there (`config/patch {model}`; `undefined` clears it so the collab agent's own model applies). The model a session is opened with is never written. See [A model picker, and a session's own model](#a-model-picker-and-a-sessions-own-model).
+
+**`useAthenaThreadModel()`** returns `{ model, configured, ready }`: the model the open session's server config holds, so an app can show a session's real model when it opens. A refused write is reported as the new `statewire.config` diagnostics event.
+
+**A collab agent's session no longer records the SDK default as its model.** With `agent` set and no `model`, the run config's `panel_config` (which the server stores on the session's first run and replays to every client) carried `DEFAULT_STATEWIRE_MODEL`, so Athena showed that model for sessions running the agent's own. It now names no model there.
+
+## What's new in 0.31.0
+
+**Draft tool cards stay in the conversation.** In the grouped view (`groupToolCalls`), a tool flagged `inline` in the shared display registry (`@athenaintel/agent-runtime` `ToolDisplayMeta.inline`; today the email and calendar-event draft tools) renders its card below the activity header, outside the "Used N tools" and "Show tool details" disclosures, and stays mounted whether the card is collapsed or not, so the person can edit and send the draft without opening anything. The call still appears as a step in the timeline, the run does not pause, and the card is not rendered a second time inside the details. The transcript view `AthenaChat` renders (`SuperGroupingTranscript`) does the same per activity segment: the draft card sits under its segment's step row, and a segment whose only step is a draft offers no empty "Show tool details". `SuperGroupingCard` and `SuperGroupingTranscript` take `isInlineTool` to override the registry per host; `excludePartsFromGroups` is exported for hosts that build their own grouped view.
+
+## What's new in 0.30.1
+
+**Spoken words no longer retype from an empty bubble while a voice turn speaks over a run.** In the grouped (conversational) view, the answer below the card is the text after the last tool call plus the words of every spoken voice turn. `SuperGroupingFinalText` used to join those parts into one string, so when a spoken turn kept streaming while the run's own reply streamed after it, the joined text changed in the middle rather than at its end. `MarkdownText`'s streaming reveal restarts whenever its text stops extending what it showed, so the whole answer was wiped and retyped on every spoken word. Each answer part now renders through its own `TextComponent` (keyed by its content index) inside a `data-slot="super-grouping-final-text"` column, and only the last part carries the running status and caret. `getFinalTextParts` (with `FinalTextSegment`) is exported beside `getFinalText`, which still returns the joined string. Nothing to change in your app.
+
+## What's new in 0.30.0
+
+**Session workbench, closer to Devin's.** The "+" menu now sits right after the tabs and has a search box (Enter opens the first match). Inside `AthenaLayout`, a maximize button gives the workspace the chat's width; the chat stays mounted, hidden, and collapsing a maximized workspace brings it back. With every tab closed, the column lists each pane centred with a one-line `description`, which is a new optional field on `SessionWorkbenchPane` that the built-in panes now carry. Tabs use 13px labels, and the close control stays quiet until the tab is hovered, focused or selected. Pure helper: `filterWorkbenchPanes`.
+
+**`SessionList` options for hosts with their own chrome.** Set `showNewChat={false}` to drop the New Chat and refresh buttons when your sidebar has its own new-session control. `originBadges` picks which rows carry an origin badge: `'all'` (the default, as before), `'external'` (every origin except the web app, so sessions started in a browser tab of the app carry none, while Slack, GitHub, Chrome and the rest still do), or `'none'`. `sessionOriginBadge` and `WEB_APP_ORIGIN_LABEL` are exported.
+
+**Composer hints.** `<AthenaChat composer={{ placeholder, runningPlaceholder }}>` sets the empty composer's hint. `runningPlaceholder` shows while a run is live, when a message steers or queues instead of starting a turn. The editor repaints a changed hint in place without being rebuilt.
+
+**`@assistant-ui/store` 0.3.21.** Its client accessors answer `call`, `apply` and `bind` themselves, so apps whose bundler lowers optional chaining (Vite's default target) no longer crash on mount (#44102). No `build.target` workaround is needed.
+
+## What's new in 0.29.5
+
+**No more "linkifyjs: already initialized" warning.** The chat text schema no longer passes `protocols: ["athena-point"]` to Tiptap's Link extension. Link registers those schemes with linkifyjs in every editor's `onCreate`, and linkifyjs accepts a new scheme only before its first scan, so every composer or message body created after the first one logged `linkifyjs: already initialized - will not register custom scheme "athena-point"`. Chrome shows it on an extension's Errors page. Screen-point chips are unchanged: they arrive as markdown links (`[label](athena-point://…)`), which parse without linkify, and the chat link allow-list still accepts the scheme. Only a bare `athena-point://…` string typed into the composer is no longer turned into a link by itself. Nothing to change in your app.
+
+## What's new in 0.29.4
+
+**A streaming reply no longer jumps a line up and down in narrow panels.** The chat-ui message components no longer load `@assistant-ui/react-markdown/styles/dot.css`. That stylesheet put a pulsing "●" after the last block of every running message body, next to the body's own caret. The dot and its margins need about 17px at the end of the line, so in a narrow panel it wrapped onto its own line before the text did: the thread scrolled up one line, then the next word dropped down to join the dot. The caret is now the only streaming indicator. A message that has no text yet still shows the "Thinking..." indicator.
+
+## What's new in 0.29.3
+
+**Tooltips, popovers and the composer's agent and model menus draw their own background again, in any host.** They render outside the provider wrapper, under `document.body`, carrying the `.athena-sdk` scope class for their tokens. That class is `display: contents` for the wrapper's sake, and nothing on a tooltip undid it, so every SDK tooltip lost its box: no background, padding or radius, just the text and the arrow. Themed popovers and pickers also carried `.athena-themed`, whose unlayered `display: contents` beat their `block`. A host whose own Tailwind compiles the same utility names against tokens in another format also broke them: shadcn's HSL channels, for example, make `bg-popover` `hsl(var(--popover))`, and that is invalid for the SDK's full colours, so the menu was transparent over the page. The portaled roots now set their box (`display: block`) and colours (`var(--popover)` / `var(--popover-foreground)` / `var(--border)` for panels, `var(--foreground)` on `var(--background)` for tooltips) inline, which no stylesheet rule beats; the theme's variables still apply through the same inline style. What your own `className` on `TooltipContent` sets stays yours: a colour or display class (`bg-red-600`, `hover:text-white`, `flex`) keeps that property out of the inline defaults, as before, and `style` overrides any of them. A tooltip's arrow follows the tooltip's background when that background is inline, whether it is the default or your `style`. Nothing to change in your app.
+
+## What's new in 0.29.2
+
+Tool cards inside an expanded collapsible tool group and the super-grouping "Run details" panel are now spaced with flex `gap-2` instead of `space-y-2`, so cards wrapped in a `display: contents` element (e.g. a host's deep-link anchor) keep the 0.5rem gap between them; boxed children look the same as before. `SuperGroupingCard` also accepts `classNames.detailsParts` to tune the gap (or other classes) on the flex column the run's parts render in.
+
+## What's new in 0.29.1
+
+**A running grouped turn shows one status line.** The activity card's header already says what the run is doing ("Thinking", "Preparing response", "Searching the web"); the elapsed counter that used to sit beneath it as a second row ("Working… · 11s", with its own pulsing dot) is now just the counter ("11s", "1m 05s"), inline on the header row to the right of the status and before the Stop control. It still appears after three seconds, turns amber once nothing has streamed for thirty, and is not shown while the card reads "Waiting for you". `SuperGroupingCard`'s `renderRunningMeta` slot keeps its signature; whatever a host returns is now placed on the header row (small, right-aligned) rather than on a line of its own, and only while the phase is `running`. Ungrouped threads (`groupToolCalls={false}`) and the per-tool-row counters are unchanged.
+
+Two related fixes in the grouped card: a tool whose only result so far is the backend's streaming placeholder (`artifact._tool_message_metadata.streaming === true` — task subagents, studio and Python execution, deep research) now stays a running step, so the header keeps naming the tool instead of flipping to "Preparing response" while it still runs (`isStreamingToolPlaceholder` is exported from `super-grouping`); and the thirty-second stall is announced to screen readers through a polite live region, while the ticking counter itself stays out of it.
+
 ## What's new in 0.28.0
 
 **The iframe auth bridge only listens to the page that frames your app, and that page can no longer point the SDK's token at another server.** When the SDK runs inside an iframe, `useParentBridge` takes `athena-auth` (a token) and `athena-config` (URLs) from the parent window. Before this release it took them from any window on any `*.athenaintel.com` origin, including the hosts that serve customer computer and application apps, and an `athena-config` could replace `backendBaseUrl` / `statewireSyncUrl` at any time. A page on one of those hosts could frame or open another app and make its SDK send its token to a server of its choosing. Now:
@@ -1047,6 +1387,40 @@ function App() {
 
 Set `linkClicks={{ interceptAthenaCitations: false }}` to keep Athena citation links opening in the browser while still letting your app observe all link clicks.
 
+### Opening assets the host's own way (`onOpenAsset`)
+
+A host with its own place for assets (a desktop app's tabs, a route of its own) passes `onOpenAsset`
+to `<AthenaProvider>`. While it is set, every request to open an asset goes to it before the SDK's
+asset panel:
+
+- a tool card's Open (and the open-asset link on a tool's card);
+- an Athena citation or asset link in a message, which the SDK then intercepts as it does with an
+  asset panel mounted (`isAssetPanelAvailable` is true); a modified click (⌘, Ctrl, Shift, Alt)
+  stays the browser's;
+- the auto-open after a tool created or touched an asset, marked `origin: 'auto'` (a person's open
+  is `origin: 'user'`).
+
+```tsx
+<AthenaProvider
+  config={config}
+  onOpenAsset={({ assetId, origin, reference, href }) => {
+    if (origin === 'auto') return; // handled: open nothing the person did not ask for
+    if (!canShowHere(assetId)) return false; // the asset panel (or the link's own navigation) takes it
+    openTab({ assetId, reference }); // `reference`: the citation's anchor and excerpt
+  }}
+>
+```
+
+The request carries the asset id, the name and coarse type the card or link knew, the citation
+target (`reference`, for `AthenaAssetEmbed`), and for a link its own address (`href`), so a host that
+opens it on the web keeps every parameter it carried. Return `false` to leave the request to the
+asset panel, or, with no panel mounted, to the link's own navigation; anything else (returning
+nothing included) means the host opened it. Hosts that do not pass `onOpenAsset` behave as before.
+
+`appendCitationReferenceParams({ params, reference })` writes a reference's place (its anchor and
+excerpt) into any URL's search params, the way `AthenaAssetEmbed` writes it into the embed URL; a
+host that opens a cited place in Athena on the web writes it into the Spaces link the same way.
+
 ## Standalone Asset Embeds
 
 Use `AthenaAssetEmbed` to render a native Athena asset without chat, thread history, tabs, or the SDK split-pane layout. It defaults to the editable, full native asset experience (`readOnly={false}` and `displayMode="full"`). The embed token and the current user must still have edit permission; otherwise Athena renders the asset read-only.
@@ -1093,6 +1467,22 @@ function AssetView() {
 }
 ```
 
+A host that mints its own embed links (`POST /api/embed/generate-token` from its own backend, so
+its credentials never reach the page) passes the link as `embedUrl`: the component frames that page
+and mints none itself. `onReady` says when the framed page has answered (its bridge's first
+message), which tells a page that is still loading from one that never arrived (a frame its
+`frame-ancestors` refused, a network failure). Other iframe attributes (`sandbox`,
+`referrerPolicy`, `allow`) pass through to the frame.
+
+```tsx
+<AthenaAssetEmbed
+  assetId={assetId}
+  embedUrl={embed.embedUrl}
+  sandbox="allow-scripts allow-same-origin allow-forms allow-popups"
+  onReady={() => setReady(true)}
+/>
+```
+
 When `onCitationClick` is provided, citation navigation is delegated to the host by default. Set `citationBehavior="browser"` to observe the event while preserving Athena's default new-tab navigation. Host mode requires `onCitationClick`; without a handler, the SDK safely falls back to browser navigation.
 
 `onCitationAction` handles actions initiated from a citation popover. It currently receives `action: 'open-in-spaces'` when the user clicks the (+) button. Providing the handler delegates that action to the host by default. Set `citationActionBehavior="browser"` to observe the event while preserving Athena's default navigation; requesting host mode without a handler safely falls back to browser behavior.
@@ -1102,6 +1492,13 @@ Pass the callback's complete `reference` to the linked `AthenaAssetEmbed`, rathe
 the cited excerpt or rectangular region. Updating the reference also navigates when the host opens
 another citation in the same asset.
 
+`reference.anchor` may also be the anchor's raw query string, the form Athena links, citations and
+search results carry (`anchor=slide&slide_index=3&slide_id=…`, `anchor=time&time=0:42`,
+`anchor=pm_node&node_id=…`, or an asset ref such as `asset_x?anchor=cell&cell_id=…`). The embed
+receives its parameters as written, so it lands on any kind of place: a slide, a moment of a
+recording, an image region. A `meta.excerpt` with no anchor is forwarded too; the embed finds the
+passage by its words.
+
 If the host starts with an Athena citation URL/string instead of an
 `onCitationAction` event, parse it and pass the returned `reference` directly to the embed:
 
@@ -1201,6 +1598,26 @@ The `collab` entry hosts the Keryx-backed live surfaces: `useGenericDoc` /
 workspace presence feed below. Both mint short-lived room-bound tokens with the
 provider's credentials and re-mint before expiry on their own.
 
+`connectGenericDoc` also serves hosts that keep a **local copy** of the document
+(Midas, through `@athenaintel/local-copy`):
+
+- `localCopy.prepare({ doc, transport })` runs once, before the first mint: it
+  applies the stored copy to the document and returns the local edits an earlier
+  session never had acknowledged, which the handle sends and waits on like its
+  own. `handle.prepared` flips once it has run; mount readers after it.
+- `localCopy.transportChanged()` is called whenever the handle's unconfirmed
+  edits (`handle.unconfirmedEdits()`) or its sync state change.
+- `localCopy.beforeConnect({ grant, firstConnection, offlineForMs,
+  hasUnsyncedEdits })` is asked after each mint and before the connection it
+  would open: the first connection, a reconnect after an outage longer than
+  `offlineGateAfterMs` (default 15 s, past which the handle reconnects itself,
+  re-minting each time), and a re-mint after a revocation. `'hold'` keeps the
+  handle disconnected (`handle.held`) until `handle.resume()`.
+- A mint that fails for want of the network (`retryMintError`, default
+  `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'`.
+
 ### Workspace presence (admin only)
 
 `useWorkspacePresence(workspaceId)` is a **read-only** subscriber to the
@@ -1287,9 +1704,33 @@ For CSS-level theming without the `theme` prop, set the design-token custom prop
 }
 ```
 
+## Pop-out windows
+
+A host that shows SDK UI in a second browser window (the React tree stays in the main window while the DOM lives in the pop-out's document, as flexlayout pop-outs do) wraps that subtree in `OwnerDocumentProvider` with the pop-out's document. The SDK's popover, tooltip and composer mention menu then portal into that document's `body` instead of the main window's; with no provider (or the main document) they keep their default container.
+
+```tsx
+import { OwnerDocumentProvider } from '@athenaintel/react/owner-document';
+
+<OwnerDocumentProvider document={popoutWindow.document}>
+  <AthenaChat />
+</OwnerDocumentProvider>
+```
+
+Your own portals can read the same context: `usePortalContainer()` returns the pop-out's `body` (or `undefined` in the main window, so a library keeps its default), `useOwnerDocument()` the hosting document, and `useIsInPopoutDocument()` whether it is a pop-out. The same exports are on the root entry; `@athenaintel/react/owner-document` imports nothing else from the SDK, so a shell can provide the context without loading the chat. The pop-out document needs the SDK stylesheet too.
+
 ## Tool cards in the thread
 
-`<AthenaChat>` folds each turn's tool calls into one collapsible activity group with a count, the answer rendered below it (`groupToolCalls`, default `true`; pass `false` to list every tool card inline in call order). Every tool call it renders — the generic `ToolFallback`, the built-in tool UIs, nested sub-calls — shares one row anatomy: a status glyph (spinner / check / x / alert), the verb and its target on one line, a running call's elapsed seconds after three, a failed call tinted red, and a disclosure for the arguments and result.
+`<AthenaChat>` renders each turn as a transcript (`groupToolCalls`, default `true`; pass `false` to list every tool card inline in call order):
+
+- **The agent's sentences stay visible.** Every text part the agent writes before its last tool call ("I'll find your workstation, then check origin/staging.", "Started. Now I'll compare.") renders in the transcript, in order, as it streams. Only the work between two sentences folds: each run of tool calls and reasoning becomes one collapsed step row. The answer (the text after the last tool call) renders below, as before; no text renders twice.
+- **Each step says what it did.** A collapsed row names the step in progress, else the last one it took — "Ran `git log -1 origin/staging`", "Read `live_audio.py`", "Edited `upstream.py`" with "+4 −1", "Found 3 assets for "workstation"", "jevin-box is running", "Viewed pull request #43093", "Updated plan (3/7 done)" — with "+2 more" when the row folds several. Opening it lists every step, and "Show tool details" reveals that row's tool UIs.
+- **The header counts the turn.** "Working for 1m 12s" while it runs, "Worked for 2m 30s · Used 7 tools" once done (from the messages' own server stamps), "Waiting for you" on an approval. After thirty seconds without a streamed change the header adds "Nothing new for 42s" in amber.
+
+The transcript is `SuperGroupingTranscript` from `@athenaintel/react/super-grouping`; it takes the same renderer and host slots as `SuperGroupingCard` (which keeps the single-card layout for hosts that mount it). `splitTurnSegments`, `readTurnTiming` and `formatWorkDuration` are exported for hosts that lay a turn out themselves.
+
+Every step row and every thread tool card reads one summary registry, `summarizeToolCall({ toolName, args, result, status })` → `{ label, detail?, meta?, code? }` (also on `@athenaintel/react/tools`). It has rules for the deep agent's core tools (`execute`, the workspace file tools, `search_assets`, the computer and GitHub tools, web search and browse, `read_asset`, `write_todos`, `task`); other tools read the shared display registry, and a tool neither knows falls back to a host catalog name (`resolveToolDisplayName`), else its sentence-cased name. A call that targets a machine or document by id (`sandbox_asset_id`, `computer_asset_id`) is named by its title when an earlier result in the turn carried one (`collectAssetTitles`); nothing is fetched.
+
+Every tool call it renders — the generic `ToolFallback`, the built-in tool UIs, nested sub-calls — shares one row anatomy: a status glyph (spinner / check / x / alert), the verb and its target on one line, a running call's elapsed seconds after three, a failed call tinted red, and a disclosure for the arguments and result.
 
 That row is the `thread` appearance of `ToolFallback`. Hosts that render their own thread keep the boxed host card they render today (the default, `card`); to adopt the row, wrap the thread in the provider or set it per card:
 
@@ -1302,12 +1743,33 @@ import { ToolFallback, ToolFallbackAppearanceProvider } from '@athenaintel/react
 
 Dedicated tool UIs built on `ToolCard` follow the provider automatically; `useToolAppearance()` reads the appearance in force for a custom tool UI.
 
+## Spreadsheet range previews (`@athenaintel/react/sheet-range`)
+
+The sheet tool cards show a read-only preview of the range a tool read or wrote: column letters across the top, row numbers down the side, each cell on one line (its full text on hover), and the rows and columns left out counted under the table. The same pieces are on the `@athenaintel/react/sheet-range` entry (and the root entry) for a custom tool UI:
+
+```tsx
+import { RangePreviewTable, rangePreviewFromCellMap } from '@athenaintel/react/sheet-range';
+
+const preview = rangePreviewFromCellMap({
+  range: "'Q1 Plan'!A1:F40", // the A1 range the cells were read from
+  cells, // A1-keyed values: { A1: 'Region', B1: 1200, … }
+  formatCell: (value) => (value == null ? '' : String(value)),
+  maxRows: 20,
+});
+
+{preview && <RangePreviewTable preview={preview} maxRows={20} caption="Q1 Plan A1:F40" />}
+```
+
+`rangePreviewFromRows` previews rows of values written from an anchor cell instead. `parseA1Range` reads a cell (`B7`), a rectangle (`A1:C5`), whole columns (`A:C`) or whole rows (`3:5`), with an optional sheet prefix (`Sales!`, `'Q1 Plan'!`, `''` for a quote in a quoted name), `$` markers and any letter case, and returns `null` for anything else (a named range, a column past XFD, row 0). The entry imports nothing else from the SDK, so a shell can use it without loading the chat.
+
 ## Key Components
 
 - **`<AthenaProvider>`** — Runtime, auth, theming, and configuration
 - **`<AthenaChat>`** — Full chat UI with composer, messages, and tool rendering
-- **`<AthenaLayout>`** — Split-pane layout with asset panel
+- **`<AthenaLayout>`** — Split-pane layout with asset panel (or a `workbench` column)
+- **`<SessionWorkbench>`** — Devin-style workspace pane: Tasks, Shell, Computer, Pull requests, Attachments, and your own panes (see [Session workbench](#session-workbench))
 - **`<SessionList>`** — Session sidebar: attention, next action, pull-request chips, pin, search (see [Session list, attention and wake markers](#session-list-attention-and-wake-markers))
+- **`<SessionsPage>`** / **`<Inbox>`** / **`<InboxButton>`** — Full-page session list with server-side filters, display options and CSV export; the notifications inbox (see [Sessions page and inbox](#sessions-page-and-inbox))
 - **`<ThreadList>`** — Plain conversation history sidebar (title rows only)
 - **`Toolkits`** — Constants for all available backend toolkits
 
@@ -1347,6 +1809,13 @@ thread. `useComposerReady()` exposes the readiness for UI that wants to show a
 "loading" state; `composer.handoff` records each deferred, applied and dropped
 write.
 
+`useFocusComposer()` puts the caret at the end of the draft and leaves the draft
+as it is, for a host that shows the chat again and wants typing to land in it (a
+launcher window brought back by a shortcut). Asked before the editor has mounted,
+it focuses the editor as it mounts. `useReadComposerDraft()` returns a function
+that reads the draft's text when called, for a host that hands the chat to
+another window and carries the unsent text along.
+
 Use `useSendMessage()` for workflow buttons, sidebar shortcuts, and other UI that lives outside `<AthenaChat>` but still needs to submit a prompt. Its promise settles once the send has been dispatched, including a send that waited for the connection.
 
 ```tsx