@athenaintel/react 0.57.1 → 0.59.0

package/README.md

@@ -30,6 +30,15 @@ with `scripts/computer-starter-lockfiles.ts --react <version>`; their
 release-age gate. The qualification steps and gate removal condition are
 in the [coordinated release runbook](../../docs/runbooks/coordinated-client-releases.md#public-native-context-publication-gate).
 
+SDK 0.59.0 moves to statewire 0.27 and Athena's 2026-11-04 command contract:
+every message is one `run/send`, on wire 2026-11-01. Athena's hosts serve it
+from the release that added `run/send` (agora on Python statewire 0.23.1,
+Athena's managed cloud since November 8, 2026), and an older host cannot serve
+a 0.59.0 chat: a customer deployment upgrades its own Athena before moving its
+apps to 0.59.0 (see [What's new in 0.59.0](#whats-new-in-0590)). 0.58.0, which
+first offered wire 2026-11-01, was tagged but never published; 0.59.0 carries
+it.
+
 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**
@@ -212,10 +221,162 @@ never changes these props after the first send writes nothing. The
 For a collab agent whose author restricts it to its own models, see
 [Offering an agent's own models](#offering-an-agents-own-models).
 
+**A session's own agent.** `agent` seeds a new session's agent on its first
+send; after that the session's server config names its agent for good
+(`collab_agent_id` is a key the config owns), whatever `agent` says. Read it
+with `useAthenaThreadAgent()` (inside `<AthenaProvider>`): `{ agentId,
+configured, ready }`, `agentId` the collab agent's asset id or `null` for the
+person's own Athena assistant; wait for `ready`, as with the model.
+
+**Grouping models by family.** Each `AthenaModelOption` of
+`useAthenaModelCatalog()` also carries its place in its family, as agora's
+model registry names it: `variantMode` (`STANDARD`, `THINKING`, `PRO`),
+`variantEffort` (`NONE`, `LOW`, `MEDIUM`, `HIGH`, `XHIGH`, `MAX`) and
+`variantServiceTier` (`STANDARD`, `FAST`), `null` where it names none. A picker
+can show one row per family (`familyId`) and an effort control instead of one
+row per model and effort.
+
+**Agents with who made them.** `useAthenaAgentDirectory()` lists the agents
+`useAthenaAgentCatalog()` lists, each with `createdBy` (agora's user id of the
+person who made it) and `updatedAt`, so a picker can put the person's own
+agents first. It is a query of its own (`AthenaAgentDirectory`); the catalog
+is unchanged.
+
 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").
 
+### Plan mode
+
+Plan mode is the agent's to-do plan: for multi-step work it writes the steps
+down (`write_todos`) and checks them off as it goes, which `AthenaChat` shows
+above the composer (`AthenaPlanStrip`). A thread plans unless its config
+excludes the `write_todos` tool or its `TodoListMiddleware`, which is what
+Athena on the web's Plan Mode switch does. Pass `planMode` to turn it off or
+back on:
+
+```tsx
+import { AthenaChat, AthenaProvider, ChatPlanModeToggle } from '@athenaintel/react';
+
+function Chat() {
+  const [planMode, setPlanMode] = useState(true);
+  return (
+    <AthenaProvider config={config} planMode={planMode}>
+      <AthenaChat
+        composer={{ toolbarStart: <ChatPlanModeToggle value={planMode} onChange={setPlanMode} /> }}
+      />
+    </AthenaProvider>
+  );
+}
+```
+
+- `planMode={false}` adds `write_todos` to the send's `excluded_tools` and
+  `TodoListMiddleware` to its `excluded_middleware`, after anything your
+  `extraRunConfig` excludes; `true` takes them out; omitting it sends neither.
+- As with `model`, changing it while a session is open applies to the next
+  turn: on a session with server config the SDK writes one `config/patch` of
+  the lists that change, computed from the session's own lists, so what
+  another client excluded stays excluded. The value a session is opened with
+  is never written. `useAthenaThreadPlanMode()` reads a session's own plan
+  mode (`{ planMode, configured, ready }`, as `useAthenaThreadModel` reads its
+  model); a refused write is a `statewire.config` diagnostics event with
+  `plan_mode` and its `config_keys`.
+- A collab agent whose author turned off its built-in tools never plans: a
+  run can only narrow what an agent may use.
+- `ChatPlanModeToggle` is the composer chip (a switch reading "Plan"),
+  controlled like the pickers.
+
+### Folding attach and `@` into a menu of your own
+
+A host that offers attaching and the `@` menu from a control of its own (a +
+menu, as Athena Desktop's composer has) turns the composer's own buttons off
+and runs them from a slot:
+
+```tsx
+import { AthenaChat, useAthenaComposerActions } from '@athenaintel/react';
+
+function AddMenu() {
+  const composer = useAthenaComposerActions();
+  return (
+    <MyMenu>
+      <MyItem disabled={composer?.needsConnectionReason != null} onSelect={() => composer?.openFilePicker()}>
+        Files…
+      </MyItem>
+      <MyItem onSelect={() => composer?.openMentionMenu()}>An asset or person</MyItem>
+    </MyMenu>
+  );
+}
+
+<AthenaChat composer={{ attachButton: false, mentionButton: false, toolbarStart: <AddMenu /> }} />;
+```
+
+- `attachButton: false` leaves the paperclip out; pasting and dropping files
+  still attach them. `openFilePicker()` opens the same picker the paperclip
+  does, and does nothing while `needsConnectionReason` is set.
+- `mentionButton: false` leaves the `@` button out; typing `@` still opens the
+  menu, and so does `openMentionMenu()`.
+- `useAthenaComposerActions()` is `null` outside a composer slot. Both default
+  to `true`: a host that sets neither sees no change.
+
+### Composer slash commands
+
+`AthenaChat`'s `composer.slashCommands` (and `TiptapComposer`'s
+`slashCommands`) give the composer a `/` menu of your own commands. Typing `/`
+at the start of the draft or after a space lists them, narrowed by what
+follows (a command's label, `name` or `aliases`). Arrows move through the
+list, and Enter, Tab or a click runs the selected command. Escape closes it.
+Enter sends nothing while the menu lists a command. A command that declares
+`args` (what it takes, as the menu shows it) gets the text typed after its
+name; any other command drops out of the menu once more words follow its name,
+so a message that starts with a command's word is sent as typed:
+
+```tsx
+import { ListChecksIcon, MessageSquarePlusIcon } from 'lucide-react';
+import type { ComposerSlashCommand } from '@athenaintel/react';
+
+const commands: ComposerSlashCommand[] = [
+  {
+    name: 'new',
+    label: 'New chat',
+    description: 'Start a new conversation',
+    aliases: ['clear'],
+    icon: MessageSquarePlusIcon,
+    group: 'Chat',
+    run: () => startNewChat(),
+  },
+  {
+    name: planMode ? 'plan-off' : 'plan-on',
+    label: planMode ? 'Turn plan mode off' : 'Turn plan mode on',
+    description: 'The to-do plan for multi-step work',
+    aliases: ['plan', planMode ? 'plan off' : 'plan on'],
+    icon: ListChecksIcon,
+    group: 'Chat',
+    run: () => setPlanMode(!planMode),
+  },
+  {
+    name: 'open',
+    label: 'Open a document',
+    description: 'Open the document a link names',
+    // `/open https://…` gives `args` "https://…".
+    args: 'a link',
+    run: ({ args }) => openDocument(args),
+  },
+];
+
+<AthenaChat composer={{ slashCommands: commands }} />;
+```
+
+- The typed `/name args` leaves the draft before `run` is called;
+  `insertText` puts text in its place, as typed.
+- A command with a `disabledReason` lists greyed with the reason and does not
+  run (a command that needs a connection, while there is none).
+- The list is read on every keystroke, so a command's label or
+  `disabledReason` can change while the menu is open. Without commands, `/` is
+  plain text.
+- A `run` that throws or rejects is reported as a `composer.slash_command`
+  diagnostics event (`slash_command_failed`); what the person should see is the
+  command's to say.
+
 ## Transport (statewire only, as of 0.18.0)
 
 The SDK speaks one chat transport: **statewire**. The provider attaches to the
@@ -258,7 +419,7 @@ What the statewire transport wires up in `AthenaChat`:
 
 - **Approvals (HITL):** when the backend parks a run on an approval-gated
   tool call, an approval card renders above the composer with Approve/Reject
-  (or Continue for a generic pause) and resumes the run through the statewire
+  (or Decline for a park it has no card for) and resumes the run through the statewire
   `run/input` command. Hosts that build their own thread UI should mount the
   exported `StatewireApprovalCard` themselves — without it an approval-gated
   run stays parked with no way to answer it. A lone call whose resolved
@@ -279,6 +440,34 @@ What the statewire transport wires up in `AthenaChat`:
   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).
+- **The agent's typed questions and approvals:** when a run parks on a typed
+  Athena interrupt, `AthenaChat` renders that kind's own card, the ones Athena
+  on the web shows, and answers with the resume shape its tool validates (a
+  host that mounts `StatewireApprovalCard` itself passes
+  `typedInterrupts={statewireTypedInterrupts}`, from
+  `@athenaintel/react/typed-interrupts`; without it a typed park keeps the
+  card's decline): the `ask` tool's questionnaire (one question
+  at a time, yes / no, one or several options, text, a comment on each, a
+  draft kept on agora), a file request (uploaded into Athena assets), a form
+  (from the resume model's JSON Schema), toolkits to turn on or off (with the
+  tool cap's headroom), a saved login to use, a project schedule, a wait, and
+  a tool-raised approval; any other `custom` park gets its schema's form. A
+  timed park counts down and stops its timer the first time the person
+  touches the card. Approving a typed approval (toolkits, a saved login, a
+  schedule, a tool-raised approval) goes through `confirmDecision` like any
+  approval, and agora holds it to a signed-in person: when it refuses an
+  answer, the card says why (for an app signed in with a key, where to answer
+  instead). Answering a question never asks. `isHandledElsewhere`, `readOnly`
+  and `onResumeRejected` apply to these cards too, and a host whose own cards
+  answer typed parks (Olympus) passes no `typedInterrupts` and never imports
+  that entry, so it bundles neither the SDK's cards nor its selector. The
+  cards load on the first typed park. For an approval UI of your own, the same
+  entry has `StatewireTypedInterruptCard`, which mounts them alone,
+  `useStatewireTypedInterrupt`, the engine behind them, `TypedInterruptCard`,
+  which renders one from an engine slice of your own, and the payload
+  contract's selector and parser (`isTypedInterruptRequest`,
+  `parseTypedInterruptPayload`); each kind's reader and resume are
+  `@athenaintel/agent-runtime/typed-interrupt-kinds`'.
 - **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.
@@ -474,6 +663,14 @@ Same visual language as `ThreadList` (Tailwind via `cn`, lucide icons), plus:
   frame instead of the loading scrim while the statewire attach lands
   (`useAthenaStatewireThreadList().prefetchThread(threadId)` for hosts
   drawing their own rows);
+- live rows, newest first: a session the signed-in user's conversation index
+  pushes (started in this tab, another tab, Slack…) shows the moment it is
+  pushed, before the list is read again; a session that becomes active moves
+  to the top; and a message sent from this chat moves its session to the top
+  as working the moment it is sent — a chat the server does not know yet as
+  a pending row titled with the message (`isPending: true` on its
+  `useAthenaStatewireThreadList().threads` entry, with no pin, rename or
+  archive), which the server's own row replaces within moments;
 - skeleton rows (indicator, title line, meta line) while the first page
   loads — including while no credential has resolved — and for a refresh
   that has no rows to keep; "No sessions yet." only after a settled empty
@@ -515,7 +712,8 @@ The provider asks for pull-request state by default in thread-list mode
 never shows the chips to spare the server the lookup). The pure rules behind
 the rows — `groupSessions`, `sessionIndicator`, `sessionSecondaryLine`,
 `pullRequestChip`, `orderedPullRequests`, `sessionOriginLabel` — are exported for hosts drawing their
-own rows; `useAthenaStatewireThreadList().setFavorited({ threadId,
+own rows, also alone as `@athenaintel/react/session-list-model`, which loads nothing else of the SDK;
+`useAthenaStatewireThreadList().setFavorited({ threadId,
 isFavorited })` is the toggle behind them.
 
 ### `useAthenaSessionAttention(threadId?)`
@@ -629,7 +827,13 @@ import { AthenaProvider, InboxButton, SessionsPage } from '@athenaintel/react';
   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).
+  (remembered per browser). `defaultHiddenColumns` (typed `SessionsColumnId[]`)
+  chooses which columns start hidden; every other column shows. The default is
+  `DEFAULT_HIDDEN_SESSIONS_COLUMNS` (Mode, Creator, Created). An app whose
+  sessions have no pull requests passes
+  `defaultHiddenColumns={[...DEFAULT_HIDDEN_SESSIONS_COLUMNS, 'pullRequests']}`.
+  The person can still show any column. Once they change the display, their
+  choice is remembered and replaces the host's default.
 - **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 /
@@ -711,6 +915,15 @@ body used to drop it. With `threadListAgentHome`, `home_agent_id` rides beside
 it, and the answer's `home_agent_applied` says whether the list holds the
 agent's conversations (absent on an older server: it does not).
 
+`firstPageUpdatedAt` says when the query's first page was last written (ms
+since the epoch; 0 before it has any). With `offlineHistory` the first page can
+be the copy the device kept, painted at once while agora is asked again: that
+copy carries its old stamp until agora answers, and a refresh that fails leaves
+the stamp as it was. A host that must act only on what agora said since it
+started (Athena Desktop's needs-you notifications) compares it with its own
+start time. `useConversationList` in `@athenaintel/agent-runtime` reports the
+same stamp.
+
 ## Session workbench
 
 A Devin-style workspace pane beside the chat for the active session: a tab
@@ -818,6 +1031,117 @@ registry entries (`SESSION_WORKBENCH_TASKS_PANE`, …), the data hooks
 (`deriveShellRows`, `filterShellRows`, `deriveTaskSteps`, `taskProgress`,
 `workspaceComputers`) are exported for hosts composing their own.
 
+## Suggested follow-up prompts
+
+`<AthenaChat followUpSuggestions />` suggests what the person might send next,
+as Codex's desktop app does after a turn. It is off by default, and while it is
+off nothing is requested.
+
+```tsx
+<AthenaChat followUpSuggestions={isCodingChat} />
+```
+
+- **When.** Once a run the person watched finishes with a reply, the chat asks
+  Athena once for that turn (`POST /api/chat/follow-up-suggestions`, with the
+  provider's token or API key, as every SDK request) and shows up to three
+  chips just above the composer. A run that was stopped, failed or is waiting
+  on the person gets none, and so does a conversation opened at rest. A
+  `readOnly` chat never shows them.
+- **A click fills the composer.** A chip puts its words in the composer, with
+  the caret after them. Nothing is sent. The chips go away once the person
+  types or sends, or a new run starts.
+- **What is sent.** The turn's last user message (its first 4,000 characters)
+  and the reply's text (its last 8,000) go with the conversation's thread id.
+  Athena reads nothing else of the conversation, answers only for one the
+  credential can read (404 otherwise), and charges the model call to that
+  conversation's token usage.
+- **Failures show nothing.** A refused or failed request (an
+  `AthenaSdkError`, code `follow_up_suggestions_failed`, or `auth_rejected`
+  for a 401 / 403), or an Athena that predates the route (404), leaves the
+  composer as it was. No error appears.
+
+## Attach objects to the next message
+
+`useAttachToChat()` hands the agent an object on screen ("Discuss this with
+the agent"): an Athena asset (optionally a place inside it), an ontology object
+or a web page. The composer shows each one as a removable chip, and the next
+message carries the references as structured data, never as text. Athena
+resolves each one on the server with the signed-in person's own permission
+before the agent is told about it.
+
+```tsx
+import { useAttachToChat } from '@athenaintel/react';
+
+function DiscussButton({ investor }: { investor: { id: string; name: string } }) {
+  const { attach } = useAttachToChat();
+  return (
+    <button
+      onClick={() =>
+        attach(
+          { referenced: 'ontology_object', id: investor.id, meta: { title: investor.name } },
+          { prompt: 'Draft an intro email to ', open: true },
+        )
+      }
+    >
+      Discuss
+    </button>
+  );
+}
+```
+
+`attach(reference, { prompt?, open? })` takes an `AthenaReference`, one of the
+reference standard's kinds (`@athenaintel/references`):
+
+| `referenced` | Shape | Read on the server through |
+|---|---|---|
+| `asset` | `{ id: 'asset_…', anchor?, meta?: { title?, assetType? } }`; `anchor` is the standard's (`{ type: 'page', page: 5 }`, `{ type: 'sheet_range', sheetId, range }`, …) | the asset permission check, then `read_asset` |
+| `ontology_object` | `{ id: 'asset_…', meta?: { title?, objectType? } }`: a v1 object or a Platform 2.0 object | the object gate (Platform 2.0) or the asset check and the ontology rule (v1), then `get_ontology_object` or `read_asset` |
+| `external_url` | `{ url: 'https://…', meta?: { title? } }` | the web reader's egress guard (`read_web_page`) |
+
+- **The chips.** `AthenaChat` shows them above the editor
+  (`ComposerAttachedReferences`), with the kind's icon, the label and an
+  anchored asset's place (`Q4 deck · p.5`). Each one has a remove button. A
+  sent message shows what it carried, read-only, above its bubble
+  (`MessageAttachedReferences`). A host that mounts `TiptapComposer` itself
+  can mount both, and spreads `useAttachedReferencesComposerProps(threadId)`
+  on the composer so its sends carry the references. A composer without them
+  never sends attachments.
+- **The send.** The references ride the message's own metadata
+  (`message.metadata.attachedReferences`), so a message that waits in the chat
+  outbox, is retried, or is posted again after a reload keeps its own. A
+  message needs words: chips with an empty draft send nothing. A message with
+  attachments sent while a run is live waits in the queue for its own turn
+  instead of joining the running one. Sending takes the chips off the composer.
+  They come back if the send does: a send Athena refuses and hands back to the
+  composer, or a held message's Cancel or Edit.
+- **What the agent sees.** For the turn the message starts, the agent is told
+  each attachment's kind, its id, its label, the title and type Athena read
+  with the person's permission, and the exact call that reads it. The label
+  (`meta.title`) is only what the chip shows. The agent is told it is the
+  app's text, unverified, and never the object's content. The agent reads the
+  object itself through the same gated tools as anything else. A later turn
+  does not repeat the list.
+- **Refusals.** An object the person can't open, one that doesn't exist, an
+  item in a connected source (SharePoint, Drive, …), a malformed id or URL,
+  and a kind Athena doesn't take yet all reach the agent as refusals with a
+  reason, never as content. A missing object and one the person can't open
+  get the same refusal. In a conversation with several people, an asset not
+  all of them can open is left out, and so is every ontology object.
+- **Results.** `attach` returns `{ attached: true, reference, duplicate }` or
+  `{ attached: false, reason }`, where `reason` is `invalid_reference` (not an
+  attachable reference), `too_many` (a message carries at most
+  `MAX_ATTACHED_REFERENCES`, 10) or `no_thread`. Attaching the same pointer
+  again (same kind and id, and the same anchor for an asset) keeps one chip
+  and updates its label. `detach(reference)`, `clear()` and `references` (the
+  pending list) complete the hook. The list is per conversation, kept in
+  memory for the page, and forgotten when someone else signs in.
+- **`prompt` and `open`.** `prompt` puts text in the composer, after the
+  draft, for the person to finish. Nothing is sent. `open` focuses the
+  composer with the caret at the end. A host whose chat can be hidden shows it
+  itself.
+- **Not yet:** a table row (a lakehouse or Kronos row, by key) waits for a
+  permission-checked row reader on the server (#54759).
+
 ## Chat voice in AthenaChat
 
 `AthenaChat` includes realtime voice alongside dictation where the deployment
@@ -954,7 +1278,35 @@ Sessions in Athena and transcript/grading calls are authorized as them. This
 works for workspace members and for external SSO viewers alike: the viewer
 credential minted by `/_athena/auth` is authorized for session creation and
 grading the same way it is for `/api/v0/sessions`, scoped to the viewer's own
-workspace. Anywhere else — standalone hosting, custom auth — pass
+workspace. Which credential each kind of viewer's app gets, and what each
+reaches: `marathon/MARATHON_SYSTEM.md` ("The credential each viewer's app is
+signed in with").
+
+Inside Olympus (the computer's Preview tab and the sidebar app page) the
+parent window answers the bridge with what agora mints for the frame; on the
+app's own URL `/_athena/auth` (and the SSO provider's `/api/sso/userinfo`)
+mints the same thing. The computer's creator gets a sign-in of their own; a
+workspace member who did not create the computer gets an asset-bound
+`member_viewer` credential (`athview_`, 30 minutes, bound to the computer, its
+workspace and the app port; the bridge renews it 5 minutes before expiry),
+never their full sign-in, because the app runs the computer owner's code. That
+credential reaches only what this SDK's identity read and voice client call:
+`GET /api/v0/me` (listing that workspace alone), voice session creation, the
+transcript download of a voice session this app started, and
+`agents/general/invoke` without tools, a knowledge base or an earlier thread
+(transcript grading). The voice agent gets a credential of its own for each
+call (it saves the call's turns and runs `ask_agent` without tools), so a
+member's call cannot enable `read_full_asset`, `search_assets` or
+`ask_agent` tools (`403`). Asset reads (`/api/v0/assets`, `/api/v0/tools/*`),
+any other session download, sharing and the chat routes (the thread list and
+the statewire chat transport) answer `403` for it, in the frame and on the
+app's own URL alike, so a chat app, or an app that needs those reads, stays
+signed out for a member who did not create the computer. See
+`docs/COMPUTER_ASSET_STANDARDS.md` ("App frame sign-in"). Nothing to change
+in your app: the credential arrives through the same `athena-auth` message and
+the same `/_athena/auth` body.
+
+Anywhere else — standalone hosting, custom auth — pass
 `createSession` and create the session from your own server (API key stays server-side):
 
 ```tsx
@@ -970,7 +1322,7 @@ it never falls back to a shared key.
 
 **After the call.** `voice.sessionId` is a regular Athena session asset:
 
-- Transcript: `GET /api/v0/sessions/{asset_id}/download?format=messages`
+- Transcript: `GET /api/v0/sessions/{asset_id}/download?export_format=messages`
 - Grading against a rubric: `POST /api/v0/agents/general/invoke` with
   `config.structured_output` (a JSON Schema) → typed `structured_output` in
   the response.
@@ -980,6 +1332,73 @@ 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.59.0
+
+**Every message is one `run/send`, and the chat needs an Athena that serves it.** The SDK moves to `statewire` 0.27.1 and `@assistant-ui/react-statewire` 0.35.1 (from 0.25.0 and 0.34.0) and speaks Athena's 2026-11-04 command contract. A new message goes as `run/send` with a behavior: `auto` from the composer (while a run is live, Athena decides whether the message joins the running turn, waits for a turn of its own, or stops the run for it), and `queue`, `steer` or `preempt` (Send now) from the queue tray. 0.58.0 sent `run/enqueue`, `run/steer`, `run/steer-live` and `run/prioritize`. The transport offers the 2026-11-04 contract only, on wire 2026-11-01. Athena's hosts serve it from the release that added `run/send` (agora on Python statewire 0.23.1, Athena's managed cloud since November 8, 2026); an older Athena cannot serve a 0.59.0 chat, so a customer deployment moves its own Athena first, then its apps. Messages an earlier SDK kept on the device are read back as the `run/send` each one meant, and session records stay inside `localStorage`'s quota.
+
+**Read and write Athena data as the signed-in person.** `useAthenaFetch`, `useAthenaGraphQL`, `useAthenaGraphQLMutation`, `useAthenaRest` and `useSemanticQuery` call agora's own routes with the provider's credential, and `useInvalidateAthenaQueries` reads them again (see [Reading and writing Athena data](#reading-and-writing-athena-data-useathenafetch-useathenagraphql-useathenarest-usesemanticquery)). `useAthenaMember` resolves a bundle member's name to the workspace's own asset; an Athena that predates the members route answers 404 (`member_not_found`).
+
+**Attach an object to the next message.** `useAttachToChat()` puts an Athena asset (or a place in it), an ontology object or a web page on the composer as a chip. The message carries it as structured data (`metadata.attachedReferences`), and Athena checks each one with the sender's own permission before the agent is told about it (see [Attach objects to the next message](#attach-objects-to-the-next-message)). An Athena that predates it keeps the references on the message and tells the agent nothing.
+
+**Pickers and the composer.** `useAthenaThreadAgent()` reads a session's own agent. Each `useAthenaModelCatalog()` option carries its place in its model family (`variantMode`, `variantEffort`, `variantServiceTier`), and `useAthenaAgentDirectory()` lists agents with who made them. `composer.attachButton`, `composer.mentionButton` and `useAthenaComposerActions()` fold attaching and the `@` menu into a menu of the host's own.
+
+Also in this release:
+- `SessionsPage` takes `defaultHiddenColumns`; `DEFAULT_HIDDEN_SESSIONS_COLUMNS` (Mode, Creator, Created) is the default.
+- A step's long detail is cut short, so its label stays readable.
+- Someone other than a conversation's owner receives its tool calls as stubs; `AthenaChat` draws each one as a muted "Used a tool" chip instead of dropping it.
+- A 1:1 chat with a collab agent shows no answer label: only an agent other than the header's is labelled.
+- `connectGenericDoc` takes `diffedInitialSync` with `httpFirstOpen`, and an HTTP-first read whose bytes keep coming runs on; one that receives nothing for a minute is given up.
+- Everything 0.58.0 carries (below).
+
+## What's new in 0.58.0
+
+0.58.0 was tagged but never published to npm: everything below ships in 0.59.0.
+
+**The chat runs on statewire 0.25 and needs an Athena that serves wire 2026-11-01.** The SDK moves to `statewire` 0.25.0 and `@assistant-ui/react-statewire` 0.34.0 (from 0.21.0 and 0.31.0). Its transport offers wire 2026-11-01 only: the client always sends the attach's results cursor and stamps a command's sequence number once, as it leaves, which a 2026-09-30 attach refuses. Athena's hosts serve 2026-09-30 through 2026-11-01 from Python statewire 0.21.2 on (Athena's managed cloud since November 6, 2026); an older host cannot serve a 0.58.0 chat. A customer deployment moves its own Athena first, then its apps. The Athena application schema stays 2026-09-13, so messages an earlier SDK queued on the device are sent on the new wire unchanged. Stored sessions move to statewire 0.25's format the first time a conversation opens.
+
+**Messages typed while Athena can't be reached wait in their conversation's own session.** With `chatOutbox` on `AthenaProvider`, each conversation's statewire session now holds its waiting messages (statewire's outbox), instead of a store of the SDK's own. The session is sealed in IndexedDB with the key your `getKey('write')` returns, or kept in page memory when it returns `null` (the tray then says the device can't keep them). A conversation waits to connect until the provider has asked for that key. A conversation whose session from an earlier SDK still holds unsent messages in `localStorage` stays there until they are sent. Messages 0.53 kept on the device move into their conversation the next time it opens, and until then `countChatOutboxMessages`, `listChatOutboxMessages` and `clearChatOutbox` include them. A message shows "Not synced yet" only once it is stuck or the device is offline, not while an ordinary send is on its way (each listed message carries `queuedAt`).
+
+**A failed message shows once.** With a chat outbox, a send that failed is one "Couldn't send" row at the top of the queue tray (Retry, Edit, Discard), and `StatewireQueuedMessages` no longer lists it again in its failed lane. A message waiting for the countdown is never shown as failed. Hosts without `chatOutbox` keep the failed lane as before.
+
+**What changed in the API.** `AthenaChatOutbox.getKey` is typed `ChatSessionKeyProvider` (same shape: `(purpose: 'read' | 'write') => Promise<CryptoKey | null>`). `ChatSessionKeyPurpose` is exported, and `ChatOutboxKeyPurpose` stays as a deprecated alias of it. In `listChatOutboxMessages`, `sending` now means the message has left the outbox for its conversation (there is no claim lease anymore), and a failed message is Retry, Edit or Discard. `subscribeChatOutbox` calls its listener only when what waits changed. Nothing to change in your app unless you named the removed `@athenaintel/agent-runtime` chat outbox store exports yourself.
+
+**Waiting messages belong to one account.** Statewire 0.25 keeps every stored session under the account it belongs to (`user:<id>`), so on a shared browser one account's waiting messages are never sent or shown as another's. Sessions stored by an earlier SDK move under the signed-in account the first time it opens them; another account's stay where they are until that account signs in.
+
+**The agent's typed questions and approvals get their own cards.** A run parked on the `ask` tool's questionnaire, a file request, a form, a toolkit choice, a saved login, a project schedule, a wait or a tool-raised approval used to show only a Decline in the SDK chat, so the run stalled. `AthenaChat` now renders each kind's card as Athena on the web does and answers with the shape its tool validates (see **The agent's typed questions and approvals** under Transport). A host that mounts `StatewireApprovalCard` itself passes `typedInterrupts={statewireTypedInterrupts}` from `@athenaintel/react/typed-interrupts`.
+
+**Slash commands and plan mode in the composer.** `composer.slashCommands` gives the composer a `/` menu of the host's commands, and `planMode` on `AthenaProvider` turns the agent's to-do plan off or on for the next turn, with `ChatPlanModeToggle` as the composer chip and `useAthenaThreadPlanMode()` to read a session's own setting (see **Plan mode** and **Composer slash commands**).
+
+**The `@` menu offers people and agents.** `mentionCategories` adds `team` (the workspace's members and groups, as Olympus offers them) and `agents`: choosing an agent names it on the composer's To line, and each send names those agents to Athena on the message's own metadata (`addressedAgents`), which agora checks against each agent's VIEW gate (see **What the `@` menu offers: people and agents**).
+
+**Subagents run side by side.** A delegation's subagents render as lanes under one strip, each card with its status, plan progress and last call, and "View transcript" opens a lane in a drawer, as Spaces shows them. The pieces are on `@athenaintel/react/subagents` (see **Subagent lanes**).
+
+**Cards for Athena's toolkits.** `AthenaChat` draws the most-used toolkits' tools (the deep agent's sandbox and tasks, Drive, ontology, project manager, the studios, documents, decks, the browser, computers, email and calendar) with Athena on the web's cards, from `TOOL_UI_REGISTRY` (see **Cards for Athena's toolkits**). A coding chat's background commands read as what they did, not their tool ids.
+
+**Following what the agent makes.** `useAthenaAgentCreations({ onCreation })` reports each asset the agent creates or opens for the person in a conversation, once, as the call finishes, and the tool auto-open's `autoOpen` now says why (`kind`: `'created'`, `'shown'` or `'touched'`).
+
+**Finding assets, and uploading into a folder.** `useAthenaAssetSearch`, `useAthenaRecentAssets`, `useAthenaFavoriteAssets`, `useAthenaProjects`, `useAthenaFolderAssets` and `useAthenaProjectAssets` read what the signed-in person may open through agora's own gated queries, and `useAthenaAssetsRefresh()` reads them again. `useFileUpload().upload(files, { parentFolderId })` uploads into a folder the person may edit (see **Finding assets: a title search, recent work and favourites**).
+
+**Suggested follow-up prompts and a turn's changes card, both off by default.** `<AthenaChat followUpSuggestions />` offers up to three chips after a finished turn (`POST /api/chat/follow-up-suggestions`; an Athena that predates the route answers 404 and nothing shows), and `turnChanges` ends a turn that changed files with Codex's "Edited 5 files" card, read and acted on by the host (see **Suggested follow-up prompts** and **What a turn changed**). With neither turned on, nothing is requested.
+
+Also in this release:
+- `composer.onBeforeSend` (`AthenaChatBeforeSend`) runs host work before a draft goes, however it is sent; a rejection sends nothing and keeps the draft.
+- A composer toolbar too narrow for its chips wraps them onto another row, so the mic, voice and Send stay in reach.
+- A host that takes `onCitationAction` also gets each member a person opens in an embedded folder, project or collection, to open as an asset of its own.
+- The session-list rules are on `@athenaintel/react/session-list-model`, which loads nothing else of the SDK.
+- The collaboration client sends Keryx only its own awareness entry, never a collaborator's.
+- Everything 0.57.2 shipped from the 0.57.1 tree (the session list's pending rows, and how a run ended in `AthenaChat`).
+
+## What's new in 0.57.2
+
+**A message you send shows in the session list the moment you send it.** The list used to wait for the server: a new chat appeared only after the server listed it and the list read its page again (about 5 seconds on staging), and a session you wrote to again stayed where it was. Now, in `SessionList`, `ThreadList` and any list a host draws from `useAthenaStatewireThreadList().threads`:
+- **A new chat's row is at the top the moment its first message is sent**, titled with the message, until the server's own row (with its title) replaces it. The row carries `isPending: true` while the server does not know the chat yet; `SessionList` offers no pin, rename or archive on it.
+- **A session you write to again moves to the top**, as working, at once.
+- **A session started anywhere else** (another tab, Slack, email) shows as soon as the signed-in user's conversation index pushes it, without waiting for the list to be read again, and a session that becomes active moves up. The list stays newest first by `updatedAt`, the server's own order.
+
+Nothing to change in your app. It sends nothing new: the list reads the same endpoints, and a list without the live index (an API key with no signed-in user) reads its page again a few seconds after a message is sent to an existing session.
+
+**A follow-up you send before the agent answers no longer reads as a stopped run.** A second message sent before the agent says anything joins the first in one turn: the run ends silently and the agent answers both. `AthenaChat` drew that ending as "⏹️ Run stopped by user." although nobody stopped anything, and Send now did the same. `AthenaChat`'s assistant row now draws how a run ended as the other surfaces do: nothing for Send now and a double text, and the status card (`RuntimeMessageCard`: "Conversation stopped", "Paused by a server update", "Run failed" with the error) for a stop, a server-update pause or a failure, in place of the marker's transcript line.
+
 ## What's new in 0.57.1
 
 **Copy on a message from Slack, email, a text or Teams copies the words that were sent.** It used to copy the message's whole text, with the routing block the channel wrote for the agent ahead of the words. The user bubble's Copy, in `AthenaChat` and in chat-ui's `UserMessage`, now copies what the bubble shows: an email's subject, then the words; any other message copies as before. Hosts with their own user bubble get the same Copy from `useUserMessageCopy()` (`copy`, `disabled`, `isCopied`).
@@ -2118,6 +2537,47 @@ file with the lines highlighted: no embed renders a catalog. Agora's own citatio
 (`<a class="mention" data-type="pdf" data-id="asset_…" data-page-number=…>`) render as the same
 chips.
 
+### What the `@` menu offers: people and agents
+
+`AthenaChat`'s `@` menu offers the asset library by default (Favorites, Assets, Projects and
+Folders), plus Tools and Toolkits when `mentionTools` (or the provider's toolkits) offers any.
+`mentionCategories` picks the rest, and the menu lists them in Athena's order:
+
+```tsx
+<AthenaChat mentionCategories={['favorites', 'assets', 'projects', 'folders', 'team', 'agents']} />
+```
+
+- **`team`** — people, as Olympus's chat composer offers them: the workspace's members, then its
+  groups. An Athena admin's people come ranked, the people they talked to most recently first,
+  with the people they saved who are not members. They are read with the chat's own credentials
+  through the queries Olympus uses (`getUsersInWorkspace`, `getWorkspaceGroups`, and for an admin
+  `personMentionCandidates`); agora answers each for the signed-in person's own workspace only. A
+  person is the link Olympus writes, `[@Ada Lovelace](mention://person?id=ada@acme.com&email=ada@acme.com&name=Ada+Lovelace)`,
+  and a group `[@Finance](mention://group?id=group_…&name=Finance)`, a pointer to the group that
+  shares nothing and notifies nobody. Typing a name after `@` finds people beside assets.
+- **`agents`** — the agents a message can name (one conversation, many participants): the person's
+  own assistant ("Athena"), then the agents the chat's agent picker lists. Choosing one never writes
+  text: it names the agent on the composer's To line (`ComposerNamedAgents`, each chip with a
+  remove button), and the chips stay for every message until the person changes them. Each send
+  names them, in order, to Athena exactly as Olympus does: on the message's own metadata
+  (`addressedAgents`: `collab_agent:<asset id>`, or `assistant`), which agora reads ahead of the
+  run config. Each named agent answers the message in its own turn. A message names at
+  most eight. Agora checks every agent a message names (the agent's VIEW gate; a colleague's own
+  assistant is refused), so the menu only offers. While Olympus offers the section to Athena admins
+  only, so does `AthenaChat` (`CHAT_AGENT_NAMING_ADMIN_ONLY` in
+  `@athenaintel/agent-runtime/named-agents`, the module both run on). A message without chips names
+  what it always did: the provider's `agent`, or none, and Athena then runs the person's last agent
+  in that conversation, else their own assistant.
+- **`browse_profiles`** and **`drives`** — the asset types of those names.
+
+A message held in the chat outbox keeps the agents it names and goes out naming them; a failed send
+retried from the queue tray or by send recovery names the agents it was sent with; a refused send
+handed back to the composer brings its chips back.
+
+Hosts composing their own chat from `@athenaintel/react/chat-ui` pass `rootCategories` to
+`TiptapComposer` and, for Agents, a `chatAgents` binding (`MentionChatAgents`: what is offered,
+naming what is chosen, a subscription).
+
 ## Citation Links
 
 When you render chat inside `<AthenaLayout>`, Athena citation links (`app.athenaintel.com/dashboard/spaces?...`) now open the referenced asset in the SDK asset pane by default instead of navigating away.
@@ -2167,7 +2627,15 @@ asset panel:
   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'`).
+  is `origin: 'user'`). It says why it came in `autoOpen`: the tool, and what that tool did with
+  the asset (`kind`): `'created'` (a create tool, or a studio script's `Create*` sub-call),
+  `'shown'` (`open_asset_in_workspace`, the agent opening it for the person) or `'touched'` (a call
+  that read or changed an asset that was already there). A host that follows only what the agent
+  makes, as Athena's desktop app does, opens the first two. A call whose answer says it did not
+  happen (it failed, agora refused it, or agora told the agent it left the person's view alone)
+  raises none. These auto-opens ride each tool's `streamCall`, which the deep agent's runtime
+  (statewire) never runs; to follow what the agent makes there, use `useAthenaAgentCreations`
+  (below).
 
 ```tsx
 <AthenaProvider
@@ -2186,6 +2654,33 @@ opens it on the web keeps every parameter it carried. Return `false` to leave th
 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.
 
+To follow what the agent makes in a conversation, render `useAthenaAgentCreations` inside
+`AthenaChat` (a `composer` slot or a `components` override, where the conversation's state is
+read). It calls `onCreation` once for each asset the agent makes (a create tool, a studio
+script's `Create*` sub-call, a subagent's too) or opens for the person (`open_asset_in_workspace`),
+as the call finishes, with `{ key, assetId, type, autoOpen }`. It never reports the thread's
+history (what its first state holds, and older pages loaded in later), a call that failed or was
+refused, or a call that only read or changed an asset. Nothing is read while `enabled` is false.
+
+```tsx
+function FollowTheAgent() {
+  useAthenaAgentCreations({
+    onCreation: ({ assetId, type, autoOpen }) => openBehind({ assetId, type, madeBy: autoOpen.tool }),
+  });
+  return null;
+}
+
+<AthenaChat composer={{ aboveEditor: <FollowTheAgent /> }} />;
+```
+
+To show the places the agent points the person at (`highlight_in_asset`: "flash and scroll the
+user to a location inside an asset", with a tooltip), render `useAthenaAgentHighlights` the same
+way. It calls `onHighlight` once for each highlight as its call answers, with `{ key, assetId,
+assetRef, content, durationMs }`: `assetRef` is the asset id and its anchor query
+(`asset_x?anchor=pm_node&node_id=…`), `content` the tooltip or `null`, `durationMs` at most 30
+seconds. A highlight agora refused (an asset the person may not view) carries no place and is never
+reported, nor is the thread's history.
+
 `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.
@@ -2262,7 +2757,7 @@ message), which tells a page that is still loading from one that never arrived (
 
 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.
+`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. A host that takes the action also gets, as `open-in-spaces` with the member's reference and no place, each member that is not a container which the person opens in an embedded folder, project or collection, and opens it as an asset of its own; any other host sees the member open in place inside the embed.
 
 Pass the callback's complete `reference` to the linked `AthenaAssetEmbed`, rather than storing only
 `reference.id`. The embed uses the reference anchor to navigate PDFs to the cited page and highlight
@@ -2311,6 +2806,225 @@ text anchors, and positioned citations are also preserved by `parseAthenaCitatio
 `page_rect` may include `unit=percent` (the default) or `unit=point`; retain the unit so the region
 maps to the correct PDF coordinates.
 
+## Reading and writing Athena data: `useAthenaFetch`, `useAthenaGraphQL`, `useAthenaRest`, `useSemanticQuery`
+
+Generic hooks for calling agora's GraphQL and REST routes as the signed-in
+person, so an app does not write its own authenticated client. They add no
+server route of their own: agora checks every call against the person's
+access, as it does for Athena on the web. Use them inside `<AthenaProvider>`;
+no `QueryClientProvider` is needed.
+
+```tsx
+import {
+  useAthenaGraphQL,
+  useAthenaGraphQLMutation,
+  useAthenaRest,
+  useInvalidateAthenaQueries,
+  useSemanticQuery,
+} from '@athenaintel/react';
+
+const ASSET = `query Asset($id: String!) { asset(id: $id) { id title } }`;
+const RENAME = `mutation Rename($id: String!, $title: String!) { renameAsset(id: $id, title: $title) { id } }`;
+
+function AssetTitle({ id }: { id: string }) {
+  const asset = useAthenaGraphQL<{ asset: { id: string; title: string } }, { id: string }>(ASSET, { id });
+  const invalidate = useInvalidateAthenaQueries();
+  const rename = useAthenaGraphQLMutation<unknown, { id: string; title: string }>(RENAME, {
+    onSuccess: () => invalidate({ operationNames: ['Asset'] }),
+  });
+  if (asset.error) return <p>{asset.error.code === 'UNAUTHORIZED' ? 'No access' : asset.error.message}</p>;
+  return <h1 onDoubleClick={() => rename.mutate({ id, title: 'Renamed' })}>{asset.data?.asset.title}</h1>;
+}
+
+function RevenueByRegion({ modelId }: { modelId: string }) {
+  const me = useAthenaRest<{ user_id: string; workspace_id: string }>('/api/v0/me');
+  const revenue = useSemanticQuery({
+    semanticModelId: modelId,
+    query: { measures: ['orders.total_revenue'], dimensions: ['orders.region'], limit: 20 },
+  });
+  if (revenue.error) return <p>{revenue.error.message}</p>;
+  return <Table rows={revenue.data?.data ?? []} caption={`As ${me.data?.user_id ?? '…'}`} />;
+}
+```
+
+**The hooks:**
+
+- `useAthenaFetch()` returns an authenticated fetch bound to the provider.
+  `athenaFetch<T>(path, options?)` returns the route's body (JSON, or text).
+  `athenaFetch.graphql<TData, TVariables>(document, variables?, options?)` runs
+  one GraphQL operation and returns its `data`. `athenaFetch.raw(path, options?)`
+  returns the response itself, for a body you read yourself (a file). The
+  options are `method`, `params` (the query string), `json` or `body`,
+  `headers`, `signal`, `timeoutMs` and `rateLimitRetry`. `createAthenaFetch(config)`
+  is the same thing without React.
+- `useAthenaGraphQL<TData, TVariables, TSelected>(document, variables?, options?)`
+  reads with one GraphQL query: the one `operationName` names, or the
+  document's only operation. It refuses a mutation or subscription, which would
+  run again on every refetch.
+- `useAthenaGraphQLMutation<TData, TVariables>(document, options?)` writes, with
+  `mutate(variables)` / `mutateAsync(variables)`.
+- `useAthenaRest<TData, TSelected>(path, options?)` reads a JSON `GET` route.
+  Pass `null` as the path to keep it idle; `params` is part of the cache key.
+- `useSemanticQuery({ semanticModelId, query, ...options })` runs a metric
+  query on a semantic model through agora's public route,
+  `POST /api/v0/semantic-model/{id}/query`. Agora checks the person's access to
+  the model, and to its lakehouse sources, before the query runs.
+  `AthenaSemanticQuery` and `AthenaSemanticQueryResult` are that route's own
+  request and response types (`measures`, `dimensions`, `filters`,
+  `time_dimensions`, `order`, `limit` → `data`, `row_count`, `truncated`,
+  `data_as_of`…). Pass `null` as the model to keep it idle.
+- `useAthenaMember(name, { track? })` resolves a bundle member's name,
+  `support-desk/support_agent`, to this workspace's own asset (`asset_id`,
+  `type`, `link`, and with `track` the `revision` that track serves), through
+  agora's `GET /api/v0/bundles/{bundle_key}/members/{member_key}`. Name members
+  this way in code a bundle ships: each workspace or deployment holding a copy
+  answers with its own id, where a raw `asset_…` id names one place's asset only.
+  A name that doesn't resolve for the person (no such member, or one they can't
+  open: agora answers both alike) fails with `status` 404 and `code`
+  `member_not_found`. `resolveAthenaMember({ backendUrl, apiKey | token, name,
+  track? })` is the same read without React, throwing
+  `AthenaMemberNotFoundError`; `parseAthenaMemberName` and
+  `isAthenaMemberName` read the grammar.
+- `useInvalidateAthenaQueries()` returns a function that reads the current
+  person's data again. Narrow it by `operationNames`, REST `paths` (prefixes)
+  or `semanticModelIds`; with no filter, it reads everything again.
+
+A document is a string or a typed document string (graphql-codegen's client
+preset with `documentMode: 'string'`). With a typed document, `TData` and
+`TVariables` are inferred. The query hooks also take TanStack Query's options
+(`enabled`, `select`, `staleTime`, `refetchInterval`…), and the mutation hook
+takes its callbacks (`onSuccess`, `onError`, `onMutate`…).
+
+**Requests.** Every request goes to the provider's `backendUrl`, and only
+there: a path must start with `/`, so the person's credential never leaves for
+another host. It presents the token `getToken` resolves, renewed once after a
+401, or else the API key. It presents no other credential: an
+`Authorization`, `X-API-KEY`, `Cookie`, `Proxy-Authorization` or
+`X-Athena-View-As` header passed in `headers` is refused, in any letter case.
+
+- **429.** The SDK waits as agora's `Retry-After` (or `retryAfterSeconds`)
+  asks, up to 30 s, and sends again at most twice. A longer wait fails at once,
+  with `retryAfterMs` set. A write is sent again only when agora's per-user
+  limiter refused it (`RATE_LIMITED`), because that limiter refuses before
+  anything runs.
+- **Timeout.** Each attempt is abandoned after `timeoutMs`: 30 s by default,
+  90 s for a semantic query, since agora waits up to 60 s for the engine.
+
+**Errors.** Every failure is an `AthenaApiError` with these fields:
+
+- `kind`: `http`, `graphql`, `network`, `timeout`, `credential`, `response` or
+  `request`.
+- `status`: the HTTP status, or `0` when no answer came.
+- `code`: agora's code (`UNAUTHORIZED`, `BAD_USER_INPUT`, `RATE_LIMITED`…), from
+  the first GraphQL error's `extensions.code` or a REST error's `detail.code`.
+- `message`: agora's message.
+- `errors`, `detail`, `retryAfterMs`, `method` and `path`.
+
+A request you cancel rejects with the abort's reason, as `fetch` does.
+`isAthenaApiError` recognises the error across copies of the SDK.
+
+**Caching and retries.**
+
+- The query hooks run on the SDK's own `QueryClient`, one per provider, so
+  they never write into your app's cache.
+- Every key starts with the backend, the signed-in person, a fingerprint of the
+  credential (the API key's, and who the held token acts as and in which
+  workspace; never the secret) and the provider's credential scope epoch. The
+  epoch moves when a `getToken` token acts as another person or is scoped to
+  another workspace or org. A switch of person, key or workspace therefore
+  reads under new keys and never shows the previous identity's answers. A
+  renewal of the same person's token keeps the cache.
+- If your own `getToken` switches who is signed in, or their workspace, without
+  remounting the provider, the switch is seen when the next request resolves a
+  token. Remount the provider (`key={userId}`) to drop the previous person's
+  answers at once.
+- A write that switches the person's workspace on agora while the token stays
+  the same can't be seen in the keys. Call `useInvalidateAthenaQueries()()`
+  after it.
+- An answer stays fresh for 30 s (`staleTime`).
+- A 4xx, a GraphQL error, a timeout or an unreadable answer is never retried.
+  A failure with no answer, or a 5xx, is asked twice more, after
+  `Retry-After` when agora sends one.
+- A read is cancelled when the last component reading it unmounts.
+- A write is not cancelled on unmount, since agora may have applied it.
+  `timeoutMs` still bounds it.
+
+## Finding assets: a title search, recent work and favourites
+
+Three TanStack Query hooks find the assets the signed-in person may open, the way Athena on the
+web's ⌘K box and sidebar do. Each reads agora's `simpleSearch` (the query the composer's
+@-mentions send) with the provider's `backendUrl` and credentials, so a host adds no other path
+for its key or token, and agora answers only with assets the person may open, never a hidden or
+an archived one. They run on the host's `QueryClient` (the session list's under
+`enableThreadList`), keyed by the request and a fingerprint of the credential, so they wait while
+the host's `onlineManager` says Athena can't be reached, as the SDK's other reads do.
+
+- `useAthenaAssetSearch({ words, limit?, notTypes?, enabled? })`: the assets whose title holds
+  the words, the best match first (agora's `RELEVANCE` order; an agora that predates it answers
+  by the newest change). Blank words hold it idle.
+- `useAthenaRecentAssets({ limit?, enabled? })`: the person's recent work, as the web sidebar's
+  "Your Recents" lists it: what they created, the newest change first, without folders, emails,
+  conversations, catalogs or a meeting's own files. It waits for `/api/v0/me` (the read the chat
+  shares) to name the person.
+- `useAthenaFavoriteAssets({ limit?, notTypes?, enabled? })`: the person's favourites from every
+  folder, the newest change first.
+
+Each answers `AthenaAssetSummary[]` (`id`, `title`, `athenaOriginalType`, `athenaConvertedType`,
+`parentFolderId`, `updatedAt`, `isFavorited`…). `searchAthenaAssets` is the same read without
+React.
+
+```tsx
+import { useAthenaAssetSearch } from '@athenaintel/react';
+
+function OpenBox({ words }: { words: string }) {
+  const found = useAthenaAssetSearch({ words, limit: 8, notTypes: ['session', 'catalog'] });
+  return (
+    <ul>
+      {(found.data ?? []).map((asset) => (
+        <li key={asset.id}>{asset.title ?? 'Untitled'}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+For a tree of the person's files, `useAthenaProjects({ limit?, enabled? })` lists the projects they
+can open, the newest change first, and two reads page with TanStack's `useInfiniteQuery`
+(`fetchNextPage`, `hasNextPage`), each page `{ assets, next }`:
+
+- `useAthenaFolderAssets({ folderId, pageSize?, enabled? })`: a folder's children, or the
+  workspace's top level for `folderId: null` (agora's `getPaginatedAssetsForWorkspace`, gated by
+  the caller's access): folders first, then the newest change, without conversations or catalogs,
+  each asset once. agora appends a listed meeting's transcript and video and a listed catalog's
+  children to its page, wherever they are filed; those are left out, and the next page starts
+  after the folder's own rows.
+- `useAthenaProjectAssets({ projectId, pageSize?, enabled? })`: the assets a project links
+  (`getProjectLinkedAssetsPaginated`, which leaves out every asset the caller may not open).
+
+`useAthenaAssetsRefresh()` answers a function that has every asset read of the provider read again
+(the search, recent work, favourites, projects, and each folder's and project's pages), for the
+backend and credential in use alone: call it after changing the person's assets (an upload into a
+folder, say). Only the reads on screen are sent again.
+
+### Uploading into a folder
+
+`useFileUpload().upload(files, { parentFolderId })` uploads into that folder through agora's async
+upload (`POST /api/upload/async` with `parent_folder_id`), which refuses the whole upload, before
+it takes any file, unless the person may edit the folder, then reads its task (`asyncUploadTask`)
+until it ends (at most 15 minutes, waiting 250 ms to 2 s between reads). It answers the uploaded
+assets as the quick upload does; a refusal or a task that took no file throws with agora's reason.
+Without `parentFolderId` the files go to the workspace's root through `POST /api/upload/`, as
+before. Either way, `onFilesRefused` hears each file Athena refused (`{ fileName, error }`, in
+agora's words) when it took others from the same upload, before `upload` resolves:
+
+```ts
+const refused: UploadRefusal[] = [];
+const assets = await upload(files, {
+  parentFolderId: folderId,
+  onFilesRefused: (rejected) => refused.push(...rejected),
+});
+```
+
 ## Repository Code Search (platform staff only, managed cloud)
 
 `useAthenaRepoSearch` searches the workspace's indexed GitHub repositories
@@ -2548,7 +3262,17 @@ The transcript is `SuperGroupingTranscript` from `@athenaintel/react/super-group
 
 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`, and the UI Testing toolkit's `test_recording_start` / `_mark` / `_stop`); 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.
 
-A delegation to a subagent (`task`) stays in the conversation, as an email draft or a UI test report does: the subagent card, with its state, tool calls, clock and newest step, and its steps behind its disclosure (see [What's new in 0.42.0](#whats-new-in-0420)).
+A delegation to a subagent (`task`) stays in the conversation, as an email draft or a UI test report does: its lanes, drawn as Athena on the web draws them (see [Subagent lanes](#subagent-lanes)).
+
+### Subagent lanes
+
+`SubagentTaskToolUI` (`TOOL_UI_REGISTRY.task`) shows the subagents a turn delegated:
+
+- **A fan-out side by side.** The `task` calls one assistant message made together render as one group: the strip ("3 subagents in parallel · 1 running · 2 done · 41 tool calls · 1m 12s") with a progress bar, a fork connector to each card, and the cards in a grid as wide as the column allows. Above four lanes the group pages ("Page 1 of 2"). Only the first sibling's tool UI draws the group; the others draw nothing. A lone delegation is one card.
+- **Each card says where its lane is.** Its brief (which opens whole), its preset's type, its status and duration ("Running · 1m 04s", "Done · 2m 05s", the server's measure once it finished), and while it works, a ring of its own plan's progress, the call it made last, the thought it streams and, after 30 seconds without a change, "No activity for 42s". A finished lane shows the start of its report, a failed one why. Its footer counts its tool calls, plan steps and tokens. A lane parked on an approval reads "Waiting for approval" with the call it waits on, and no clock; a lane its run left before it settled (the run was stopped, or the conversation moved on) reads "Stopped".
+- **"View transcript" opens the lane in a drawer.** The lane's steps, laid out as the chat lays out a turn and rendered read-only with the chat's own tool UIs, live while it runs (the drawer follows the lane, so its card carries every step); "Showing the latest 8 of 42 steps" and "Load earlier steps" for a lane its card carries cut (`history/lane`, opened at the newest page); its images as they scroll into view; and its run details (status, type, model, dispatch id, duration, volume, tokens) for matching a failure with the backend's logs. Escape or the backdrop closes it; a tool UI that throws inside it stays inside it. Inside a lane, a delegation is a static chip.
+
+The pieces are on `@athenaintel/react/subagents` for a host that renders its own thread or its own `task` UI (Athena on the web does): `SubagentLaneGroup` (with `renderLaneApproval` for a host's own controls in a queued lane's card, `footer`, and `TranscriptDrawer`), `useTaskSubagentGroup`, `SubagentTranscriptDrawer` (with `renderTranscript`, `renderReport` and `onError`), the card's parts, what a lane says (`subagentLaneTitle`, `laneDurationLabel`, `formatLaneTokens`, …), and `DeepAgentLaneFollowScope`, the lanes a chat follows. `AthenaChat` mounts that scope, and its history edge keeps the attach following the lane an open drawer shows; a host with its own runtime mounts the scope and runs `useDeepAgentLaneFollowSync` itself.
 
 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.
 
@@ -2563,6 +3287,51 @@ 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.
 
+## What a turn changed (`turnChanges`)
+
+A host whose agent edits files (Athena Desktop, in a chat that works in a folder on the person's Mac) can end every finished turn that changed files with Codex's card: **Edited 5 files +164 −6**, **Undo** and **View changes**, then the first three files with their lines added and removed and **Show 2 more files** for the rest. An earlier turn keeps its own card with that turn's numbers. The SDK draws the card (in the SDK's theme, light and dark) and puts it at the end of the turn; the host reads the changes and does what Undo and View changes mean. Off unless the host turns it on: without `turnChanges` (or with `null`), or with `enabled` not `true`, nothing renders and nothing is read.
+
+```tsx
+import { AthenaChat, type AthenaChatTurnChanges } from '@athenaintel/react';
+
+const turnChanges: AthenaChatTurnChanges = {
+  enabled: true,
+  // 'chat' (the default): View changes opens every change in the chat; 'turn': this turn's alone.
+  reviewScope: 'turn',
+  read: async ({ threadId, turn, signal }) => myChanges({ threadId, runIds: turn.runIds, signal }),
+  onView: ({ threadId, turn, changes, scope }) => openMyReview({ threadId, ref: changes.ref, scope }),
+  onUndo: ({ threadId, changes }) => undoMyChanges({ threadId, ref: changes.ref }),
+};
+
+<AthenaChat turnChanges={turnChanges} />;
+```
+
+- **Which turns.** A turn is the assistant messages between two of the person's. It is read once it has finished (one the person wrote after, or the last one once its run is over), and only when its messages name their runs: Athena stamps `metadata.custom.athena_run_id` on every assistant message, the id the run's device calls carry, so a host that keeps something per run (the desktop app's checkpoint before a run's first change) finds the turn's. `turn` is `{ messageId, runIds }`, the runs oldest first (a turn resumed after an approval has more than one).
+- **What `read` answers.** `AthenaTurnChangesSummary`: `files` (`{ path, additions, deletions }`, `null` lines for a binary file), `more` (files changed past those listed), the total `additions` and `deletions`, and `ref`, the host's own handle on these changes, opaque to the SDK and handed back to `onView` and `onUndo`. `null`, no files or a rejection show nothing. Each turn is read once and kept (TanStack Query, per thread and turn, whether or not Athena can be reached); after `onUndo` settles the card reads its turn again.
+- **The buttons.** View changes calls `onView` with `scope` (`reviewScope`, `chat` unless the host says `turn`). Undo calls `onUndo` and is off until it settles; the host decides how to undo and whether to ask first (the desktop app's own dialog asks).
+- **A thread of your own.** The card renders in `AthenaChat`'s assistant turn. A host with its own `AssistantMessage` places `AthenaTurnChangesSlot` where the card goes; it reads `turnChanges` from `AthenaChat`.
+
+## Cards for Athena's toolkits
+
+`AthenaChat` draws the tools agents use most the way Athena on the web does, from `TOOL_UI_REGISTRY`, with nothing to pass in `toolUIs`. Each card reads only its own call (arguments, result, status, artifact); the one request any of them makes is for a fresh URL for a screenshot whose stored one has expired (`POST /api/asset/screenshot-presigned-url`, which signs only what the signed-in person may read).
+
+| Toolkit | Tools | What the card shows |
+|---|---|---|
+| Deep-agent sandbox | `execute`, `delete` | `$ ` and the command's first line with its `exit N` / `truncated` chips and the machine it ran on; opened, the command and its output in a terminal (cut at 400 lines). The deleted path and the sandbox's answer. |
+| Code interpreter and background tasks | `eval`, `start_async_task`, `check_async_task`, `update_async_task`, `cancel_async_task`, `ask_agent` | The code and its output. A coding task's status, summary, branch, commit, files, tests and blockers; an agent session's answer and a button that opens it. |
+| Athena Drive | `search_assets`, `list_contents`, `project_links` | The matches (type, title, creator, last update), each opening its asset; a folder's tree and page; the assets linked to a project. |
+| Ontology | `list_object_types`, `search_objects`, `get_object_links` | How many types, objects or links came back. |
+| Project manager | `pm_documents`, `get_pm_roadmap` | The project file read or patched (patches as before and after), and the roadmap. |
+| Spreadsheets | `execute_spreadsheet_code`, `query_sheet_range`, `capture_sheet_screenshot` | The run's phase, then its summary, code and output and an Open workbook button; the range read as a table (a batch lists each range); the captured range. |
+| Word documents | `execute_word_document_code`, `capture_page_screenshot` | The run's phase and result; the captured page. |
+| Athena documents | `replace_markdown_in_athena_document`, `insert_markdown_before_block`, `insert_markdown_after_block`, `delete_blocks_from_athena_document`, `clear_athena_document`, `convert_athena_doc_to_pdf` | What changed, with the written markdown as a preview; the PDF, which opens. |
+| Decks | `capture_slide_screenshots`, `manage_slides`, `set_slide_notes`, `update_slide_shapes` | The contact sheet with a chip per slide that opens it; each edit and the slide it touched. |
+| Hosted browser | `computer`, `browser_batch`, `go_to_url`, `get_page_text`, `get_current_url`, `create_new_browse_session`, `stop_browser_session` | Each action in words ("Did Left-Click", "Typed …", the zoomed region); a batch's steps; the browse session and its profiles, with Open session. |
+| Computers | `computer_asset_create`, `computer_asset_ensure_sandbox`, `computer_asset_get_status`, `computer_asset_deploy` | The machine's state, and a deployment's link and ports. |
+| Email and calendar | `send_email_from_athena`, `unified_email_get_thread`, `unified_email_get_message`, `unified_search_calendar_events` | The sent email's recipients, subject, files and opening lines; the thread as Gmail lists it; the events by day. |
+
+A card that opens an asset does it through the asset panel (`useAssetPanelStore().openAsset`), only when the person clicks. Each card is also exported by name (`ExecuteToolUI`, `SearchAssetsToolUI`, `QuerySheetRangeToolUI`, …) for a host that composes its own registry; a tool UI a host passes in `toolUIs` replaces the card for that tool.
+
 ## 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:
@@ -2580,7 +3349,7 @@ const preview = rangePreviewFromCellMap({
 {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.
+`rangePreviewFromRows` previews rows of values written from an anchor cell instead. `queryRangeItemTable({ item, data })` reads one range of a `query_sheet_range` result into the table the query card draws (values, formulas or formats, capped at `QUERY_RANGE_MAX_DISPLAY_ROWS` rows). `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