@invergent/website-widget 2.7.4 → 2.7.6

package/README.md

@@ -46,29 +46,57 @@ pnpm add @invergent/website-widget @ag-ui/client @ag-ui/core rxjs
 
 `@ag-ui/client`, `@ag-ui/core`, and `rxjs` are **peer dependencies** -- they likely already exist in your app's bundle (especially if you're using CopilotKit or another AG-UI consumer), so we don't duplicate them.
 
-### CDN / `<script>` tag
+### Drop-in widget (`<script>` tag)
 
-For plain HTML sites without a bundler, use the IIFE build from a CDN. It bundles AG-UI and RxJS:
+For plain HTML sites without a bundler, load the IIFE build from a CDN and
+call `mount()`. One call renders a complete, self-contained chat widget — a
+floating launcher button that opens a streaming chat panel, fully isolated in
+a Shadow DOM so it can't collide with your site's CSS. The bundle includes
+AG-UI, RxJS, and the UI:
 
 ```html
-<script src="https://cdn.surogates.com/widget/v1/surogates-widget.global.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@invergent/website-widget@2/dist/surogates-widget.global.js"></script>
 <script>
-  const agent = new SurogatesWidget.WebsiteAgent({
+  SurogatesWidget.mount({
     apiUrl: 'https://agent.acme.com',
     publishableKey: 'surg_wk_...',
+    // Optional appearance:
+    // title: 'Acme Support',
+    // accentColor: '#4f46e5',
+    // welcomeMessage: 'Hi! How can I help?',
+    // position: 'bottom-right',
   });
-
-  agent.subscribe({
-    onTextMessageContentEvent: ({ event }) => document.body.append(event.delta),
-    onRunFinishedEvent: () => console.log('done'),
-  });
-
-  agent.addMessage({ role: 'user', content: 'hello' });
-  agent.runAgent();
 </script>
 ```
 
-The IIFE exposes `WebsiteAgent`, `EventType`, `AbstractAgent`, the error classes, and the `Translator` on `window.SurogatesWidget`.
+`mount(config)` returns a `WidgetHandle` — `{ open(), close(), toggle(),
+destroy(), agent }` — for programmatic control.
+
+| Option | Type | Notes |
+|---|---|---|
+| `apiUrl` | string, required | Base URL of the Surogates API. |
+| `publishableKey` | string, required | `surg_wk_...` key. Safe to embed in browser JS. |
+| `title` | string | Header label. Defaults to the deployed agent's name. |
+| `accentColor` | string | Brand colour (hex) for the launcher/header/bubbles. |
+| `welcomeMessage` | string | Greeting shown before the first turn (Markdown). |
+| `position` | `'bottom-right'` \| `'bottom-left'` | Launcher corner. Default `bottom-right`. |
+| `target` | `HTMLElement` | Host element. Defaults to `document.body`. |
+| `inline` | boolean | Render the panel inline (no floating launcher). |
+| `openByDefault` | boolean | Open the panel on load. |
+
+The IIFE also exposes the headless `WebsiteAgent`, `EventType`,
+`AbstractAgent`, the error classes, and the `Translator` on
+`window.SurogatesWidget` for hosts that want to build their own UI.
+
+#### Bundler consumers
+
+If you build your own React/Vue app, import the headless client from the
+package root, or the self-mounting UI from the `./ui` subpath:
+
+```ts
+import { mount } from '@invergent/website-widget/ui';
+mount({ apiUrl: 'https://agent.acme.com', publishableKey: 'surg_wk_...' });
+```
 
 ## API
 
@@ -160,11 +188,15 @@ Measured on the current build:
 
 | Target | Raw | Gzipped |
 |---|---|---|
-| ESM (`dist/index.js`) | 21 KB | **6 KB** |
-| CJS (`dist/index.cjs`) | 22 KB | **6 KB** |
-| IIFE (`dist/surogates-widget.global.js`) | 285 KB | **66 KB** |
-
-The npm/ESM numbers exclude AG-UI, RxJS, and zod (peer deps). The IIFE bundles everything for script-tag users.
+| ESM headless (`dist/index.js` + chunk) | ~23 KB | **~6 KB** |
+| ESM widget UI (`dist/ui.js`) | 16 KB | **~5 KB** |
+| IIFE (`dist/surogates-widget.global.js`) | 178 KB | **~49 KB** |
+
+The npm headless numbers exclude AG-UI, RxJS, and zod (peer deps); the headless
+entry stays Preact-free. The `./ui` build bundles Preact (peers still external).
+The IIFE bundles everything (AG-UI + RxJS + Preact + UI) for script-tag users and
+is built with `platform: 'browser'` so transitive deps resolve to their
+Web-Crypto variants rather than Node's `require('crypto')`.
 
 ## Versioning
 

