@athenaintel/react 0.17.0 → 0.19.0

package/README.md

@@ -50,37 +50,23 @@ function App() {
 </AthenaProvider>
 ```
 
-`config` accepts `apiKey`, `token`, `apiUrl`, `backendUrl`, `appUrl`, `trustedParentOrigins`, `environment`, `transport`, and `statewireSyncUrl`. Top-level `apiKey`, `token`, `apiUrl`, `backendUrl`, `appUrl`, and `environment` props remain supported as compatibility aliases, but `config` is now the preferred API.
+`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.
 
 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.
 
-## Statewire Transport (default as of 0.12.0)
+## Transport (statewire only, as of 0.18.0)
 
-Statewire is the default chat transport: the SDK attaches to the deep-agent
-statewire sync host, so the thread is hosted server-side and replicated live —
-history, reconnect, run scheduling, mid-run queueing, HITL approvals, and
-client tools (for recognized SDK hosts, e.g. computer-asset `app_id`s) all
-come from the server snapshot. Pass `transport: 'legacy'` to opt a deployment
-back onto the legacy Iris `/api/chat` stream:
+The SDK speaks one chat transport: **statewire**. The provider attaches to the
+deep-agent statewire sync host at `<statewireSyncUrl>/<threadId>`, so the
+thread is hosted server-side and replicated live — history, reconnect, run
+scheduling, mid-run queueing, HITL approvals, and client tools (for recognized
+SDK hosts, e.g. computer-asset `app_id`s) all come from the server snapshot.
 
-```tsx
-<AthenaProvider config={{ environment: 'staging', transport: 'legacy' }}>
-  <AthenaChat />
-</AthenaProvider>
-```
-
-**Migrating from ≤0.11.x (legacy default):**
-
-- Threads are transport-scoped: conversations created on the legacy transport
-  are read-only from statewire (and vice versa). Users keep their history but
-  continue in new threads.
-- The statewire runtime applies the deep-agent model default when no `model`
-  prop is set; pin `model` explicitly if you depended on the legacy default.
-- The `agent` prop's legacy agent names are not honored on statewire; use
-  `collab_agent:<id>` refs (with `transport: 'statewire'` semantics) or the
-  default agent.
+The legacy Iris `/api/chat` assistant-transport leg was deleted in 0.18.0
+along with the `transport` prop — there is nothing to opt back onto. See
+[Migrating from 0.17](#migrating-from-017).
 
 The sync endpoint resolves in this order: an explicit `statewireSyncUrl`; the
 `statewireSyncUrl` the host environment supplies (a Marathon-served computer
@@ -95,6 +81,11 @@ back to an Athena default — credentials are never sent to a host you didn't
 configure. Hosts that predate the minted statewire fields keep working through
 the `apiUrl` derivation. Auth reuses the provider's existing credential
 plumbing: tokens ride `Authorization: Bearer` and API keys ride `X-API-KEY`.
+A `getToken` resolver is called with `{ force: true }` right after the sync
+host refuses a credential, so a caching getter must mint a fresh token then;
+the persisted command lane is scoped to the signed-in user as well as the
+host, so a shared browser never resends one user's pending sends under the
+next user's token.
 
 What the statewire transport wires up in `AthenaChat`:
 
@@ -103,27 +94,171 @@ What the statewire transport wires up in `AthenaChat`:
   (or Continue for a generic pause) 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.
+  run stays parked with no way to answer it. Its `renderDetails`,
+  `isHandledElsewhere`, and `readOnly` seams take host-specific review UIs,
+  requests another surface answers, and viewers without edit rights; the
+  headless `useStatewireApprovalRequest` behind it is exported for hosts with
+  their own decision UI.
 - **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.
 - **Mid-run sends and the queue:** a message sent while a run is active
-  queues on the server. The queue panel above the composer lists queued
-  entries with remove and "Send now" (steer), plus Continue for a stopped
-  run's steer lane.
+  queues on the server. The queue panel above the composer
+  (`StatewireQueuedMessages`) lists queued entries with remove, "Send now"
+  (steer), Prioritize (`run/prioritize`), inline edit, and failed sends with
+  Retry/Discard, plus Continue for a stopped run's queue head; hosts can opt
+  into `autoContinue` for stranded queues and slot their own row renderer and
+  editor.
+- **Lean entries for hosts with their own composer:** `@athenaintel/react/chat-ui/statewire`
+  exports just the approval card, the queue tray, and the continue/run-ended
+  affordances (plus the runtime-message card and Continue pill they render),
+  and `@athenaintel/react/tools` exports the generic `ToolFallback` card with
+  its primitives (`ToolCard`, `ExpandableSection`, `NestedPtcMessages`) — so a
+  host that already ships its own composer and mention stack (Olympus) never
+  pulls the SDK's Tiptap graph into its build. Tool names, icons, categories,
+  and running copy come from the shared registry in
+  `@athenaintel/agent-runtime` (`getToolDisplayMeta`), and success/failure from
+  its `classifyToolResult`; the fallback takes host seams (`displayName`,
+  `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
+  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.
+- **Olympus consumes the package, not the source.** `@athenaintel/react` is a
+  workspace dependency of Olympus, resolved through this package's `exports`
+  to the built `dist/` (the guarded `prepare` script builds it on a cold
+  `bun install`; `olympus/scripts/prepare-react-sdk.ts` rebuilds it before
+  `bun run ts` when sources changed; `scripts/typecheck-all.ts` emits the
+  declarations before the repo typecheck). While editing the SDK against a
+  running Olympus, run `bun run dev` here so the dist follows your edits. The
+  Chrome extension and Office add-in still alias the entries to source.
 - **Errors and connection state:** transport errors (send rejections,
   paywall refusals) render as a dismissible banner; a degraded connection
-  shows a reconnect strip; a read-only pre-cutover thread shows a read-only
-  notice. Custom hosts can read all of it via `useAthenaStatewireLifecycle`.
-- **Thread list:** `enableThreadList` works with statewire. The list is the
-  same persisted Agora session list; switching threads re-attaches the
-  statewire session to the selected thread. `ThreadList` and
-  `useAthenaThreadManager` work in both modes.
-
-Remaining limitations: on statewire the `agent` prop only accepts
-`collab_agent:<asset_id>` refs (see below) — any other value is ignored,
-because the statewire host always runs the Athena deep agent. `model`
-defaults to the deep-agent default model unless a collab agent supplies one.
+  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`.
+- **Thread list:** `enableThreadList` provides the persisted Agora session
+  list; switching threads re-attaches the statewire session to the selected
+  thread. `ThreadList`, `useAthenaThreadManager`, and `useRefreshThreadList`
+  read that state (and render nothing / return `null` without it).
+
+The `agent` prop only accepts `collab_agent:<asset_id>` refs (see below),
+because the statewire host always runs the Athena deep agent. **Any other
+non-blank value throws at first render** — it is a misconfiguration, and a
+silently ignored selector would let a deployment answer as the wrong agent.
+`model` defaults to the deep-agent default model (`DEFAULT_STATEWIRE_MODEL`)
+unless a collab agent supplies one.
+
+## What's new in 0.19.0
+
+0.19.0 is a minor release with **no breaking changes**: every export that
+shipped in 0.18.0 is still exported under the same name from the same entry,
+and `<AthenaProvider>` / `<AthenaChat>` accept the same props. Bump the pin
+and re-install; there is nothing to migrate.
+
+- **Windowed history on every surface.** Each attach now declares a message
+  window (`ATHENA_SDK_MESSAGE_WINDOW`, 40 messages, sent as the
+  `x-athena-deep-agent-window` hello), so a long thread's first snapshot
+  carries the transcript's tail instead of every message. `<AthenaChat>`
+  mounts the new `StatewireHistoryEdge` row above the messages — "N earlier
+  messages", paged in as you scroll near the top (or on click) while the
+  reading position is kept — and cut tool outputs are fetched back for the
+  cards that show them. Hosts composing their own thread mount
+  `StatewireHistoryEdge` in `ChatThreadShell`'s `beforeMessages` slot (also
+  exported from `@athenaintel/react/chat-ui` and `/chat-ui/statewire`) and
+  read the tool-output store through `useStatewireToolOutputs`. Editing a
+  message below the loaded window resubmits with an anchored `run/edit`.
+- **One approval card, queue tray, and continue affordance.**
+  `StatewireApprovalCard` (`renderDetails`, `isHandledElsewhere`, `readOnly`),
+  `StatewireQueuedMessages` (`renderContent`, `renderEditor`, `autoContinue`,
+  `onEvent`), and the continue / run-ended affordances are the single
+  implementations Olympus, the Chrome extension, and the Office add-in mount;
+  the headless `useStatewireApprovalRequest` and `HITL_PENDING_RESUME_GRACE_MS`
+  are exported for hosts with their own decision UI. New lean entry:
+  `@athenaintel/react/chat-ui/statewire`.
+- **One tool display registry, result classifier, and fallback.**
+  `getToolDisplayMeta`, `classifyToolResult`, `isToolResultSuccess`,
+  `describeToolArgs`, `resultMessage`, `toolActiveLabel`, `toolCompletedLabel`
+  (re-exported from `@athenaintel/agent-runtime`), `TOOL_ICONS` / `toolIcon`,
+  the `ToolFallback` host seams (`ToolFallbackNotice`, `ToolFallbackOptions`,
+  `ToolFallbackContext`, …), `CopyToolSpecButton`, `InstallPackageToolUI`,
+  and `NestedPtcComponentsProvider` / `useNestedPtcComponents`. New lean
+  entry: `@athenaintel/react/tools`.
+- **Grouped activity card and timeline.** `SuperGroupingCard`,
+  `SuperGroupingFinalText`, `SuperGroupingProvider`, `CollapsibleGroup`,
+  `buildActivityTimeline`, `useActivityExpansion`,
+  `createToolBasedGroupingFunction`, `TOOLKIT_THEMES`, and their types are
+  exported; `<AthenaChat groupToolCalls>` renders through them. New lean
+  entry: `@athenaintel/react/super-grouping`.
+- **`rejected` is a first-class tool-result state.** A gated tool call the
+  user refused classifies as `{ state: 'rejected' }` (`ToolResultClassification`)
+  instead of an error, and reads as rejected on the tool card and in the
+  grouped timeline.
+- **Diagnostics instead of console noise.** Composer, tool-UI, and mention
+  failures now emit `composer.attachment.error`, `composer.cancel.error`,
+  `tools.schema.warning`, `tools.debug`, and `mentions.fetch.error` on the
+  diagnostics bus (`onDiagnostic` / `onError`, `__ATHENA_SDK__.diagnostics`)
+  rather than through `console.*`.
+- **`config.getToken` may be called with `{ force: true }`**
+  (`AthenaStatewireTokenGetter`) right after the statewire host refused the
+  previous credential; a getter that caches should mint a fresh token then.
+  Existing zero-argument getters keep working unchanged.
+- **Dependencies.** The assistant-ui family is pinned exactly on one release
+  train (`@assistant-ui/react` 0.15.17, `@assistant-ui/react-statewire`
+  0.24.0, `assistant-stream` 0.3.41, `statewire` 0.14.0); the SDK's internal
+  `zod` moved to v4 (it is not part of the public types).
+
+Moved, not renamed: `ToolCard`, `ExpandableSection`, `normalizeResult`,
+`truncate`, `formatToolName`, and `ToolStatus` now live in the tool
+primitives module and are exported from both `@athenaintel/react` (as before)
+and `@athenaintel/react/tools`.
+
+## Migrating from 0.17
+
+0.18.0 deletes the legacy assistant-transport leg. Every Athena chat client
+now speaks the native statewire wire, and the `TAG:JSON` transport over Iris
+`/api/chat` is being removed server-side, so the SDK no longer offers it.
+
+Removed from `<AthenaProvider>`:
+
+- `transport` prop and `config.transport` — statewire is the only lane.
+- `customToolConfigs` — it only ever reached the legacy leg (the deep-agent
+  runtime has no `custom_tool_configs` reader; MCP configuration is the parsed
+  `mcp_server_configs` key).
+- `agent` no longer accepts named agents (`athena_assist_agent`, …). The only
+  accepted shape is `collab_agent:<asset_id>`; anything else throws with a
+  message naming the prop and the accepted shape. Omit the prop to run the
+  Athena deep agent. Validate ahead of time with `resolveAgentProp({ agent })`.
+
+Removed exports:
+
+- `useAthenaRuntime`, `AthenaRuntimeConfig`, `DEFAULT_API_URL`,
+  `DEFAULT_BACKEND_URL` — use `useAthenaStatewireRuntime` /
+  `buildStatewireRunConfig` for a custom chat surface.
+- `ATHENA_TRANSPORTS`, `DEFAULT_ATHENA_TRANSPORT`, `resolveAthenaTransport`,
+  `allowsMidRunSend`, `AthenaTransport`, `ResolvedAthenaTransport`, and the
+  `transport` field on `AthenaConfig` (`useAthenaConfig()`).
+- `convertLangChainToThreadMessages`, `autoCloseInFlightSubgraphMessages`,
+  `PTC_SUBCALL_DID_NOT_COMPLETE_MESSAGE` — the LangChain message converter
+  existed only for the legacy wire.
+- `StatewireLegacyReadOnlyBanner` (rendered nothing since 0.17) and the
+  no-op `onLegacyReadOnly` option of `useAthenaStatewireRuntime`. The
+  residual `legacy_thread_read_only` 409 still surfaces through
+  `StatewireErrorBanner` / `useAthenaStatewireLifecycle`.
+- `useAthenaThreadListAdapter` (the assistant-ui remote-thread-list adapter).
+  `useRefreshThreadList`, `useAthenaThreadId`, and `AthenaThreadIdContext`
+  remain and read the statewire thread-list state.
+- Error codes `stream_failed` and `config_ignored`; diagnostics events
+  `stream.connected` and `stream.error`. `sdk.transport` still fires (always
+  `statewire`).
+
+Unchanged: `apiUrl`/`backendUrl` (explicit, host-minted, or from
+`environment`) — `apiUrl`'s origin still derives the statewire sync mount when
+`statewireSyncUrl` is not set, and `backendUrl` is still the Agora REST base
+for thread lists, uploads, and asset embeds.
 
 ## Collab Agents
 
@@ -133,7 +268,6 @@ the provider at one and the chat runs **as** that agent:
 
 ```tsx
 <AthenaProvider
-  transport="statewire"
   agent="collab_agent:asset_432af46f-293d-480b-a518-30b1f42a9ef7"
   channel="askbob_web"
 >
@@ -150,7 +284,10 @@ run the agent's base configuration.
 
 ### Requirements
 
-- **`transport="statewire"`.** The legacy transport ignores `collab_agent:` refs.
+- **The ref is the only accepted `agent` shape.** `collab_agent:<asset_id>`
+  selects the agent; omitting `agent` (or a blank string) runs the Athena deep
+  agent; any other value throws at render (`resolveAgentProp` is the same check,
+  exported for hosts that validate configuration up front).
 - **Publish the agent.** Resolution reads the *published* snapshot, not the
   live draft, so a channel that exists only in the editor is rejected with
   `collab_agent_channel_unknown`.
@@ -167,7 +304,6 @@ returns a plausible answer using your config instead of theirs.
 ```tsx
 // ❌ the agent's prompt, model, and tools are all discarded
 <AthenaProvider
-  transport="statewire"
   agent="collab_agent:asset_1234"
   model="claude-opus-4-6"
   systemPrompt="You are a helpful assistant."
@@ -175,7 +311,7 @@ returns a plausible answer using your config instead of theirs.
 />
 
 // ✅ the agent's own configuration wins
-<AthenaProvider transport="statewire" agent="collab_agent:asset_1234" />
+<AthenaProvider agent="collab_agent:asset_1234" />
 ```
 
 Pass them only when you deliberately want to override the agent — an explicit

package/dist/AthenaContext-B1QMhIP-.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"AthenaContext-B1QMhIP-.cjs","sources":["../src/provider/AthenaContext.ts"],"sourcesContent":["import { createContext, useContext } from 'react';\nimport type { AthenaTransport } from '../runtime/transport';\nimport type { AthenaProviderConfig } from './config';\nimport type { AthenaCitationLinkOptions, AthenaLinkClickOptions } from './citation-links';\n\nexport interface AthenaConfig extends Pick<AthenaProviderConfig, 'apiKey' | 'token'> {\n  backendUrl: string;\n  appUrl: string;\n  enabledToolkits: string[];\n  /** Effective chat transport — the lane the provider actually mounted (the\n   *  SDK defaults to 'statewire'; see `DEFAULT_ATHENA_TRANSPORT`). Optional\n   *  only so hand-built `AthenaConfig` literals keep compiling; capability\n   *  gates treat an absent value as the conservative legacy lane (e.g.\n   *  `allowsMidRunSend(undefined)` is false). */\n  transport?: AthenaTransport;\n  linkClicks?: AthenaLinkClickOptions;\n  citationLinks?: AthenaCitationLinkOptions;\n}\n\nexport const AthenaContext = createContext<AthenaConfig | null>(null);\n\nexport function useAthenaConfig(): AthenaConfig {\n  const ctx = useContext(AthenaContext);\n  if (!ctx) {\n    throw new Error('[AthenaSDK] useAthenaConfig must be used within <AthenaProvider>');\n  }\n  return ctx;\n}\n"],"names":["createContext","useContext"],"mappings":";;AAmBO,MAAM,gBAAgBA,MAAAA,cAAmC,IAAI;AAE7D,SAAS,kBAAgC;AAC9C,QAAM,MAAMC,MAAAA,WAAW,aAAa;AACpC,MAAI,CAAC,KAAK;AACR,UAAM,IAAI,MAAM,kEAAkE;AAAA,EACpF;AACA,SAAO;AACT;;;"}
+{"version":3,"file":"AthenaContext-B1QMhIP-.cjs","sources":["../src/provider/AthenaContext.ts"],"sourcesContent":["import { createContext, useContext } from 'react';\nimport type { AthenaProviderConfig } from './config';\nimport type { AthenaCitationLinkOptions, AthenaLinkClickOptions } from './citation-links';\n\nexport interface AthenaConfig extends Pick<AthenaProviderConfig, 'apiKey' | 'token'> {\n  backendUrl: string;\n  appUrl: string;\n  enabledToolkits: string[];\n  linkClicks?: AthenaLinkClickOptions;\n  citationLinks?: AthenaCitationLinkOptions;\n}\n\nexport const AthenaContext = createContext<AthenaConfig | null>(null);\n\nexport function useAthenaConfig(): AthenaConfig {\n  const ctx = useContext(AthenaContext);\n  if (!ctx) {\n    throw new Error('[AthenaSDK] useAthenaConfig must be used within <AthenaProvider>');\n  }\n  return ctx;\n}\n"],"names":["createContext","useContext"],"mappings":";;AAYO,MAAM,gBAAgBA,MAAAA,cAAmC,IAAI;AAE7D,SAAS,kBAAgC;AAC9C,QAAM,MAAMC,MAAAA,WAAW,aAAa;AACpC,MAAI,CAAC,KAAK;AACR,UAAM,IAAI,MAAM,kEAAkE;AAAA,EACpF;AACA,SAAO;AACT;;;"}

package/dist/AthenaContext-MOslgOmE.js.map

@@ -1 +1 @@
-{"version":3,"file":"AthenaContext-MOslgOmE.js","sources":["../src/provider/AthenaContext.ts"],"sourcesContent":["import { createContext, useContext } from 'react';\nimport type { AthenaTransport } from '../runtime/transport';\nimport type { AthenaProviderConfig } from './config';\nimport type { AthenaCitationLinkOptions, AthenaLinkClickOptions } from './citation-links';\n\nexport interface AthenaConfig extends Pick<AthenaProviderConfig, 'apiKey' | 'token'> {\n  backendUrl: string;\n  appUrl: string;\n  enabledToolkits: string[];\n  /** Effective chat transport — the lane the provider actually mounted (the\n   *  SDK defaults to 'statewire'; see `DEFAULT_ATHENA_TRANSPORT`). Optional\n   *  only so hand-built `AthenaConfig` literals keep compiling; capability\n   *  gates treat an absent value as the conservative legacy lane (e.g.\n   *  `allowsMidRunSend(undefined)` is false). */\n  transport?: AthenaTransport;\n  linkClicks?: AthenaLinkClickOptions;\n  citationLinks?: AthenaCitationLinkOptions;\n}\n\nexport const AthenaContext = createContext<AthenaConfig | null>(null);\n\nexport function useAthenaConfig(): AthenaConfig {\n  const ctx = useContext(AthenaContext);\n  if (!ctx) {\n    throw new Error('[AthenaSDK] useAthenaConfig must be used within <AthenaProvider>');\n  }\n  return ctx;\n}\n"],"names":[],"mappings":";AAmBO,MAAM,gBAAgB,cAAmC,IAAI;AAE7D,SAAS,kBAAgC;AAC9C,QAAM,MAAM,WAAW,aAAa;AACpC,MAAI,CAAC,KAAK;AACR,UAAM,IAAI,MAAM,kEAAkE;AAAA,EACpF;AACA,SAAO;AACT;"}
+{"version":3,"file":"AthenaContext-MOslgOmE.js","sources":["../src/provider/AthenaContext.ts"],"sourcesContent":["import { createContext, useContext } from 'react';\nimport type { AthenaProviderConfig } from './config';\nimport type { AthenaCitationLinkOptions, AthenaLinkClickOptions } from './citation-links';\n\nexport interface AthenaConfig extends Pick<AthenaProviderConfig, 'apiKey' | 'token'> {\n  backendUrl: string;\n  appUrl: string;\n  enabledToolkits: string[];\n  linkClicks?: AthenaLinkClickOptions;\n  citationLinks?: AthenaCitationLinkOptions;\n}\n\nexport const AthenaContext = createContext<AthenaConfig | null>(null);\n\nexport function useAthenaConfig(): AthenaConfig {\n  const ctx = useContext(AthenaContext);\n  if (!ctx) {\n    throw new Error('[AthenaSDK] useAthenaConfig must be used within <AthenaProvider>');\n  }\n  return ctx;\n}\n"],"names":[],"mappings":";AAYO,MAAM,gBAAgB,cAAmC,IAAI;AAE7D,SAAS,kBAAgC;AAC9C,QAAM,MAAM,WAAW,aAAa;AACpC,MAAI,CAAC,KAAK;AACR,UAAM,IAAI,MAAM,kEAAkE;AAAA,EACpF;AACA,SAAO;AACT;"}