@athenaintel/react 0.10.41-rc.2 → 0.11.0

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;
+};