package/dist/agent-ia0JiKMG.d.cts

@@ -0,0 +1,174 @@
+import { AbstractAgent, AgentConfig, RunAgentInput, BaseEvent } from '@ag-ui/client';
+import { Observable } from 'rxjs';
+
+/**
+ * HTTP + SSE wire layer.
+ *
+ * Pure functions that talk to the website channel's three endpoints,
+ * isolated here so :class:`WebsiteAgentClient` can stay focused on
+ * state-machine orchestration.  All fetches use ``credentials:
+ * 'include'`` so the browser sends the HttpOnly session cookie that
+ * ``bootstrap`` set -- without it the message/SSE/end routes return
+ * 401 and the whole channel falls apart.
+ *
+ * SSE is handled by the native ``EventSource`` rather than a custom
+ * fetch-based parser because the native implementation is zero bytes,
+ * auto-reconnects on network drops, and respects browser-internal
+ * backoff heuristics.  The one thing it can't do is resume with a
+ * server-side cursor, so we manage the ``?after=N`` reopen logic
+ * explicitly in :class:`WebsiteAgentClient`.
+ */
+interface BootstrapResult {
+    sessionId: string;
+    csrfToken: string;
+    expiresAt: number;
+    agentName: string;
+}
+
+/**
+ * AG-UI ``AbstractAgent`` implementation for the Surogates public-website channel.
+ *
+ * A ``WebsiteAgent`` bridges the channel-specific HTTP protocol
+ * (publishable-key bootstrap, HttpOnly cookie, CSRF double-submit,
+ * ``/v1/website/sessions/{id}/events`` SSE) onto AG-UI's standard
+ * ``run()`` contract so any AG-UI-aware host app -- CopilotKit,
+ * custom chat UIs, LangGraph-style clients -- can talk to a Surogates
+ * backend with no custom glue beyond instantiation.
+ *
+ * Responsibilities
+ * ----------------
+ * * **Lazy bootstrap.**  The first ``runAgent`` call POSTs to
+ *   ``/v1/website/sessions`` to exchange the publishable key for a
+ *   session cookie + CSRF token; subsequent calls reuse them.  A cookie
+ *   expiry (HTTP 401) triggers a transparent re-bootstrap so the host
+ *   app never has to manage auth state.
+ *
+ * * **Message → POST.**  On each ``runAgent`` call the agent finds the
+ *   latest user message in ``input.messages`` and posts its content to
+ *   ``/v1/website/sessions/{id}/messages`` with the CSRF header.
+ *
+ * * **SSE → AG-UI.**  The channel's native event stream is converted
+ *   to AG-UI events by :class:`Translator` frame-by-frame.  The agent
+ *   opens a fresh EventSource per run (with ``?after=<cursor>`` to
+ *   skip already-processed frames) and closes it after a short grace
+ *   drain on turn completion so trailing server frames (late
+ *   ``memory.update``, ``session.done``) advance the cursor rather
+ *   than replaying on the next run.
+ *
+ * * **RUN lifecycle.**  AG-UI requires every run to be bracketed by
+ *   ``RUN_STARTED`` and exactly one of ``RUN_FINISHED`` / ``RUN_ERROR``.
+ *   Surogates has no such sentinel on the wire, so the agent emits
+ *   them itself; a per-run ``terminated`` flag guarantees at most one
+ *   terminal event even under concurrent SSE ``onerror`` + translator
+ *   end-of-turn detection.
+ */
+
+/**
+ * Constructor config for :class:`WebsiteAgent`.  Extends AG-UI's
+ * base ``AgentConfig`` with the two Surogates-specific fields the
+ * bootstrap needs; everything else (``agentId``, ``threadId``,
+ * ``initialMessages``, ``initialState``, ``debug``) is inherited
+ * unchanged so consumers reuse the AG-UI patterns they already know.
+ */
+interface WebsiteAgentConfig extends AgentConfig {
+    /** Base URL of the Surogates API, e.g. ``https://agent.acme.com``. */
+    apiUrl: string;
+    /** Publishable key issued by ops (``surg_wk_...``). */
+    publishableKey: string;
+}
+declare class WebsiteAgent extends AbstractAgent {
+    readonly apiUrl: string;
+    readonly publishableKey: string;
+    /** Cached bootstrap result.  ``undefined`` until the first ``run()``. */
+    private bootstrapResult;
+    /** Monotonic cursor across runs.  Passed to the SSE ``?after=`` param. */
+    private cursor;
+    constructor(config: WebsiteAgentConfig);
+    /**
+     * Ensure we have a live session cookie + CSRF token.
+     *
+     * Idempotent; returns the cached result when one already exists.
+     * ``bootstrap()`` is the only call that requires the publishable
+     * key to travel in an Authorization header, so callers that want
+     * to eagerly validate their configuration (e.g. to surface a
+     * setup error at widget-load time) can invoke this directly.
+     */
+    ensureBootstrapped(): Promise<BootstrapResult>;
+    /**
+     * Close the current session on the server side and drop local state.
+     *
+     * Callers should invoke this when the visitor closes the chat UI
+     * so the server can mark the session complete instead of waiting
+     * for the idle-reset timer.  Safe to call when no session has been
+     * bootstrapped yet.
+     */
+    end(): Promise<void>;
+    /**
+     * Implementation of the AG-UI ``run()`` contract.
+     *
+     * Returns a cold observable: one subscription per run.  AG-UI's
+     * ``runAgent`` pipeline pipes this through chunk transformation,
+     * verification, and subscriber notifications before updating
+     * ``this.messages``.
+     */
+    run(input: RunAgentInput): Observable<BaseEvent>;
+    /**
+     * Async body of the observable factory.
+     *
+     * Emits ``RUN_STARTED`` up front so every downstream failure is
+     * well-bracketed by the AG-UI lifecycle.  ``RUN_FINISHED`` is
+     * emitted by the SSE listeners when the translator detects end-of-
+     * turn; ``RUN_ERROR`` is emitted from the catch below when bootstrap
+     * or message-send fails before the SSE has any chance to close out.
+     *
+     * The ``ctx.terminated`` guard is the single enforcement point for
+     * AG-UI's "exactly one terminal event" invariant.  Every emission
+     * site checks it before calling ``subscriber.next`` with RUN_FINISHED
+     * or RUN_ERROR, and every terminal call sets it to true first.
+     */
+    private driveRun;
+    /**
+     * Tear down whatever EventSource is currently live on ``ctx`` and
+     * open a fresh one against *sessionId* starting at *after*.  Called
+     * both for the initial stream and after cookie recovery.  Always
+     * clears the stale ``onerror`` first so the old source can't race
+     * a ``RUN_ERROR`` into the subscriber after it's been replaced.
+     */
+    private replaceStreamSource;
+    /**
+     * Try ``sendMessage``; on auth failure re-bootstrap once and retry.
+     *
+     * The re-bootstrap mints a new session id, so the caller passes an
+     * ``onRebootstrap`` callback that reopens the SSE stream against the
+     * fresh session before the retry.  Visitor continuity across
+     * bootstraps is a deliberate non-feature for v1; the new session
+     * starts empty.  Only frames emitted on the OLD session between
+     * SSE-open and send-failure are lost -- and those are always
+     * previous-turn events, since the current turn's ``sendMessage`` is
+     * what 401-ed.
+     */
+    private sendWithCookieRecovery;
+    /**
+     * Wire up the EventSource to translate and forward every frame,
+     * and terminate the observable when the translator flags
+     * end-of-turn or a transport failure occurs.
+     *
+     * After the translator flips end-of-turn we emit ``RUN_FINISHED``
+     * immediately, then keep the stream open for ``DRAIN_WINDOW_MS``
+     * so trailing frames (late ``memory.update``, the sentinel
+     * ``session.done``) advance ``this.cursor`` rather than arriving
+     * on the next run.  The ``ctx.terminated`` gate stops additional
+     * subscriber emissions during the drain.
+     */
+    private attachStreamListeners;
+    /**
+     * Find the last user-authored message body to post.  AG-UI supports
+     * multimodal content arrays; this v1 only handles string content
+     * (the website channel's ``POST /messages`` endpoint accepts plain
+     * text).  Multimodal support lands once the server grows a media
+     * upload path.
+     */
+    private extractUserText;
+}
+
+export { WebsiteAgent as W, type WebsiteAgentConfig as a };

