@invergent/website-widget 1.4.3

package/dist/index.d.ts

@@ -0,0 +1,406 @@
+import { AbstractAgent, AgentConfig, RunAgentInput, BaseEvent } from '@ag-ui/client';
+export { AbstractAgent, EventType } 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;
+}
+
+/**
+ * Pure event translation: Surogates wire events → AG-UI ``BaseEvent``\ s.
+ *
+ * The SSE stream delivered by ``/v1/website/sessions/{id}/events`` carries
+ * event types defined in ``surogates/session/events.py``
+ * (``user.message``, ``llm.delta``, ``llm.response``, ``tool.call``, ...).
+ * AG-UI consumers expect a different, standardised vocabulary
+ * (``TEXT_MESSAGE_START`` / ``CONTENT`` / ``END`` triads, ``TOOL_CALL_*``,
+ * ``RUN_STARTED`` / ``RUN_FINISHED``, ``STATE_SNAPSHOT``, etc.).  This
+ * module is the contract.
+ *
+ * Design notes
+ * ------------
+ * * **Pure and state-carried.**  ``Translator`` is a class only because
+ *   a few decisions need a tiny bit of memory (have we emitted the
+ *   running ``TextMessageStart`` yet?  how many tool calls are
+ *   outstanding?  did the last ``llm.response`` signal end-of-turn?).
+ *   It does not touch the network or any globals; every instance is a
+ *   single run's translation state and discardable after
+ *   ``RUN_FINISHED``.
+ *
+ * * **Chunks over triads.**  AG-UI provides
+ *   ``TEXT_MESSAGE_CHUNK`` / ``TOOL_CALL_CHUNK`` convenience events
+ *   that expand to the START / CONTENT / END triad automatically via
+ *   the client-side ``transformChunks`` pipeline.  Surogates already
+ *   streams in chunks (``llm.delta``, full-payload ``tool.call``), so
+ *   emitting chunk events keeps the translator short and matches the
+ *   data we actually have.
+ *
+ * * **Unknown → CUSTOM.**  Platform-specific events we cannot map to
+ *   first-class AG-UI events (memory updates, saga step transitions,
+ *   session resets, context compaction) are emitted as AG-UI ``CUSTOM``
+ *   events with ``name`` set to the Surogates event type and ``value``
+ *   set to the raw payload.  Consumers that care can match on
+ *   ``name``; consumers that don't simply ignore CUSTOM.
+ *
+ * * **End-of-turn heuristic.**  Our server does not emit a
+ *   ``turn.complete`` event.  Per-turn completion is inferred: an
+ *   ``llm.response`` whose payload indicates the model is done (no
+ *   pending tool calls, ``finish_reason`` of ``stop`` / ``end_turn``)
+ *   flips ``isTurnComplete`` to ``true``.  The caller emits
+ *   ``RUN_FINISHED`` and closes the stream.  A ``session.done`` SSE
+ *   sentinel also completes the turn.
+ */
+
+/** Minimal shape of a single SSE frame we read from the server. */
+interface SurogatesFrame {
+    /** Monotonic server-side event id (cursor for reconnect). */
+    id: number;
+    /** Surogates event type (``user.message``, ``llm.delta``, etc.). */
+    type: string;
+    /** Parsed JSON payload from the ``data:`` line. */
+    data: unknown;
+}
+/**
+ * Stateful translator for one run.
+ *
+ * The caller is expected to build a fresh instance per ``runAgent`` turn
+ * and discard it after the run finishes; every method is idempotent and
+ * thread-safe only in the single-SSE-consumer sense (JavaScript events
+ * are single-threaded).
+ */
+declare class Translator {
+    /**
+     * Running message id for the current streaming assistant message.
+     * Re-used across ``llm.delta`` frames so every chunk targets the
+     * same AG-UI message -- that's what makes the client-side
+     * ``transformChunks`` stitch them into one logical message.
+     */
+    private currentMessageId;
+    /**
+     * Running message id for the current reasoning stream, if any.
+     * Kept separate from ``currentMessageId`` so reasoning deltas never
+     * accidentally merge into the assistant content stream.
+     */
+    private currentReasoningId;
+    /**
+     * Tool calls that have been announced (``TOOL_CALL_CHUNK`` emitted)
+     * but have not yet received a matching ``tool.result``.  Non-empty
+     * means the turn is mid-execution even if an ``llm.response`` looks
+     * final.
+     */
+    private pendingToolCalls;
+    /** Set once we've seen an end-of-turn signal. */
+    private _turnComplete;
+    get isTurnComplete(): boolean;
+    /**
+     * Translate one SSE frame into zero or more AG-UI events.
+     *
+     * Returns an empty array when the frame carries no user-visible
+     * information (internal bookkeeping events like ``harness.wake``).
+     * Returns multiple events when a single Surogates event corresponds
+     * to a chunk triad that the AG-UI client can't reconstruct on its
+     * own -- though we try to use chunk events to keep this to one
+     * output event per input in the common path.
+     */
+    translate(frame: SurogatesFrame): BaseEvent[];
+    private handleLlmDelta;
+    private handleLlmResponse;
+    private handleLlmThinking;
+    private handleToolCall;
+    private handleToolResult;
+    private handlePolicyDenied;
+    private handleExpertDelegation;
+    private handleExpertResult;
+    private handleTerminalFailure;
+    private asCustom;
+    /**
+     * Generate a stable message id derived from the triggering frame's
+     * event id.  The event id is globally unique per session, so using
+     * it as a suffix guarantees uniqueness without pulling in ``uuid``.
+     */
+    private mintMessageId;
+}
+
+/**
+ * Error taxonomy for the website-widget SDK.
+ *
+ * Consumers should not have to parse strings to tell "the key is wrong"
+ * apart from "the network blinked" -- different remediations apply.
+ * Every error thrown or emitted by the SDK derives from
+ * :class:`SurogatesError` so a single ``instanceof`` catch is always
+ * safe; the subclasses encode the specific failure mode.
+ */
+declare class SurogatesError extends Error {
+    /** HTTP status code when the error originated from a server response. */
+    readonly status?: number;
+    /** Raw server detail string, if any. */
+    readonly detail?: string;
+    constructor(message: string, opts?: {
+        status?: number;
+        detail?: string;
+        cause?: unknown;
+    });
+}
+/**
+ * The publishable key is invalid, expired, or the request Origin is not
+ * in the agent's allow-list.  Non-retryable: the embed is misconfigured
+ * and no amount of backoff will help.
+ */
+declare class SurogatesAuthError extends SurogatesError {
+    constructor(message: string, opts?: {
+        status?: number;
+        detail?: string;
+    });
+}
+/**
+ * Rate-limited (HTTP 429) or the per-session message/token cap has
+ * been reached.  Retryable after a backoff; the SDK exposes this as a
+ * distinct type so consumers can show a "slow down" indicator instead
+ * of a generic failure.
+ */
+declare class SurogatesRateLimitError extends SurogatesError {
+    /** Seconds the server asked us to wait, if it included a Retry-After header. */
+    readonly retryAfter?: number;
+    constructor(message: string, opts?: {
+        status?: number;
+        retryAfter?: number;
+        detail?: string;
+    });
+}
+/**
+ * The protocol itself is the problem -- the SDK received a response it
+ * can't interpret, or a cookie/CSRF invariant was violated.  Indicates
+ * an SDK-server version mismatch or a corrupt response; raises the
+ * priority of whatever error reporting channel the host app has.
+ */
+declare class SurogatesProtocolError extends SurogatesError {
+    constructor(message: string, opts?: {
+        status?: number;
+        detail?: string;
+        cause?: unknown;
+    });
+}
+/**
+ * Transport-level failure: network drop, CORS preflight refusal, DNS,
+ * browser offline, 5xx from an ingress/load balancer.  Retryable by
+ * design; the SDK does not auto-retry today -- the caller should back
+ * off and re-issue the operation (typically by re-invoking
+ * ``runAgent``).  A future revision may add internal exponential
+ * backoff; consumers should continue to surface these errors to the
+ * user rather than assume they'll be swallowed.
+ */
+declare class SurogatesNetworkError extends SurogatesError {
+    constructor(message: string, opts?: {
+        cause?: unknown;
+    });
+}
+
+/**
+ * Wire-protocol and SDK-version constants.
+ *
+ * ``PROTOCOL_VERSION`` is the integer the SDK sends to the server so
+ * future breaking protocol changes can be negotiated or hard-failed at
+ * bootstrap instead of silently corrupting running embeds.
+ *
+ * ``SDK_VERSION`` travels in an ``X-Surogates-Widget-Version`` header on
+ * every request so server logs can correlate a buggy client build with
+ * its error surface.  Kept in sync with ``package.json`` manually; the
+ * build pipeline can replace it at bundle time in a later phase.
+ */
+declare const PROTOCOL_VERSION = 1;
+declare const SDK_VERSION = "0.1.0";
+declare const SURG_EVENT: {
+    readonly USER_MESSAGE: "user.message";
+    readonly LLM_REQUEST: "llm.request";
+    readonly LLM_RESPONSE: "llm.response";
+    readonly LLM_THINKING: "llm.thinking";
+    readonly LLM_DELTA: "llm.delta";
+    readonly TOOL_CALL: "tool.call";
+    readonly TOOL_RESULT: "tool.result";
+    readonly SANDBOX_PROVISION: "sandbox.provision";
+    readonly SANDBOX_EXECUTE: "sandbox.execute";
+    readonly SANDBOX_RESULT: "sandbox.result";
+    readonly SANDBOX_DESTROY: "sandbox.destroy";
+    readonly SESSION_START: "session.start";
+    readonly SESSION_PAUSE: "session.pause";
+    readonly SESSION_RESUME: "session.resume";
+    readonly SESSION_COMPLETE: "session.complete";
+    readonly SESSION_FAIL: "session.fail";
+    readonly SESSION_DONE: "session.done";
+    readonly CONTEXT_COMPACT: "context.compact";
+    readonly MEMORY_UPDATE: "memory.update";
+    readonly EXPERT_DELEGATION: "expert.delegation";
+    readonly EXPERT_RESULT: "expert.result";
+    readonly EXPERT_FAILURE: "expert.failure";
+    readonly POLICY_DENIED: "policy.denied";
+    readonly POLICY_ALLOWED: "policy.allowed";
+    readonly HARNESS_CRASH: "harness.crash";
+};
+
+export { PROTOCOL_VERSION, SDK_VERSION, SURG_EVENT, SurogatesAuthError, SurogatesError, type SurogatesFrame, SurogatesNetworkError, SurogatesProtocolError, SurogatesRateLimitError, Translator, WebsiteAgent, type WebsiteAgentConfig };