@athenaintel/react 0.10.41 → 0.11.1

package/README.md

@@ -103,9 +103,83 @@ What the statewire transport wires up in `AthenaChat`:
   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.
+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.
+
+## Collab Agents
+
+A **collab agent** is an agent configuration authored in Athena (prompt,
+model, toolkits, behavior) and addressed as `collab_agent:<asset_id>`. Point
+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"
+>
+  <AthenaChat />
+</AthenaProvider>
+```
+
+Copy the snippet with real ids from the agent's **Channels** tab in Athena.
+
+`channel` is optional. It selects a **channel override layer** — a built-in
+channel (`email`, `sms`, …) or a custom channel defined on that agent — so one
+agent can present different prompts, models, and tools per surface. Omit it to
+run the agent's base configuration.
+
+### Requirements
+
+- **`transport="statewire"`.** The legacy transport ignores `collab_agent:` refs.
+- **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`.
+- **The acting user needs VIEW access** to the agent asset (admins bypass).
+  Running as an agent exposes its prompt and tool policy, so the same gate that
+  governs opening the asset governs running it.
+
+### Do not also pass `model`, `systemPrompt`, or `tools`
+
+Request keys override the agent definition, so **anything you pass here
+silently replaces what the agent's author configured** — the run succeeds and
+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."
+  tools={['web_search_browse_toolkit']}
+/>
+
+// ✅ the agent's own configuration wins
+<AthenaProvider transport="statewire" agent="collab_agent:asset_1234" />
+```
+
+Pass them only when you deliberately want to override the agent — an explicit
+`model` is honoured as a caller override, with the agent's model as the default
+beneath it.
+
+### Failure codes
+
+A refused selection surfaces as an `AthenaSdkError` with
+`code: 'collab_agent_rejected'`; the specific reason below rides in the error's
+`detail`. Subscribe with `onError` (see
+[Debugging](#debugging-and-diagnostics)) rather than guessing from messages:
+
+| Code | Meaning |
+|---|---|
+| `collab_agent_not_found` | No such asset, or it is not a `collab_agent` |
+| `collab_agent_forbidden` | The acting user lacks VIEW on the asset |
+| `collab_agent_channel_unknown` | No such channel (the message lists the known ones) |
+| `collab_agent_channel_disabled` | The channel exists but is toggled off |
+| `collab_agent_channel_kind_mismatch` | A voice channel was selected for a text run |
+| `collab_agent_runs_disabled` | The deployment has the SDK seam turned off |
 
 ## Authentication
 
@@ -323,6 +397,52 @@ function WorkflowButton() {
 }
 ```
 
+## Debugging and Diagnostics
+
+The SDK emits structured diagnostic events — auth handshake, thread list,
+statewire attach, sends, errors — with timings. Nothing is logged by default;
+turn it on with the `debug` prop:
+
+```tsx
+<AthenaProvider
+  debug                        // or 'debug' | 'info' | { console: 'debug', posthog: true }
+  onDiagnostic={(event) => console.log(event.name, event.durationMs)}
+  onError={(error) => reportToSentry(error)}
+>
+```
+
+`onError` receives an `AthenaSdkError` with a stable `code`, a human `hint`,
+and the originating `status`/`detail` — match on `code`, never on message text:
+
+```tsx
+import { ATHENA_SDK_ERROR_CODES } from '@athenaintel/react';
+
+onError={(error) => {
+  if (error.code === ATHENA_SDK_ERROR_CODES.collab_agent_rejected) {
+    // the backend's granular reason rides in `detail`, e.g.
+    // 'collab_agent_channel_unknown' — whose message lists the known channels
+    console.warn(error.detail, error.hint);
+  }
+}}
+```
+
+Each provider registers its own consumer, so multiple mounted providers all
+receive every event; a callback that throws is caught and cannot break the chat.
+
+Without a rebuild, from the browser console:
+
+```js
+localStorage.setItem('athena:debug', 'debug');  // console echo on, survives reload
+__ATHENA_SDK__.diagnostics.snapshot();          // recent events + timings
+__ATHENA_SDK__.diagnostics.export();            // JSON, for attaching to a bug report
+```
+
+Credentials are redacted everywhere (buffer, console, PostHog): any key
+matching `token`, `secret`, `api[-_]?key`, `authorization`, `cookie`, or
+`password` is stripped before an event is recorded. Spans also emit
+`performance.mark`/`measure` entries prefixed `athena-sdk:`, so they show up on
+the browser Performance timeline.
+
 ## License
 
 Proprietary. For licensed enterprise customers only.

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