package/dist/agent-ia0JiKMG.d.ts

@@ -0,0 +1,174 @@
+import { AbstractAgent, AgentConfig, RunAgentInput, BaseEvent } from '@ag-ui/client';
+import { Observable } from 'rxjs';
+
+/**
+ * HTTP + SSE wire layer.
+ *
+ * Pure functions that talk to the website channel's three endpoints,
+ * isolated here so :class:`WebsiteAgentClient` can stay focused on
+ * state-machine orchestration.  All fetches use ``credentials:
+ * 'include'`` so the browser sends the HttpOnly session cookie that
+ * ``bootstrap`` set -- without it the message/SSE/end routes return
+ * 401 and the whole channel falls apart.
+ *
+ * SSE is handled by the native ``EventSource`` rather than a custom
+ * fetch-based parser because the native implementation is zero bytes,
+ * auto-reconnects on network drops, and respects browser-internal
+ * backoff heuristics.  The one thing it can't do is resume with a
+ * server-side cursor, so we manage the ``?after=N`` reopen logic
+ * explicitly in :class:`WebsiteAgentClient`.
+ */
+interface BootstrapResult {
+    sessionId: string;
+    csrfToken: string;
+    expiresAt: number;
+    agentName: string;
+}
+
+/**
+ * AG-UI ``AbstractAgent`` implementation for the Surogates public-website channel.
+ *
+ * A ``WebsiteAgent`` bridges the channel-specific HTTP protocol
+ * (publishable-key bootstrap, HttpOnly cookie, CSRF double-submit,
+ * ``/v1/website/sessions/{id}/events`` SSE) onto AG-UI's standard
+ * ``run()`` contract so any AG-UI-aware host app -- CopilotKit,
+ * custom chat UIs, LangGraph-style clients -- can talk to a Surogates
+ * backend with no custom glue beyond instantiation.
+ *
+ * Responsibilities
+ * ----------------
+ * * **Lazy bootstrap.**  The first ``runAgent`` call POSTs to
+ *   ``/v1/website/sessions`` to exchange the publishable key for a
+ *   session cookie + CSRF token; subsequent calls reuse them.  A cookie
+ *   expiry (HTTP 401) triggers a transparent re-bootstrap so the host
+ *   app never has to manage auth state.
+ *
+ * * **Message → POST.**  On each ``runAgent`` call the agent finds the
+ *   latest user message in ``input.messages`` and posts its content to
+ *   ``/v1/website/sessions/{id}/messages`` with the CSRF header.
+ *
+ * * **SSE → AG-UI.**  The channel's native event stream is converted
+ *   to AG-UI events by :class:`Translator` frame-by-frame.  The agent
+ *   opens a fresh EventSource per run (with ``?after=<cursor>`` to
+ *   skip already-processed frames) and closes it after a short grace
+ *   drain on turn completion so trailing server frames (late
+ *   ``memory.update``, ``session.done``) advance the cursor rather
+ *   than replaying on the next run.
+ *
+ * * **RUN lifecycle.**  AG-UI requires every run to be bracketed by
+ *   ``RUN_STARTED`` and exactly one of ``RUN_FINISHED`` / ``RUN_ERROR``.
+ *   Surogates has no such sentinel on the wire, so the agent emits
+ *   them itself; a per-run ``terminated`` flag guarantees at most one
+ *   terminal event even under concurrent SSE ``onerror`` + translator
+ *   end-of-turn detection.
+ */
+
+/**
+ * Constructor config for :class:`WebsiteAgent`.  Extends AG-UI's
+ * base ``AgentConfig`` with the two Surogates-specific fields the
+ * bootstrap needs; everything else (``agentId``, ``threadId``,
+ * ``initialMessages``, ``initialState``, ``debug``) is inherited
+ * unchanged so consumers reuse the AG-UI patterns they already know.
+ */
+interface WebsiteAgentConfig extends AgentConfig {
+    /** Base URL of the Surogates API, e.g. ``https://agent.acme.com``. */
+    apiUrl: string;
+    /** Publishable key issued by ops (``surg_wk_...``). */
+    publishableKey: string;
+}
+declare class WebsiteAgent extends AbstractAgent {
+    readonly apiUrl: string;
+    readonly publishableKey: string;
+    /** Cached bootstrap result.  ``undefined`` until the first ``run()``. */
+    private bootstrapResult;
+    /** Monotonic cursor across runs.  Passed to the SSE ``?after=`` param. */
+    private cursor;
+    constructor(config: WebsiteAgentConfig);
+    /**
+     * Ensure we have a live session cookie + CSRF token.
+     *
+     * Idempotent; returns the cached result when one already exists.
+     * ``bootstrap()`` is the only call that requires the publishable
+     * key to travel in an Authorization header, so callers that want
+     * to eagerly validate their configuration (e.g. to surface a
+     * setup error at widget-load time) can invoke this directly.
+     */
+    ensureBootstrapped(): Promise<BootstrapResult>;
+    /**
+     * Close the current session on the server side and drop local state.
+     *
+     * Callers should invoke this when the visitor closes the chat UI
+     * so the server can mark the session complete instead of waiting
+     * for the idle-reset timer.  Safe to call when no session has been
+     * bootstrapped yet.
+     */
+    end(): Promise<void>;
+    /**
+     * Implementation of the AG-UI ``run()`` contract.
+     *
+     * Returns a cold observable: one subscription per run.  AG-UI's
+     * ``runAgent`` pipeline pipes this through chunk transformation,
+     * verification, and subscriber notifications before updating
+     * ``this.messages``.
+     */
+    run(input: RunAgentInput): Observable<BaseEvent>;
+    /**
+     * Async body of the observable factory.
+     *
+     * Emits ``RUN_STARTED`` up front so every downstream failure is
+     * well-bracketed by the AG-UI lifecycle.  ``RUN_FINISHED`` is
+     * emitted by the SSE listeners when the translator detects end-of-
+     * turn; ``RUN_ERROR`` is emitted from the catch below when bootstrap
+     * or message-send fails before the SSE has any chance to close out.
+     *
+     * The ``ctx.terminated`` guard is the single enforcement point for
+     * AG-UI's "exactly one terminal event" invariant.  Every emission
+     * site checks it before calling ``subscriber.next`` with RUN_FINISHED
+     * or RUN_ERROR, and every terminal call sets it to true first.
+     */
+    private driveRun;
+    /**
+     * Tear down whatever EventSource is currently live on ``ctx`` and
+     * open a fresh one against *sessionId* starting at *after*.  Called
+     * both for the initial stream and after cookie recovery.  Always
+     * clears the stale ``onerror`` first so the old source can't race
+     * a ``RUN_ERROR`` into the subscriber after it's been replaced.
+     */
+    private replaceStreamSource;
+    /**
+     * Try ``sendMessage``; on auth failure re-bootstrap once and retry.
+     *
+     * The re-bootstrap mints a new session id, so the caller passes an
+     * ``onRebootstrap`` callback that reopens the SSE stream against the
+     * fresh session before the retry.  Visitor continuity across
+     * bootstraps is a deliberate non-feature for v1; the new session
+     * starts empty.  Only frames emitted on the OLD session between
+     * SSE-open and send-failure are lost -- and those are always
+     * previous-turn events, since the current turn's ``sendMessage`` is
+     * what 401-ed.
+     */
+    private sendWithCookieRecovery;
+    /**
+     * Wire up the EventSource to translate and forward every frame,
+     * and terminate the observable when the translator flags
+     * end-of-turn or a transport failure occurs.
+     *
+     * After the translator flips end-of-turn we emit ``RUN_FINISHED``
+     * immediately, then keep the stream open for ``DRAIN_WINDOW_MS``
+     * so trailing frames (late ``memory.update``, the sentinel
+     * ``session.done``) advance ``this.cursor`` rather than arriving
+     * on the next run.  The ``ctx.terminated`` gate stops additional
+     * subscriber emissions during the drain.
+     */
+    private attachStreamListeners;
+    /**
+     * Find the last user-authored message body to post.  AG-UI supports
+     * multimodal content arrays; this v1 only handles string content
+     * (the website channel's ``POST /messages`` endpoint accepts plain
+     * text).  Multimodal support lands once the server grows a media
+     * upload path.
+     */
+    private extractUserText;
+}
+
+export { WebsiteAgent as W, type WebsiteAgentConfig as a };