@agentforge-io/chat-sdk 2.5.7 → 2.6.1

package/dist/entities.d.ts

@@ -171,6 +171,31 @@ export type ChatEvent = {
  | {
     type: 'conversation_started';
     conversationId: string;
+}
+/**
+ * Fired exactly once, the first time the session manages to start an
+ * ObserverAdapter (after the conversation id is known). Carries the
+ * resolved mode so integrators can log/diagnose their WebMCP bridge:
+ *   - `tool`/`window-events`/`hybrid` — WebMCP took over capture
+ *   - `dom-only` — fallback to native DOM listeners
+ *   - `none` — nothing landed (capture flags all off, or no DOM)
+ *
+ * Absent if the consumer didn't pass `observer` into ChatSessionOptions.
+ */
+ | {
+    type: 'observer_started';
+    mode: 'tool' | 'window-events' | 'hybrid' | 'dom-only' | 'none';
+}
+/**
+ * Fired when the server's daily-cap guard rejected a batch (HTTP 429
+ * with code `observer_throttled`). Per the SDD §8.5 we NEVER surface
+ * this to the end-user — it's purely informational for the embedding
+ * tenant so they can decide to raise their cap. `droppedEvents` is
+ * the size of the batch we couldn't flush.
+ */
+ | {
+    type: 'observer_throttled';
+    droppedEvents: number;
 } | {
     type: 'destroyed';
 };
@@ -208,4 +233,20 @@ export interface ChatSessionOptions {
      * session, the SDK silently falls back to a fresh conversation.
      */
     resumeConversationId?: string;
+    /**
+     * Optional DOM/WebMCP observer adapter. When passed, ChatSession:
+     *   1. Calls `observer.start({ sessionRef: conversationId, sessionKind: 'conversation' })`
+     *      as soon as the conversation id is known.
+     *   2. Drains the buffer on every `send()` and ships the events to
+     *      `POST /public/chat/:token/observer/events` alongside the message.
+     *   3. Flushes one last time via `navigator.sendBeacon` on `destroy()`
+     *      / page unload so tab-closes still ship their tail.
+     *   4. Calls `observer.stop()` on destroy.
+     *
+     * Type is `ObserverAdapterLike` — structurally compatible with the
+     * `ObserverAdapter` from `@agentforge-io/observer` but defined
+     * locally so the observer package is a TRUE optional dependency.
+     * Consumers who never set this don't need to install observer.
+     */
+    observer?: import('./observer').ObserverAdapterLike;
 }

package/dist/index.d.ts

@@ -11,3 +11,4 @@ export { ChatSession } from './session';
 export { HttpTransport } from './transport';
 export type { StreamEvent, ServerStreamChunk, TransportError, } from './transport';
 export type { ChatAgentSummary, ChatEvent, ChatMessage, ChatMessageMetadata, ChatRole, ChatSessionOptions, ChatSessionState, ChatSessionStatus, ChatTheme, } from './entities';
+export type { ObserverAdapterLike, ObserverEventLike, ObserverMode, } from './observer';

package/dist/observer.d.ts

@@ -0,0 +1,27 @@
+export interface ObserverEventLike {
+    type: 'click' | 'input' | 'change' | 'navigation' | 'scroll' | 'custom';
+    timestampMs: number;
+    url?: string;
+    targetSelector?: string;
+    label?: string;
+    payload?: Record<string, unknown>;
+    captureSource?: 'dom' | 'webmcp' | 'hybrid' | 'unknown';
+}
+export type ObserverMode = 'tool' | 'window-events' | 'hybrid' | 'dom-only' | 'none';
+export interface ObserverAdapterLike {
+    start(opts: {
+        sessionRef: string;
+        sessionKind: 'recording' | 'conversation';
+    }): Promise<{
+        active: boolean;
+        mode: ObserverMode;
+    }>;
+    drain(): ObserverEventLike[];
+    emit?(name: string, data?: unknown): void;
+    stop(): Promise<void>;
+    getStats?(): {
+        capturedEvents: number;
+        droppedEvents: number;
+        mode: ObserverMode | 'idle';
+    };
+}

package/dist/observer.js

@@ -0,0 +1,14 @@
+"use strict";
+// Structural contract for the @agentforge-io/observer ObserverAdapter.
+//
+// The chat-sdk consumes a duck-typed adapter so the observer package is
+// a truly OPTIONAL dependency. Consumers who never call `new
+// ObserverAdapter()` don't need to install or load it; consumers who do
+// pass an adapter into ChatSession see end-to-end typing because the
+// real ObserverAdapter satisfies this interface structurally.
+//
+// Keep this file in lockstep with @agentforge-io/observer's public
+// surface. The fields here are the ONLY surface the SDK touches at
+// runtime — narrowing the contract on purpose so an SDK bump doesn't
+// require re-publishing observer.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/react.d.ts

@@ -181,6 +181,22 @@ export interface ChatWidgetProps {
      * once `agent_loaded` has fired internally.
      */
     handleRef?: React.MutableRefObject<ChatWidgetHandle | null>;
+    /**
+     * Optional observer adapter. When supplied, the SDK boots it once the
+     * conversation id is known (first user message) and flushes captured
+     * DOM/WebMCP events to the AgentForge ingestion endpoint after every
+     * turn + on page unload. The adapter is a duck-typed contract — see
+     * `ObserverAdapterLike` — so the `@agentforge-io/observer` package
+     * stays an optional peer dep. Hosts that don't ship observer can
+     * omit this and chat behaves identically.
+     *
+     * Wire this from preview / playground pages where the operator
+     * wants to inspect what visitors do, or from production embeds
+     * where the agent's `observerEnabled` is true. The server-side
+     * agent config determines whether ingestion actually persists;
+     * the client-side adapter just captures.
+     */
+    observer?: import('./observer').ObserverAdapterLike;
 }
 /** Imperative surface exposed via ChatWidgetProps.handleRef. Narrow
  *  on purpose — hosts get a verb, not the whole session. */

package/dist/react.js

@@ -228,7 +228,7 @@ function fallbackCopy(ctx) {
  * SDK event. Consumers don't need to read `session.getState()` themselves.
  */
 function ChatWidget(props) {
-    const { token, apiBaseUrl, inline = false, position, browserSessionId, resumeConversationId, onConversationStart, stream, className, style, onApprovalDecision, readOnlyApprovals = false, variant = 'card', greeting, personaName, shortcuts, onShortcutClick, inputPlaceholder, members, composerLeftSlot, handleRef, } = props;
+    const { token, apiBaseUrl, inline = false, position, browserSessionId, resumeConversationId, onConversationStart, stream, className, style, onApprovalDecision, readOnlyApprovals = false, variant = 'card', greeting, personaName, shortcuts, onShortcutClick, inputPlaceholder, members, composerLeftSlot, handleRef, observer, } = props;
     // Build a lookup so MessageBubble can resolve actingAgentId → identity
     // in O(1) per render without re-walking the members array. Stable
     // identity per `members` prop change.
@@ -309,6 +309,12 @@ function ChatWidget(props) {
     // updates to it are ignored — the SDK already owns the live
     // conversation id internally via session.state.conversationId.
     const resumeRef = (0, react_1.useRef)(resumeConversationId);
+    // Same rationale as `resumeRef` above — the observer adapter is
+    // captured at mount so a parent re-render with a new (but equivalent)
+    // adapter identity doesn't tear down the live ChatSession mid-
+    // conversation. Hosts that need to swap observers should remount
+    // the widget (e.g. via a `key` prop).
+    const observerRef = (0, react_1.useRef)(observer);
     (0, react_1.useEffect)(() => {
         let cancelled = false;
         const s = new session_1.ChatSession({
@@ -317,6 +323,7 @@ function ChatWidget(props) {
             browserSessionId,
             resumeConversationId: resumeRef.current,
             stream,
+            observer: observerRef.current,
         });
         setSession(s);
         setMessages([]);

package/dist/session.d.ts

@@ -21,6 +21,14 @@ export declare class ChatSession {
     private readonly transport;
     private readonly stream;
     private readonly resumeId?;
+    /** Optional observer adapter — see ChatSessionOptions.observer. */
+    private readonly observer?;
+    /** Flips true after `observer.start()` resolves once, so subsequent
+     *  conversations (resume / restart) don't re-start the adapter. */
+    private observerStarted;
+    /** Page-unload handler installed when observer is active so we can
+     *  flush via sendBeacon before the tab closes. Removed in destroy(). */
+    private observerUnloadHandler?;
     private listeners;
     private state;
     private startPromise;
@@ -46,6 +54,19 @@ export declare class ChatSession {
     resolveApproval(approvalId: string, action: 'approve' | 'deny'): Promise<void>;
     /** Tear down. Future sends throw. Useful for SPA unmount. */
     destroy(): void;
+    /**
+     * Boot the observer adapter the first time we know the conversation
+     * id. Idempotent — subsequent calls (e.g. resumed conversations) no-op.
+     * Failures are swallowed: a broken observer must NOT break the chat.
+     */
+    private ensureObserverStarted;
+    /**
+     * Drain the observer buffer and POST it to the ingestion endpoint.
+     * Called inline after each send() and via sendBeacon on destroy /
+     * page-unload. Swallows errors per the SDD §8.5 "never bill-error"
+     * commitment.
+     */
+    private flushObserver;
     /**
      * Send a user message. Opens the conversation on first call. Returns the
      * final assistant content for callers that want to await it; the same

package/dist/session.js

@@ -20,6 +20,9 @@ const transport_1 = require("./transport");
  */
 class ChatSession {
     constructor(opts) {
+        /** Flips true after `observer.start()` resolves once, so subsequent
+         *  conversations (resume / restart) don't re-start the adapter. */
+        this.observerStarted = false;
         this.listeners = new Set();
         this.state = {
             status: 'idle',
@@ -39,6 +42,7 @@ class ChatSession {
         this.stream = opts.stream ?? true;
         this.browserSessionId = opts.browserSessionId ?? generateBrowserSessionId();
         this.resumeId = opts.resumeConversationId;
+        this.observer = opts.observer;
     }
     // ─── Subscriptions ──────────────────────────────────────────────────────
     /** Returns an unsubscribe function. Listeners are called synchronously. */
@@ -80,6 +84,11 @@ class ChatSession {
                     const history = await this.transport.getConversation(this.resumeId, this.browserSessionId);
                     if (history) {
                         this.state.conversationId = history.id;
+                        // Resume path: boot the observer the moment we know the
+                        // conv id, BEFORE replaying history. Otherwise the first
+                        // user click after page reload would go into a buffer with
+                        // no sessionRef and we'd lose its early events.
+                        await this.ensureObserverStarted(history.id);
                         for (const m of history.messages) {
                             // Replay each persisted message as if it had been streamed in
                             // — view layers already render `message_added` events.
@@ -148,11 +157,95 @@ class ChatSession {
     }
     /** Tear down. Future sends throw. Useful for SPA unmount. */
     destroy() {
+        // Flush observer first — drain() is cheap and the beacon path can
+        // ride out the unmount even when the rest of the session is gone.
+        this.flushObserver({ useBeacon: true }).catch(() => {
+            /* destroy must not throw */
+        });
+        if (this.observerUnloadHandler && typeof window !== 'undefined') {
+            window.removeEventListener('beforeunload', this.observerUnloadHandler);
+            window.removeEventListener('pagehide', this.observerUnloadHandler);
+            this.observerUnloadHandler = undefined;
+        }
+        if (this.observer) {
+            // Fire-and-forget — stop() is async but destroy is sync. Errors
+            // are swallowed: we're going away anyway.
+            this.observer.stop().catch(() => { });
+        }
         this.listeners.clear();
         this.emit({ type: 'destroyed' });
         // Drop everything — a destroyed session shouldn't be reused.
         this.state = { status: 'idle', messages: [] };
         this.startPromise = null;
+        this.observerStarted = false;
+    }
+    // ─── Observer wiring ────────────────────────────────────────────────────
+    /**
+     * Boot the observer adapter the first time we know the conversation
+     * id. Idempotent — subsequent calls (e.g. resumed conversations) no-op.
+     * Failures are swallowed: a broken observer must NOT break the chat.
+     */
+    async ensureObserverStarted(conversationId) {
+        if (!this.observer || this.observerStarted)
+            return;
+        try {
+            const result = await this.observer.start({
+                sessionRef: conversationId,
+                sessionKind: 'conversation',
+            });
+            this.observerStarted = true;
+            this.emit({ type: 'observer_started', mode: result.mode });
+            // Install the unload flush. We listen to BOTH beforeunload (still
+            // the most reliable in Chrome/Firefox) and pagehide (Safari
+            // doesn't fire beforeunload reliably). The handler fires once
+            // per page lifetime — either listener wins, the other is a
+            // no-op when the buffer is already empty.
+            if (typeof window !== 'undefined') {
+                this.observerUnloadHandler = () => {
+                    void this.flushObserver({ useBeacon: true });
+                };
+                window.addEventListener('beforeunload', this.observerUnloadHandler);
+                window.addEventListener('pagehide', this.observerUnloadHandler);
+            }
+        }
+        catch {
+            // Observer is best-effort. A broken adapter shouldn't surface.
+        }
+    }
+    /**
+     * Drain the observer buffer and POST it to the ingestion endpoint.
+     * Called inline after each send() and via sendBeacon on destroy /
+     * page-unload. Swallows errors per the SDD §8.5 "never bill-error"
+     * commitment.
+     */
+    async flushObserver(opts = {}) {
+        if (!this.observer || !this.observerStarted)
+            return;
+        const convId = this.state.conversationId;
+        if (!convId)
+            return;
+        let batch;
+        try {
+            batch = this.observer.drain();
+        }
+        catch {
+            return;
+        }
+        if (batch.length === 0)
+            return;
+        try {
+            const result = await this.transport.ingestObserverEvents(convId, batch, opts);
+            if (result.throttled) {
+                this.emit({
+                    type: 'observer_throttled',
+                    droppedEvents: result.dropped ?? 0,
+                });
+            }
+        }
+        catch {
+            // Server-side failure: drop the batch. Better than spamming a
+            // retry loop that delays the user's next chat turn.
+        }
     }
     // ─── User actions ───────────────────────────────────────────────────────
     /**
@@ -232,6 +325,11 @@ class ChatSession {
                 if (evt.kind === 'conversation') {
                     this.state.conversationId = evt.id;
                     this.emit({ type: 'conversation_started', conversationId: evt.id });
+                    // Now that we have a conv id, boot the observer adapter (if
+                    // the caller passed one). Awaited so the buffer doesn't start
+                    // ingesting events under a stale sessionRef — but errors are
+                    // swallowed inside ensureObserverStarted.
+                    await this.ensureObserverStarted(evt.id);
                     continue;
                 }
                 if (evt.kind === 'chunk') {
@@ -385,6 +483,10 @@ class ChatSession {
                 this.removeMessage(assistant.id);
             }
             this.setStatus('ready');
+            // Flush observer AFTER the turn lands. Doing it after instead of
+            // inline with the SSE keeps the captured timestamps closer to the
+            // turn boundary the operator will read in the timeline.
+            void this.flushObserver();
             return totalFull;
         }
         catch (err) {
@@ -421,12 +523,16 @@ class ChatSession {
                 const res = await this.transport.createConversation(text, this.browserSessionId);
                 this.state.conversationId = res.conversationId;
                 this.emit({ type: 'conversation_started', conversationId: res.conversationId });
+                await this.ensureObserverStarted(res.conversationId);
                 content = res.content;
             }
             assistant.content = content;
             assistant.isStreaming = false;
             this.updateMessage(assistant);
             this.setStatus('ready');
+            // Inline flush AFTER the message lands so the events ride along
+            // with it. Non-blocking: if the cap kicks in we drop silently.
+            void this.flushObserver();
             return content;
         }
         catch (err) {

package/dist/transport.d.ts

@@ -93,6 +93,25 @@ export declare class HttpTransport {
      */
     resolveApproval(approvalId: string, action: 'approve' | 'deny', browserSessionId: string): Promise<void>;
     endConversation(conversationId: string, browserSessionId: string): Promise<void>;
+    /**
+     * Ship a batch of captured observer events for the current
+     * conversation. The server responds 200 even when the daily cap is
+     * exhausted (`throttled: true`) — per SDD §8.5 we NEVER raise a
+     * billing-shaped error to the end-user. The session uses the
+     * `throttled` field to emit `observer_throttled` for the embedding
+     * tenant's telemetry.
+     *
+     * `useBeacon: true` switches to `navigator.sendBeacon` for the
+     * page-unload flush. Beacon sends are fire-and-forget — no response
+     * to inspect — so we return a default OK envelope.
+     */
+    ingestObserverEvents(conversationId: string, events: unknown[], opts?: {
+        useBeacon?: boolean;
+    }): Promise<{
+        accepted: number;
+        dropped?: number;
+        throttled?: boolean;
+    }>;
     /** Parse the server's SSE response body into typed events. */
     private readSse;
 }

package/dist/transport.js

@@ -142,6 +142,48 @@ class HttpTransport {
             throw makeTransportError(data?.message ?? `HTTP ${res.status}`, res.status, data?.error);
         }
     }
+    /**
+     * Ship a batch of captured observer events for the current
+     * conversation. The server responds 200 even when the daily cap is
+     * exhausted (`throttled: true`) — per SDD §8.5 we NEVER raise a
+     * billing-shaped error to the end-user. The session uses the
+     * `throttled` field to emit `observer_throttled` for the embedding
+     * tenant's telemetry.
+     *
+     * `useBeacon: true` switches to `navigator.sendBeacon` for the
+     * page-unload flush. Beacon sends are fire-and-forget — no response
+     * to inspect — so we return a default OK envelope.
+     */
+    async ingestObserverEvents(conversationId, events, opts = {}) {
+        const body = JSON.stringify({ conversationId, events });
+        if (opts.useBeacon && typeof navigator !== 'undefined' && navigator.sendBeacon) {
+            // Beacon is best-effort. Browsers cap the body at ~64kB; that's
+            // well above our flush limit (~200 events * a couple hundred
+            // bytes each).
+            const blob = new Blob([body], { type: 'application/json' });
+            navigator.sendBeacon(this.url('/observer/events'), blob);
+            return { accepted: events.length };
+        }
+        const res = await fetch(this.url('/observer/events'), {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body,
+            // We deliberately do NOT credentials: 'include' — the chat token
+            // in the URL is the only auth surface for the observer endpoint.
+        });
+        if (!res.ok) {
+            // The endpoint shouldn't fail in normal operation. If it does
+            // we silently swallow — the chat UX must keep working even when
+            // observer ingest is down.
+            return { accepted: 0, dropped: events.length };
+        }
+        const data = (await safeJson(res));
+        return {
+            accepted: data?.accepted ?? 0,
+            dropped: data?.dropped,
+            throttled: data?.throttled,
+        };
+    }
     /** Parse the server's SSE response body into typed events. */
     async *readSse(res) {
         if (!res.ok) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge-io/chat-sdk",
-  "version": "2.5.7",
+  "version": "2.6.1",
   "description": "Framework-free chat session SDK for AgentForge public chat tokens. Headless — no DOM. Drop into any frontend (React, Vue, Svelte, vanilla) and listen for events.",
   "license": "MIT",
   "main": "dist/index.js",