@athenaintel/react 0.10.40 → 0.10.41-rc.1

package/README.md

@@ -50,12 +50,63 @@ function App() {
 </AthenaProvider>
 ```
 
-`config` accepts `apiKey`, `token`, `apiUrl`, `backendUrl`, `appUrl`, `trustedParentOrigins`, and `environment`. 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`, `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.
 
 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 (opt-in)
+
+The default chat transport is the legacy Iris `/api/chat` stream. Pass
+`transport: 'statewire'` to attach to the deep-agent statewire sync host
+instead — the thread is hosted server-side and replicated live, so history,
+reconnect, and run scheduling come from the server snapshot:
+
+```tsx
+<AthenaProvider config={{ environment: 'staging', transport: 'statewire' }}>
+  <AthenaChat />
+</AthenaProvider>
+```
+
+The sync endpoint defaults to the effective `apiUrl` host + `/v2/threads`
+(e.g. staging resolves to `https://iris.stg.athenaintel.com/v2/threads`, the
+same statewire base the mobile app and Chrome extension ship); pass
+`statewireSyncUrl` to override it for custom hosts whose sync mount lives on
+a different origin. If neither yields a URL (e.g. an unparseable custom
+`apiUrl`), the provider throws instead of falling back to an Athena default —
+credentials are never sent to a host you didn't configure. Auth reuses the
+provider's existing credential plumbing: tokens ride `Authorization: Bearer`
+and API keys ride `X-API-KEY`.
+
+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
+  `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.
+- **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.
+- **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: the `agent` prop is legacy-only (the statewire host
+always runs the Athena deep agent), and `model` defaults to the deep-agent
+default model in this mode.
+
 ## Authentication
 
 ### Same-origin SSO defaults

package/dist/chat/StatewireApprovalCard.d.ts

@@ -0,0 +1,2 @@
+import type { FC } from 'react';
+export declare const StatewireApprovalCard: FC;

package/dist/chat/StatewireClientToolBridge.d.ts

@@ -0,0 +1,14 @@
+import type { StatewireClientTool } from './statewire-client-tools';
+/**
+ * Executes the deep agent's frontend tool calls in statewire mode.
+ *
+ * Tools declared through `runConfig.custom.client_tools` have no backend
+ * implementation: a call parks the run and surfaces here as a statewire
+ * input request. The bridge runs the matching local handler and resumes the
+ * run with a per-call result envelope, so a missing tool or a thrown handler
+ * still frees the run with an error the model can act on instead of hanging.
+ */
+export declare function StatewireClientToolBridge({ tools, threadId, }: {
+    tools: readonly StatewireClientTool[];
+    threadId: string;
+}): null;

package/dist/chat/StatewireQueuedMessages.d.ts

@@ -0,0 +1,8 @@
+import { type FC } from 'react';
+/**
+ * Controls for the server-owned statewire queue and steer lanes: a message
+ * sent mid-run queues behind the active run; entries can be removed or
+ * steered in ("Send now"), and a stopped run can continue with its queue.
+ * Renders nothing on the legacy transport or when the queue is empty.
+ */
+export declare const StatewireQueuedMessages: FC;

package/dist/chat/statewire-approval.d.ts

@@ -0,0 +1,35 @@
+import type { StatewireThread } from '@assistant-ui/react-statewire';
+/** Human-in-the-loop approval payload the agora deep-agent runtime parks a run
+ *  on (shaped by `athena_deep_agent/hitl_bridge.py`). */
+export interface HitlApprovalPayload {
+    source: string;
+    type: string;
+    message: string;
+    context?: {
+        tool_name?: string;
+        tool_id?: string;
+        tool_args?: Record<string, unknown>;
+        pending_action_count?: number;
+    };
+}
+/**
+ * The statewire hooks read the nearest aui thread's extras and throw when
+ * those aren't statewire extras — which is the case on the SDK's legacy
+ * transport. Duck-type the pieces the approval card consumes so it can no-op
+ * on legacy threads instead of crashing.
+ */
+export declare function hasStatewireThreadExtras(extras: unknown): boolean;
+/** A parked interrupt that has not been answered yet. */
+export declare function isPendingInterrupt(request: StatewireThread.InputRequestState): request is StatewireThread.CustomInputRequest;
+/**
+ * A pending interrupt the approval card may answer. Client-tool parks are
+ * excluded — the client-tool bridge owns those, and a generic Continue resume
+ * would corrupt the parked tool call. The source check is deliberately loose
+ * (any payload stamped with the client-tool source) so a skewed deploy can
+ * never route one here.
+ */
+export declare function isApprovalCardInterrupt(request: StatewireThread.InputRequestState): request is StatewireThread.CustomInputRequest;
+/** Narrow an interrupt payload to the Athena HITL approval shape. */
+export declare function asHitlApproval(value: unknown): HitlApprovalPayload | null;
+/** Best-effort human-readable message from any interrupt payload. */
+export declare function readInterruptMessage(value: unknown): string;

package/dist/chat/statewire-banners.d.ts

@@ -0,0 +1,17 @@
+import type { FC } from 'react';
+/**
+ * Dismissible transport-error banner for statewire mode: send rejections,
+ * paywall refusals, and command failures that would otherwise vanish into
+ * the console after the composer already cleared. Renders nothing on the
+ * legacy transport.
+ */
+export declare const StatewireErrorBanner: FC;
+/**
+ * Degraded-connection strip: shown only while the statewire channel is
+ * reconnecting or gone, with a manual reconnect affordance when the
+ * transport exposes one. Healthy states render nothing.
+ */
+export declare const StatewireConnectionBanner: FC;
+/** Read-only notice for pre-cutover threads whose history lives under the
+ *  legacy runtime; the server fences dispatch into them. */
+export declare const StatewireLegacyReadOnlyBanner: FC;

package/dist/chat/statewire-client-tools.d.ts

@@ -0,0 +1,24 @@
+import type { Toolkit } from '@assistant-ui/react';
+/** A frontend tool the statewire client-tool bridge can execute locally. */
+export interface StatewireClientTool {
+    name: string;
+    description?: string;
+    /** JSON schema for the tool arguments. */
+    parameters: Record<string, unknown>;
+    handler: (args: Record<string, unknown>, context: {
+        toolCallId: string;
+    }) => Promise<unknown>;
+}
+/**
+ * Collect the client-executable tools from a frontend toolkit.
+ *
+ * The deep-agent runtime drops frontend (`ui_*`) tool definitions, so tools
+ * with a local `execute` must instead be declared through
+ * `runConfig.custom.client_tools` and answered by the statewire client-tool
+ * bridge. Schema conversion reuses `toToolsJSONSchema` — the same conversion
+ * the legacy assistant-transport applies — and a tool whose schema cannot be
+ * converted is skipped with a warning rather than failing the whole set.
+ */
+export declare function collectStatewireClientTools(toolkit: Toolkit): StatewireClientTool[];
+/** Wire entries for `runConfig.custom.client_tools`. */
+export declare function statewireClientToolWireEntries(tools: readonly StatewireClientTool[]): Record<string, unknown>[];

package/dist/chat/super-grouping/SuperGroupingCard.d.ts

@@ -20,7 +20,7 @@ export interface SuperGroupingCardProps {
     getToolGroupKey?: GetToolGroupKey;
 }
 /**
- * Ported from `olympus/src/components/copilotkit/sidebar/SuperGroupingCard.tsx`.
+ * Ported from `olympus/src/components/chat/sidebar/SuperGroupingCard.tsx`.
  *
  * Trimmed to drop Olympus-only deps:
  * - `useChatAllotmentStore.isWaitingForUserInput` (Olympus allotment system) — dropped.