@@ -1,10 +1,16 @@
 import type { Toolkit } from '@assistant-ui/react';
-/** A frontend tool the statewire client-tool bridge can execute locally. */
+import { toJSONSchema } from 'assistant-stream';
+type StatewireToolParameters = ReturnType<typeof toJSONSchema>;
+interface StatewireClientToolWireEntry extends Record<string, unknown> {
+    name: string;
+    description: string;
+    parameters: StatewireToolParameters;
+    requires_write: false;
+}
 export interface StatewireClientTool {
     name: string;
     description?: string;
-    /** JSON schema for the tool arguments. */
-    parameters: Record<string, unknown>;
+    parameters: StatewireToolParameters;
     handler: (args: Record<string, unknown>, context: {
         toolCallId: string;
     }) => Promise<unknown>;
@@ -15,10 +21,11 @@ export interface StatewireClientTool {
  * 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.
+ * bridge. Schema conversion reuses `toJSONSchema` — the same conversion
+ * primitive as the legacy assistant-transport — 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>[];
+export declare function statewireClientToolWireEntries(tools: readonly StatewireClientTool[]): StatewireClientToolWireEntry[];
+export {};

package/dist/diagnostics/athena-diagnostics.d.ts

@@ -0,0 +1,138 @@
+/**
+ * SDK diagnostics: one structured event bus for everything the SDK does that
+ * can be slow or can fail — auth acquisition, thread-list fetches, statewire
+ * attach/snapshot/connection changes, sends, first tokens, and every error.
+ *
+ * Design:
+ * - Module-level singleton (one SDK, one bus), configured by `AthenaProvider`
+ *   from its `debug` / `onDiagnostic` / `onError` props. Nothing here runs
+ *   until something calls `emit`, and with defaults it costs a ring-buffer push.
+ * - Every event carries `t` (ms since page navigation start via
+ *   `performance.now()`) so the buffer reads as a waterfall. Timed spans use
+ *   `performance.mark` / `performance.measure` too, so the browser Performance
+ *   panel shows them as user timings without any extra tooling.
+ * - Console output is opt-in (`debug` prop or `localStorage['athena:debug']`),
+ *   prefixed `[AthenaSDK]`, and level-gated. Errors always reach `onError`.
+ * - PostHog forwarding (opt-in) sends the timing events as
+ *   `athena_sdk_<name>` with `duration_ms`, through the SDK's capture gate.
+ *
+ * Consumers read the buffer with `useAthenaDiagnostics()` or, in the browser
+ * console, `window.__ATHENA_SDK__.diagnostics.snapshot()`.
+ */
+import { AthenaSdkError } from './errors';
+export declare const ATHENA_DIAGNOSTIC_LEVELS: readonly ['debug', 'info', 'warn', 'error'];
+export type AthenaDiagnosticLevel = (typeof ATHENA_DIAGNOSTIC_LEVELS)[number];
+/**
+ * Event names. Dotted `area.event` so a consumer can filter by prefix. Names
+ * are part of the public contract: renaming one is a breaking change for
+ * dashboards, so add new ones instead of repurposing.
+ */
+export type AthenaDiagnosticEventName = 'sdk.init' | 'sdk.transport' | 'sdk.config.warning' | 'auth.bridge.start' | 'auth.bridge.ready' | 'auth.bridge.timeout' | 'auth.bridge.absent' | 'auth.bridge.error' | 'auth.token.acquired' | 'auth.token.refreshed' | 'auth.token.refresh_failed' | 'auth.token.stale' | 'auth.sso.userinfo.start' | 'auth.sso.userinfo.done' | 'auth.sso.userinfo.error' | 'threads.list.start' | 'threads.list.done' | 'threads.list.error' | 'threads.history.start' | 'threads.history.done' | 'threads.history.error' | 'statewire.attach.start' | 'statewire.snapshot' | 'statewire.connection' | 'statewire.parked' | 'statewire.error' | 'statewire.read_only' | 'run.send' | 'run.first_token' | 'run.done' | 'run.error' | 'stream.connected' | 'stream.error' | 'sdk.error';
+export interface AthenaDiagnosticEvent {
+    /** Monotonic sequence number within this page. */
+    seq: number;
+    /** `performance.now()` at emit time (ms since navigation start). */
+    t: number;
+    /** Wall-clock ISO timestamp, for exports. */
+    at: string;
+    name: AthenaDiagnosticEventName;
+    level: AthenaDiagnosticLevel;
+    /** Milliseconds for a completed span (set on `*.done` / `*.ready` / `run.first_token`). */
+    durationMs?: number;
+    /** Structured context. Never contains credentials — see `redact`. */
+    data?: Record<string, unknown>;
+    /** Present on error-level events. */
+    error?: AthenaSdkError;
+}
+export interface AthenaDiagnosticsConfig {
+    /** Minimum level echoed to the console. `false` disables console output. */
+    console: AthenaDiagnosticLevel | false;
+    /** Forward timing + error events to PostHog as `athena_sdk_*` events. */
+    posthog: boolean;
+    /** Receives every event (already redacted). */
+    onEvent?: (event: AthenaDiagnosticEvent) => void;
+    /** Receives every error-level event's `AthenaSdkError`. */
+    onError?: (error: AthenaSdkError, event: AthenaDiagnosticEvent) => void;
+    /** Ring-buffer capacity. */
+    bufferSize: number;
+}
+export interface AthenaDiagnosticsSnapshot {
+    sdkVersion: string;
+    config: Omit<AthenaDiagnosticsConfig, 'onEvent' | 'onError'>;
+    events: AthenaDiagnosticEvent[];
+    /** Latest value per gauge (connection status, transport, auth mode, …). */
+    gauges: Record<string, unknown>;
+    /** Named span durations, most recent per name (`auth.bridge`, `threads.list`, …). */
+    timings: Record<string, number>;
+}
+type Listener = (event: AthenaDiagnosticEvent) => void;
+declare class AthenaDiagnosticsBus {
+    private config;
+    private events;
+    private listeners;
+    private snapshotListeners;
+    private seq;
+    private gauges;
+    private timings;
+    private spans;
+    private cachedSnapshot;
+    configure(partial: Partial<AthenaDiagnosticsConfig>): void;
+    getConfig(): AthenaDiagnosticsConfig;
+    /** Effective console level: the configured one, or `localStorage['athena:debug']`. */
+    private consoleLevel;
+    emit(name: AthenaDiagnosticEventName, options?: {
+        level?: AthenaDiagnosticLevel;
+        data?: Record<string, unknown>;
+        durationMs?: number;
+        error?: unknown;
+    }): AthenaDiagnosticEvent;
+    /** Record an error-level event. Returns the normalized `AthenaSdkError`. */
+    error(name: AthenaDiagnosticEventName, error: unknown, fallback: {
+        code: AthenaSdkError['code'];
+        message: string;
+        hint?: string;
+    }, data?: Record<string, unknown>): AthenaSdkError;
+    /**
+     * Start a named span. Returns a function that ends it and emits `doneName`
+     * with `durationMs` (or `errorName` when passed an error). Also records a
+     * `performance.measure` so the span shows in the browser's Performance panel.
+     */
+    span(spanName: string, startName: AthenaDiagnosticEventName, data?: Record<string, unknown>): (doneName: AthenaDiagnosticEventName, doneOptions?: {
+        data?: Record<string, unknown>;
+        error?: unknown;
+    }) => number;
+    /** Set a gauge (latest-value metric): connection status, transport, auth mode. */
+    gauge(name: string, value: unknown): void;
+    subscribe(listener: Listener): () => void;
+    /**
+     * Additive consumer registration: every registered consumer receives every
+     * event (and every error), unlike the single `onEvent`/`onError` config
+     * slots which are last-writer-wins. `AthenaProvider` registers through this
+     * so two mounted providers never clobber each other's callbacks.
+     */
+    addConsumer(consumer: {
+        onEvent?: (event: AthenaDiagnosticEvent) => void;
+        onError?: (error: AthenaSdkError, event: AthenaDiagnosticEvent) => void;
+    }): () => void;
+    /** Subscribe to snapshot changes (for `useSyncExternalStore`). */
+    subscribeSnapshot(listener: () => void): () => void;
+    snapshot(): AthenaDiagnosticsSnapshot;
+    /** Copy-paste-able JSON of the current snapshot (errors serialized). */
+    export(): string;
+    clear(): void;
+    private invalidate;
+    private mark;
+    private measure;
+    private echoToConsole;
+    private forwardToPostHog;
+}
+export declare const athenaDiagnostics: AthenaDiagnosticsBus;
+/**
+ * Expose the bus on `window.__ATHENA_SDK__` so an integrator can inspect the
+ * waterfall from the console (`__ATHENA_SDK__.diagnostics.snapshot()`) or turn
+ * console echo on without a rebuild (`localStorage.setItem('athena:debug','debug')`).
+ */
+export declare function installAthenaDiagnosticsGlobal(): void;
+/** Normalize the provider's `debug` prop into a diagnostics config patch. */
+export declare function debugPropToDiagnosticsConfig(debug: boolean | AthenaDiagnosticLevel | Partial<AthenaDiagnosticsConfig> | undefined): Partial<AthenaDiagnosticsConfig>;
+export {};

package/dist/diagnostics/errors.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Typed SDK errors. Every failure the SDK surfaces to a consumer carries a
+ * stable `code` (matchable in code), a human `message`, and a `hint` — the
+ * one-line "what to do about it" that turns a silent failure into a debuggable
+ * one. Backend rejections keep their structured `{ status, detail }` payload.
+ */
+export declare const ATHENA_SDK_ERROR_CODES: {
+    /** No token and no API key resolved before a request had to be sent. */
+    readonly auth_missing: 'auth_missing';
+    /** The server refused the credential (401 / statewire `unauthorized` fin). */
+    readonly auth_rejected: 'auth_rejected';
+    /** `/_athena/auth` or the iframe bridge did not answer within the timeout. */
+    readonly auth_bridge_timeout: 'auth_bridge_timeout';
+    /** `/_athena/auth` answered with a non-404 error. */
+    readonly auth_bridge_failed: 'auth_bridge_failed';
+    /** The statewire sync URL could not be derived from the configuration. */
+    readonly config_invalid: 'config_invalid';
+    /** A prop was set that the active transport ignores (e.g. `agent` on statewire). */
+    readonly config_ignored: 'config_ignored';
+    /** The thread list request failed. */
+    readonly threads_list_failed: 'threads_list_failed';
+    /** Loading a thread's history failed. */
+    readonly thread_load_failed: 'thread_load_failed';
+    /** The statewire host rejected a command (structured `{status, detail}`). */
+    readonly statewire_rejected: 'statewire_rejected';
+    /** The statewire connection is gone and will not reconnect on its own. */
+    readonly statewire_gone: 'statewire_gone';
+    /** The legacy `/api/chat` stream failed. */
+    readonly stream_failed: 'stream_failed';
+    /** The selected collab agent / channel was refused by the backend. */
+    readonly collab_agent_rejected: 'collab_agent_rejected';
+    /** Anything else. */
+    readonly unknown: 'unknown';
+};
+export type AthenaSdkErrorCode = (typeof ATHENA_SDK_ERROR_CODES)[keyof typeof ATHENA_SDK_ERROR_CODES];
+export interface AthenaSdkErrorOptions {
+    code: AthenaSdkErrorCode;
+    message: string;
+    /** One line telling the integrator what to check or change. */
+    hint?: string;
+    /** HTTP-ish status when the failure came from a server. */
+    status?: number;
+    /** Structured server detail (e.g. `{ code, message }` from agora). */
+    detail?: unknown;
+    cause?: unknown;
+    /** Extra structured context safe to log (never credentials). */
+    context?: Record<string, unknown>;
+}
+export declare class AthenaSdkError extends Error {
+    readonly code: AthenaSdkErrorCode;
+    readonly hint: string | undefined;
+    readonly status: number | undefined;
+    readonly detail: unknown;
+    readonly context: Record<string, unknown>;
+    constructor(options: AthenaSdkErrorOptions);
+    /** A log/console-friendly one-liner: `[code] message — hint`. */
+    describe(): string;
+    toJSON(): Record<string, unknown>;
+}
+export declare function isAthenaSdkError(value: unknown): value is AthenaSdkError;
+/** Wrap any thrown value as an `AthenaSdkError` (idempotent for SDK errors). */
+export declare function toAthenaSdkError(value: unknown, fallback: Omit<AthenaSdkErrorOptions, 'cause'>): AthenaSdkError;
+/** Structured `{ code, message }` detail from an agora rejection, if present. */
+export declare function readRejectionDetail(detail: unknown): {
+    code: string | null;
+    message: string | null;
+};

package/dist/diagnostics/useAthenaDiagnostics.d.ts

@@ -0,0 +1,13 @@
+import { type AthenaDiagnosticsSnapshot } from './athena-diagnostics';
+/**
+ * Read the SDK diagnostics buffer reactively — events, gauges (connection
+ * status, transport, auth mode), and the latest span timings (time to auth,
+ * time to thread list, time to statewire snapshot, time to first token).
+ *
+ * Renders on every emitted event; mount it in a debug panel, not in the chat
+ * transcript.
+ */
+export declare function useAthenaDiagnostics(): AthenaDiagnosticsSnapshot & {
+    clear: () => void;
+    export: () => string;
+};