@trigger.dev/sdk 4.4.6 → 4.5.0-rc.0

package/dist/commonjs/v3/chat.js

@@ -0,0 +1,968 @@
+"use strict";
+/**
+ * @module @trigger.dev/sdk/chat
+ *
+ * Browser-safe module for AI SDK chat transport integration.
+ * Use this on the frontend with the AI SDK's `useChat` hook.
+ *
+ * For backend helpers (`chatAgent`, `pipeChat`), use `@trigger.dev/sdk/ai` instead.
+ *
+ * @example
+ * ```tsx
+ * import { useChat } from "@ai-sdk/react";
+ * import { TriggerChatTransport } from "@trigger.dev/sdk/chat";
+ *
+ * function Chat() {
+ *   const { messages, sendMessage, status } = useChat({
+ *     transport: new TriggerChatTransport({
+ *       task: "my-chat-task",
+ *       accessToken: async ({ chatId }) => fetchSessionToken(chatId),
+ *       startSession: async ({ chatId, taskId }) => createChatSession({ chatId, taskId }),
+ *     }),
+ *   });
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChatStream = exports.AgentChat = exports.TriggerChatTransport = void 0;
+exports.createChatTransport = createChatTransport;
+const v3_1 = require("@trigger.dev/core/v3");
+const chat_tab_coordinator_js_1 = require("./chat-tab-coordinator.js");
+const DEFAULT_BASE_URL = "https://api.trigger.dev";
+const DEFAULT_STREAM_TIMEOUT_SECONDS = 120;
+/**
+ * Detect 401/403 from realtime/input-stream calls without relying on `instanceof`
+ * (Vitest can load duplicate `@trigger.dev/core` copies, which breaks subclass checks).
+ */
+function isAuthError(error) {
+    if (error === null || typeof error !== "object")
+        return false;
+    const e = error;
+    return e.name === "TriggerApiError" && (e.status === 401 || e.status === 403);
+}
+/**
+ * Parses an SSE byte/text stream of `data: <UIMessageChunk JSON>\n\n`
+ * frames back into `UIMessageChunk` objects. Used by the handover
+ * first-turn path to convert the customer's route handler response
+ * (which is AI-SDK-shaped SSE text) into the chunk form the AI SDK's
+ * `useChat` consumes from a transport.
+ *
+ * Spec-light parser — assumes well-formed `data:` events from our own
+ * `chat.handover` SSE writer. Lines starting with `:` (comments) and
+ * other event types are ignored.
+ */
+function parseUIMessageSseTransform() {
+    let buffer = "";
+    return new TransformStream({
+        transform(chunk, controller) {
+            buffer += chunk;
+            // Frames are separated by blank lines.
+            let idx = buffer.indexOf("\n\n");
+            while (idx !== -1) {
+                const frame = buffer.slice(0, idx);
+                buffer = buffer.slice(idx + 2);
+                for (const line of frame.split("\n")) {
+                    if (line.startsWith("data: ")) {
+                        const data = line.slice(6).trim();
+                        if (!data)
+                            continue;
+                        try {
+                            controller.enqueue(JSON.parse(data));
+                        }
+                        catch {
+                            /* drop malformed chunk; the response source is our own writer */
+                        }
+                    }
+                }
+                idx = buffer.indexOf("\n\n");
+            }
+        },
+        flush(controller) {
+            // Trailing data without a closing blank line — treat as a final frame.
+            if (buffer.trim().length === 0)
+                return;
+            for (const line of buffer.split("\n")) {
+                if (line.startsWith("data: ")) {
+                    const data = line.slice(6).trim();
+                    if (!data)
+                        continue;
+                    try {
+                        controller.enqueue(JSON.parse(data));
+                    }
+                    catch {
+                        /* drop */
+                    }
+                }
+            }
+            buffer = "";
+        },
+    });
+}
+/**
+ * A custom AI SDK `ChatTransport` that runs chat completions as durable
+ * Trigger.dev tasks via the Sessions primitive.
+ *
+ * Lifecycle:
+ *   1. Customer pre-creates the session server-side OR calls
+ *      `transport.start(chatId)` to mint a one-shot start token and
+ *      `POST /api/v1/sessions` from the browser.
+ *   2. The server triggers the first run as part of session create and
+ *      returns a session-scoped PAT.
+ *   3. `sendMessages` appends to `.in` and subscribes to `.out`. When a
+ *      run dies (idle, cancel, end-and-continue), the server's
+ *      append-time probe triggers a fresh run for the same session —
+ *      transport keeps streaming.
+ *   4. `stop()` posts a `{kind:"stop"}` chunk; the agent's turn aborts
+ *      but the run keeps reading `.in` for the next message.
+ *   5. PAT expiry: transport invokes `accessToken` to refresh and
+ *      retries the failing request once.
+ */
+class TriggerChatTransport {
+    taskId;
+    resolveAccessToken;
+    resolveStartSession;
+    resolveBaseURLFn;
+    fetchOverride;
+    extraHeaders;
+    streamTimeoutSeconds;
+    defaultMetadata;
+    watchMode;
+    headStart;
+    coordinator = null;
+    _onSessionChange;
+    sessions = new Map();
+    activeStreams = new Map();
+    pendingStarts = new Map();
+    constructor(options) {
+        this.taskId = options.task;
+        this.resolveAccessToken = options.accessToken;
+        this.resolveStartSession = options.startSession;
+        const baseURLOption = options.baseURL ?? DEFAULT_BASE_URL;
+        const streamOverride = options.streamBaseURL;
+        this.resolveBaseURLFn = typeof baseURLOption === "function"
+            ? (ctx) => (ctx.endpoint === "out" && streamOverride ? streamOverride : baseURLOption(ctx))
+            : (ctx) => (ctx.endpoint === "out" && streamOverride ? streamOverride : baseURLOption);
+        this.fetchOverride = options.fetch;
+        this.extraHeaders = options.headers ?? {};
+        this.streamTimeoutSeconds = options.streamTimeoutSeconds ?? DEFAULT_STREAM_TIMEOUT_SECONDS;
+        this.defaultMetadata = options.clientData;
+        this._onSessionChange = options.onSessionChange;
+        this.watchMode = options.watch ?? false;
+        this.headStart = options.headStart;
+        if (options.multiTab && !this.watchMode) {
+            this.coordinator = new chat_tab_coordinator_js_1.ChatTabCoordinator();
+            this.coordinator.addSessionListener((chatId, sessionUpdate) => {
+                const session = this.sessions.get(chatId);
+                if (session && sessionUpdate.lastEventId) {
+                    session.lastEventId = sessionUpdate.lastEventId;
+                }
+            });
+        }
+        if (options.sessions) {
+            for (const [chatId, session] of Object.entries(options.sessions)) {
+                this.sessions.set(chatId, {
+                    publicAccessToken: session.publicAccessToken,
+                    lastEventId: session.lastEventId,
+                    isStreaming: session.isStreaming,
+                });
+            }
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Public lifecycle
+    // -------------------------------------------------------------------------
+    /**
+     * Eagerly create a Session and trigger its first run. Useful as a
+     * "the user might be about to send a message — boot the agent now"
+     * preload, or to take ownership of the session before any sendMessage.
+     *
+     * Idempotent: calling `start(chatId)` twice converges to the same
+     * session via the `(env, externalId)` upsert. Concurrent calls
+     * deduplicate via an in-flight promise.
+     *
+     * Requires `getStartToken` to be configured. Customers who pre-create
+     * sessions server-side don't need to call this.
+     */
+    async start(chatId) {
+        const existing = this.sessions.get(chatId);
+        if (existing?.publicAccessToken) {
+            return this.toPersisted(existing);
+        }
+        const inflight = this.pendingStarts.get(chatId);
+        if (inflight)
+            return inflight.then(this.toPersisted);
+        const promise = this.doStart(chatId).finally(() => {
+            this.pendingStarts.delete(chatId);
+        });
+        this.pendingStarts.set(chatId, promise);
+        return promise.then(this.toPersisted);
+    }
+    /**
+     * Eagerly create the session before the user types. Same semantics as
+     * {@link start} — kept as a separate name for the AI SDK Chat hook,
+     * which calls `preload` rather than `start`.
+     */
+    async preload(chatId) {
+        await this.start(chatId);
+    }
+    /**
+     * Send a user message via the session's `.in` channel. The server
+     * probes `currentRunId`; if terminal/null it triggers a fresh run on
+     * the same session before the append lands. The returned
+     * `ReadableStream` carries the agent's response chunks via `.out` SSE.
+     */
+    sendMessages = async (options) => {
+        const { trigger, chatId, messageId, messages, abortSignal, body, metadata } = options;
+        if (this.coordinator) {
+            if (this.coordinator.isReadOnly(chatId)) {
+                throw new Error("This chat is active in another tab");
+            }
+            this.coordinator.claim(chatId);
+        }
+        const mergedMetadata = this.defaultMetadata || metadata
+            ? { ...(this.defaultMetadata ?? {}), ...(metadata ?? {}) }
+            : undefined;
+        // First-turn handover routing — when `headStart` is set AND no
+        // session state exists yet for this chatId, POST the wire payload
+        // to the customer's `chat.handover` route handler. The handler
+        // creates the session, triggers the agent run with
+        // `handover-prepare`, runs `streamText` step 1 in its warm
+        // process, and tees the output back as the SSE response. We
+        // hydrate session state from the response headers so subsequent
+        // turns bypass the handler and use direct `session.in` writes.
+        if (this.headStart && !this.sessions.has(chatId)) {
+            return this.sendMessagesViaHandover({
+                trigger,
+                chatId,
+                messageId,
+                messages,
+                abortSignal,
+                body,
+                metadata: mergedMetadata,
+            });
+        }
+        // Slim wire — at most ONE message per record. The agent rebuilds prior
+        // history from its durable S3 snapshot + session.out replay at run boot
+        // (or `hydrateMessages`, if registered). See plan vivid-humming-bonbon.
+        //
+        //   - "submit-message": ship the latest message (new user message OR a
+        //     tool-approval-responded assistant message). Throw if absent.
+        //   - "regenerate-message": omit `message`; the agent slices its own
+        //     history (drops the trailing assistant) and re-runs.
+        if (trigger === "submit-message" && messages.length === 0) {
+            throw new Error("TriggerChatTransport.sendMessages: 'submit-message' trigger requires at least one message");
+        }
+        const wirePayload = {
+            ...(body ?? {}),
+            ...(trigger === "submit-message" ? { message: messages.at(-1) } : {}),
+            chatId,
+            trigger,
+            messageId,
+            metadata: mergedMetadata,
+        };
+        const state = await this.ensureSessionState(chatId);
+        const sendChatMessage = async (token) => {
+            await this.appendInputChunk(chatId, token, this.serializeInputChunk({ kind: "message", payload: wirePayload }));
+        };
+        await this.callWithAuthRetry(chatId, state, sendChatMessage);
+        // Cancel any in-flight stream for this chat — the new turn supersedes it.
+        const activeStream = this.activeStreams.get(chatId);
+        if (activeStream) {
+            activeStream.abort();
+            this.activeStreams.delete(chatId);
+        }
+        state.isStreaming = true;
+        this.notifySessionChange(chatId, state);
+        return this.subscribeToSessionStream(state, abortSignal, chatId);
+    };
+    /**
+     * First-turn-only path used when `headStart` is configured. POSTs the
+     * wire payload to the customer's `chat.handover` route handler and
+     * pipes its SSE response back as a UIMessageChunk stream. Hydrates
+     * session state from response headers so subsequent turns bypass
+     * the endpoint and use the direct `session.in` path.
+     */
+    async sendMessagesViaHandover(args) {
+        if (!this.headStart) {
+            throw new Error("sendMessagesViaHandover called without headStart configured");
+        }
+        // Head-start ships full UIMessage history via `headStartMessages`. The
+        // route handler runs on the customer's own HTTP endpoint (NOT
+        // `/realtime/v1/sessions/{id}/in/append`), so the 512 KiB body cap
+        // doesn't apply. The agent's run boot consumes `headStartMessages` ONLY
+        // when no snapshot exists yet (very first turn) — see plan section B.3.
+        const wirePayload = {
+            ...(args.body ?? {}),
+            headStartMessages: args.messages,
+            chatId: args.chatId,
+            trigger: args.trigger,
+            messageId: args.messageId,
+            metadata: args.metadata,
+        };
+        const response = await fetch(this.headStart, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                ...this.extraHeaders,
+            },
+            body: JSON.stringify(wirePayload),
+            signal: args.abortSignal,
+        });
+        if (!response.ok) {
+            throw new Error(`chat.handover endpoint returned ${response.status} ${response.statusText}`);
+        }
+        if (!response.body) {
+            throw new Error("chat.handover endpoint returned no response body");
+        }
+        // Hydrate session state from response headers so subsequent turns
+        // skip the endpoint and write directly to session.in. Failing fast
+        // when the header is missing avoids a quiet degraded state where
+        // every later turn re-runs the handover route instead of taking
+        // the slim-wire path.
+        const accessToken = response.headers.get("X-Trigger-Chat-Access-Token");
+        const chatId = args.chatId;
+        if (!accessToken) {
+            throw new Error("chat.handover response is missing the X-Trigger-Chat-Access-Token header. chat.agent's handover endpoint must echo the session PAT so the transport can hydrate.");
+        }
+        const state = {
+            publicAccessToken: accessToken,
+            isStreaming: true,
+        };
+        this.sessions.set(chatId, state);
+        this.notifySessionChange(chatId, state);
+        // Filter the parsed UIMessage stream:
+        //   - Drop control chunks (`trigger:turn-complete`,
+        //     `trigger:session-state`) before they reach AI SDK — they
+        //     aren't valid UIMessageChunks and the AI SDK chunk parser
+        //     would reject them.
+        //   - On `trigger:turn-complete`, clear `isStreaming` so the
+        //     useChat resume / reconnectToStream path doesn't open a
+        //     second `session.out` subscription on top of our stitched
+        //     response.
+        //   - On `trigger:session-state`, hydrate `state.lastEventId`
+        //     with the agent's final S2 event id. Without this, turn 2's
+        //     `session.out` subscribe reads from the start and replays
+        //     turn 1's chunks back into the UI.
+        //   - On stream end (handover-skip case — no
+        //     `trigger:turn-complete` arrives, customer's stream just
+        //     ends), also clear `isStreaming` for the same reason.
+        const sessions = this.sessions;
+        const notifyChange = (id, state) => this.notifySessionChange(id, state);
+        const TRIGGER_TURN_COMPLETE = "trigger:turn-complete";
+        const TRIGGER_SESSION_STATE = "trigger:session-state";
+        const clearStreaming = () => {
+            const state = sessions.get(chatId);
+            if (state && state.isStreaming) {
+                state.isStreaming = false;
+                notifyChange(chatId, state);
+            }
+        };
+        const setLastEventId = (lastEventId) => {
+            const state = sessions.get(chatId);
+            if (state) {
+                state.lastEventId = lastEventId;
+                notifyChange(chatId, state);
+            }
+        };
+        return response.body
+            .pipeThrough(new TextDecoderStream())
+            .pipeThrough(parseUIMessageSseTransform())
+            .pipeThrough(new TransformStream({
+            transform(chunk, controller) {
+                if (chunk && typeof chunk === "object") {
+                    const type = chunk.type;
+                    if (type === TRIGGER_TURN_COMPLETE) {
+                        clearStreaming();
+                        return; // drop — not a real UIMessageChunk
+                    }
+                    if (type === TRIGGER_SESSION_STATE) {
+                        const lastEventId = chunk.lastEventId;
+                        if (typeof lastEventId === "string") {
+                            setLastEventId(lastEventId);
+                        }
+                        return; // drop
+                    }
+                }
+                controller.enqueue(chunk);
+            },
+            flush() {
+                clearStreaming();
+            },
+        }));
+    }
+    /**
+     * Send a steering message during an active stream without disrupting
+     * it. The agent's `pendingMessages` config decides whether to inject
+     * between tool-call steps or buffer for the next turn.
+     */
+    sendPendingMessage = async (chatId, message, metadata) => {
+        const state = this.sessions.get(chatId);
+        if (!state)
+            return false;
+        const mergedMetadata = this.defaultMetadata || metadata
+            ? { ...(this.defaultMetadata ?? {}), ...(metadata ?? {}) }
+            : undefined;
+        const wirePayload = {
+            message,
+            chatId,
+            trigger: "submit-message",
+            metadata: mergedMetadata,
+        };
+        const send = async (token) => {
+            await this.appendInputChunk(chatId, token, this.serializeInputChunk({ kind: "message", payload: wirePayload }));
+        };
+        try {
+            await this.callWithAuthRetry(chatId, state, send);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    /**
+     * Re-establish an SSE subscription to a known session. Used after a
+     * page refresh: the customer hydrates `sessions` in the constructor,
+     * the AI SDK calls `reconnectToStream` to resume the stream.
+     */
+    reconnectToStream = async (options) => {
+        const state = this.sessions.get(options.chatId);
+        if (!state)
+            return null;
+        if (state.isStreaming === false)
+            return null;
+        if (this.activeStreams.has(options.chatId))
+            return null;
+        const abortController = new AbortController();
+        this.activeStreams.set(options.chatId, abortController);
+        const abortSignal = options.abortSignal
+            ? AbortSignal.any([options.abortSignal, abortController.signal])
+            : abortController.signal;
+        return this.subscribeToSessionStream(state, abortSignal, options.chatId, {
+            sendStopOnAbort: !!options.abortSignal,
+            // Reconnect-on-reload opts into the server's settled-peek shortcut
+            // so the SSE doesn't hang for 60s when no turn is in flight. Active
+            // send-a-message paths must keep wait=60 to avoid racing the
+            // freshly-triggered turn's first chunk.
+            peekSettled: true,
+        });
+    };
+    /**
+     * Stop the current generation. Sends `{kind:"stop"}` on `.in`; the
+     * agent aborts its `streamText` call but stays alive for the next
+     * message.
+     */
+    stopGeneration = async (chatId) => {
+        const state = this.sessions.get(chatId);
+        if (!state)
+            return false;
+        const send = async (token) => {
+            await this.appendInputChunk(chatId, token, this.serializeInputChunk({ kind: "stop" }));
+        };
+        try {
+            await this.callWithAuthRetry(chatId, state, send);
+        }
+        catch {
+            return false;
+        }
+        state.skipToTurnComplete = true;
+        const activeStream = this.activeStreams.get(chatId);
+        if (activeStream) {
+            activeStream.abort();
+            this.activeStreams.delete(chatId);
+        }
+        return true;
+    };
+    /**
+     * Send a custom action chunk (for `chat.agent`'s `actionSchema` /
+     * `onAction` hook). Actions are not turns — only `hydrateMessages`
+     * and `onAction` fire on the agent side. The returned stream
+     * carries any model response `onAction` produced (when it returns a
+     * `StreamTextResult`); for `void`-returning side-effect-only actions
+     * the stream completes immediately with `trigger:turn-complete`.
+     */
+    sendAction = async (chatId, action) => {
+        if (this.coordinator) {
+            if (this.coordinator.isReadOnly(chatId)) {
+                throw new Error("This chat is active in another tab");
+            }
+            this.coordinator.claim(chatId);
+        }
+        const state = await this.ensureSessionState(chatId);
+        const wirePayload = {
+            chatId,
+            trigger: "action",
+            action,
+            metadata: this.defaultMetadata ?? undefined,
+        };
+        const body = this.serializeInputChunk({ kind: "message", payload: wirePayload });
+        const send = async (token) => {
+            await this.appendInputChunk(chatId, token, body);
+        };
+        await this.callWithAuthRetry(chatId, state, send);
+        return this.subscribeToSessionStream(state, undefined, chatId);
+    };
+    // -------------------------------------------------------------------------
+    // External-state surface
+    // -------------------------------------------------------------------------
+    getSession = (chatId) => {
+        const state = this.sessions.get(chatId);
+        if (!state)
+            return undefined;
+        return this.toPersisted(state);
+    };
+    setSession(chatId, session) {
+        this.sessions.set(chatId, {
+            publicAccessToken: session.publicAccessToken,
+            lastEventId: session.lastEventId,
+            isStreaming: session.isStreaming,
+        });
+        this.notifySessionChange(chatId, this.toPersisted(this.sessions.get(chatId)));
+    }
+    setOnSessionChange(callback) {
+        this._onSessionChange = callback;
+    }
+    /**
+     * Update the transport's `clientData`. Used by `useTriggerChatTransport`
+     * to keep the latest value reachable from inside `startSession` and
+     * the per-turn `metadata` merge without recreating the transport.
+     *
+     * Reads always go through the live field — closures around the
+     * transport see the latest value the next time they fire.
+     */
+    setClientData(clientData) {
+        this.defaultMetadata = clientData;
+    }
+    // -------------------------------------------------------------------------
+    // Multi-tab coordination passthrough
+    // -------------------------------------------------------------------------
+    isReadOnly(chatId) {
+        return this.coordinator?.isReadOnly(chatId) ?? false;
+    }
+    hasClaim(chatId) {
+        return this.coordinator?.hasClaim(chatId) ?? false;
+    }
+    addReadOnlyListener(fn) {
+        this.coordinator?.addListener(fn);
+    }
+    removeReadOnlyListener(fn) {
+        this.coordinator?.removeListener(fn);
+    }
+    broadcastMessages(chatId, messages) {
+        this.coordinator?.broadcastMessages(chatId, messages);
+    }
+    addMessagesListener(fn) {
+        this.coordinator?.addMessagesListener(fn);
+    }
+    removeMessagesListener(fn) {
+        this.coordinator?.removeMessagesListener(fn);
+    }
+    dispose() {
+        // Tear down any open session.out subscriptions before the coordinator
+        // goes away. Otherwise controllers in `activeStreams` keep reading
+        // until they time out, leaking network and memory on every
+        // unmount/navigation.
+        for (const controller of this.activeStreams.values()) {
+            controller.abort();
+        }
+        this.activeStreams.clear();
+        this.coordinator?.dispose();
+        this.coordinator = null;
+    }
+    // -------------------------------------------------------------------------
+    // Internal helpers
+    // -------------------------------------------------------------------------
+    serializeInputChunk(chunk) {
+        return JSON.stringify(chunk);
+    }
+    toPersisted = (state) => ({
+        publicAccessToken: state.publicAccessToken,
+        lastEventId: state.lastEventId,
+        isStreaming: state.isStreaming,
+    });
+    notifySessionChange(chatId, session) {
+        if (!this._onSessionChange)
+            return;
+        this._onSessionChange(chatId, session ? this.toPersisted(session) : null);
+    }
+    /**
+     * Resolves the session state for a chatId, starting the session if
+     * needed (and `getStartToken` is configured). Customers who provide
+     * `accessToken` but no `getStartToken` are expected to have created
+     * the session server-side; in that case the first `accessToken` call
+     * returns a fresh session PAT.
+     */
+    async ensureSessionState(chatId) {
+        const existing = this.sessions.get(chatId);
+        if (existing?.publicAccessToken)
+            return existing;
+        if (this.resolveStartSession) {
+            // Lazily start: customer's server action creates the session and
+            // returns a PAT. Idempotent on `(env, externalId)` so concurrent
+            // tabs / repeat calls converge to the same session.
+            const inflight = this.pendingStarts.get(chatId);
+            if (inflight)
+                return inflight;
+            const promise = this.doStart(chatId).finally(() => {
+                this.pendingStarts.delete(chatId);
+            });
+            this.pendingStarts.set(chatId, promise);
+            return promise;
+        }
+        // No `startSession` configured. Customer fully manages session
+        // lifecycle externally — they're expected to have hydrated
+        // `sessions: { ... }` already, or the very first `accessToken` call
+        // returns a PAT for an out-of-band-created session.
+        const token = await this.resolveAccessToken({ chatId });
+        const state = { publicAccessToken: token };
+        this.sessions.set(chatId, state);
+        this.notifySessionChange(chatId, state);
+        return state;
+    }
+    async doStart(chatId) {
+        if (!this.resolveStartSession) {
+            throw new Error("TriggerChatTransport: `startSession` is required to call `start()` / `preload()`. Either provide it or pre-hydrate the session via `sessions: { ... }`.");
+        }
+        const { publicAccessToken } = await this.resolveStartSession({
+            taskId: this.taskId,
+            chatId,
+            clientData: (this.defaultMetadata ?? {}),
+        });
+        const state = {
+            publicAccessToken,
+            isStreaming: false,
+        };
+        this.sessions.set(chatId, state);
+        this.notifySessionChange(chatId, state);
+        return state;
+    }
+    /**
+     * Run `op` with the session's stored PAT. On 401/403, refresh the PAT
+     * via `accessToken` and retry once. Surfaces non-auth errors as-is.
+     */
+    resolveBaseURL(ctx) {
+        const raw = this.resolveBaseURLFn(ctx);
+        return raw.replace(/\/$/, "");
+    }
+    async doFetch(ctx, url, init) {
+        return this.fetchOverride ? this.fetchOverride(url, init, ctx) : fetch(url, init);
+    }
+    async appendInputChunk(chatId, token, body) {
+        const ctx = { endpoint: "in", chatId };
+        const url = `${this.resolveBaseURL(ctx)}/realtime/v1/sessions/${encodeURIComponent(chatId)}/in/append`;
+        const headers = {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${token}`,
+            "x-trigger-source": "sdk",
+            ...this.extraHeaders,
+        };
+        const response = await this.doFetch(ctx, url, { method: "POST", headers, body });
+        if (!response.ok) {
+            const text = await response.text().catch(() => "");
+            const err = new Error(`appendToSessionStream failed: ${response.status} ${text}`);
+            err.name = "TriggerApiError";
+            err.status = response.status;
+            throw err;
+        }
+    }
+    async callWithAuthRetry(chatId, state, op) {
+        try {
+            await op(state.publicAccessToken);
+            return;
+        }
+        catch (err) {
+            if (!isAuthError(err))
+                throw err;
+        }
+        const fresh = await this.resolveAccessToken({ chatId });
+        state.publicAccessToken = fresh;
+        this.notifySessionChange(chatId, state);
+        await op(fresh);
+    }
+    /**
+     * Open an SSE subscription to the session's `.out` stream and pipe
+     * UIMessageChunks through to the AI SDK. Trigger control records
+     * (`turn-complete`, `upgrade-required` — see `trigger-control` header
+     * on `client-protocol.mdx#records-on-session-out`) are routed by
+     * header and never reach the consumer. `upgrade-required` is purely
+     * telemetry now since the server handles the run swap inline (see
+     * `end-and-continue`).
+     */
+    subscribeToSessionStream(state, abortSignal, chatId, options) {
+        const internalAbort = new AbortController();
+        this.activeStreams.set(chatId, internalAbort);
+        const combinedSignal = abortSignal
+            ? AbortSignal.any([abortSignal, internalAbort.signal])
+            : internalAbort.signal;
+        if (abortSignal) {
+            abortSignal.addEventListener("abort", () => {
+                if (options?.sendStopOnAbort !== false) {
+                    state.skipToTurnComplete = true;
+                    this.appendInputChunk(chatId, state.publicAccessToken, this.serializeInputChunk({ kind: "stop" })).catch(() => { });
+                }
+                internalAbort.abort();
+            }, { once: true });
+        }
+        const streamUrl = `${this.resolveBaseURL({ endpoint: "out", chatId })}/realtime/v1/sessions/${encodeURIComponent(chatId)}/out`;
+        return new ReadableStream({
+            start: async (controller) => {
+                // Track the live subscription so browser wake events can act
+                // on it. Three classes of wake:
+                //   - `online`: network came back. Existing connection might
+                //     be silently dead; force a fresh one.
+                //   - `visibilitychange` → visible after long hidden: tab
+                //     was backgrounded long enough that the OS likely killed
+                //     the TCP socket. Force reconnect.
+                //   - `visibilitychange` → visible after short hidden: cheap
+                //     wake of any in-flight backoff.
+                //   - `pageshow` with `event.persisted`: bfcache restore
+                //     (mobile Safari back/forward, app-switcher resume). The
+                //     socket is definitely dead. Force reconnect.
+                let currentSubscription = null;
+                let hiddenSince = null;
+                const FORCE_RECONNECT_AFTER_HIDDEN_MS = 30_000;
+                const onVisibilityChange = () => {
+                    if (typeof document === "undefined")
+                        return;
+                    if (document.visibilityState === "hidden") {
+                        hiddenSince = Date.now();
+                        return;
+                    }
+                    const wasHiddenForMs = hiddenSince ? Date.now() - hiddenSince : 0;
+                    hiddenSince = null;
+                    if (wasHiddenForMs >= FORCE_RECONNECT_AFTER_HIDDEN_MS) {
+                        currentSubscription?.forceReconnect();
+                    }
+                    else {
+                        currentSubscription?.retryNow();
+                    }
+                };
+                const onPageShow = (event) => {
+                    // PageTransitionEvent in browsers; type guard via `persisted`.
+                    if (event.persisted) {
+                        currentSubscription?.forceReconnect();
+                    }
+                };
+                const onOnline = () => currentSubscription?.forceReconnect();
+                const teardownWakeListeners = typeof document !== "undefined" && typeof window !== "undefined"
+                    ? (() => {
+                        document.addEventListener("visibilitychange", onVisibilityChange);
+                        window.addEventListener("online", onOnline);
+                        window.addEventListener("pageshow", onPageShow);
+                        return () => {
+                            document.removeEventListener("visibilitychange", onVisibilityChange);
+                            window.removeEventListener("online", onOnline);
+                            window.removeEventListener("pageshow", onPageShow);
+                        };
+                    })()
+                    : () => { };
+                const sseCtx = { endpoint: "out", chatId };
+                const fetchOverride = this.fetchOverride;
+                const sseFetchClient = fetchOverride
+                    ? ((input, init) => {
+                        if (typeof input === "string") {
+                            return fetchOverride(input, init ?? {}, sseCtx);
+                        }
+                        if (input instanceof URL) {
+                            return fetchOverride(input.toString(), init ?? {}, sseCtx);
+                        }
+                        // Request — preserve its url + intrinsic init, let any
+                        // provided init override on top (matches fetch(Request, init)
+                        // semantics).
+                        return fetchOverride(input.url, {
+                            method: input.method,
+                            headers: input.headers,
+                            signal: input.signal,
+                            ...(init ?? {}),
+                        }, sseCtx);
+                    })
+                    : undefined;
+                const connectSseOnce = async (token) => {
+                    const subscription = new v3_1.SSEStreamSubscription(streamUrl, {
+                        headers: {
+                            Authorization: `Bearer ${token}`,
+                            ...this.extraHeaders,
+                            ...(options?.peekSettled ? { "X-Peek-Settled": "1" } : {}),
+                        },
+                        signal: combinedSignal,
+                        timeoutInSeconds: this.streamTimeoutSeconds,
+                        lastEventId: state.lastEventId,
+                        // Catch silent-dead-socket: if no chunk (or server
+                        // keepalive) arrives in 60s, force reconnect. Sized
+                        // generously over typical agent thinking pauses.
+                        stallTimeoutMs: 60_000,
+                        fetchClient: sseFetchClient,
+                    });
+                    currentSubscription = subscription;
+                    const sseStream = await subscription.subscribe();
+                    const reader = sseStream.getReader();
+                    try {
+                        const first = await reader.read();
+                        if (first.done) {
+                            reader.releaseLock();
+                            return null;
+                        }
+                        return { reader, primed: first.value };
+                    }
+                    catch (readErr) {
+                        reader.releaseLock();
+                        throw readErr;
+                    }
+                };
+                try {
+                    let reader;
+                    let primed;
+                    try {
+                        const opened = await connectSseOnce(state.publicAccessToken);
+                        if (opened === null) {
+                            controller.close();
+                            return;
+                        }
+                        reader = opened.reader;
+                        primed = opened.primed;
+                    }
+                    catch (e) {
+                        if (isAuthError(e)) {
+                            const fresh = await this.resolveAccessToken({ chatId });
+                            state.publicAccessToken = fresh;
+                            this.notifySessionChange(chatId, state);
+                            const opened = await connectSseOnce(fresh);
+                            if (opened === null) {
+                                controller.close();
+                                return;
+                            }
+                            reader = opened.reader;
+                            primed = opened.primed;
+                        }
+                        else {
+                            throw e;
+                        }
+                    }
+                    while (true) {
+                        let value;
+                        if (primed !== undefined) {
+                            value = primed;
+                            primed = undefined;
+                        }
+                        else {
+                            const next = await reader.read();
+                            if (next.done) {
+                                controller.close();
+                                return;
+                            }
+                            value = next.value;
+                        }
+                        if (combinedSignal.aborted) {
+                            internalAbort.abort();
+                            await reader.cancel();
+                            controller.close();
+                            return;
+                        }
+                        if (value.id)
+                            state.lastEventId = value.id;
+                        // Trigger control record (turn-complete, upgrade-required) —
+                        // routed by header, body is empty. Detect via the
+                        // `trigger-control` header on the SSE record. Data records
+                        // (UIMessageChunks) fall through to the chunk path below.
+                        //
+                        // Cross-version bridge: a customer who redeploys their
+                        // Next.js app (new browser SDK) before their next
+                        // `trigger deploy` (old agent SDK still writing turn-complete
+                        // / upgrade-required as `chunk.type` data records) would
+                        // otherwise hang. Fall back to the legacy chunk-type form
+                        // when no header is present so the deploy-skew window
+                        // closes turns correctly.
+                        let controlValue = (0, v3_1.controlSubtype)(value.headers);
+                        let legacyChunk;
+                        if (!controlValue && value.chunk && typeof value.chunk === "object") {
+                            const chunk = value.chunk;
+                            if (chunk.type === "trigger:turn-complete") {
+                                controlValue = v3_1.TRIGGER_CONTROL_SUBTYPE.TURN_COMPLETE;
+                                legacyChunk = chunk;
+                            }
+                            else if (chunk.type === "trigger:upgrade-required") {
+                                controlValue = v3_1.TRIGGER_CONTROL_SUBTYPE.UPGRADE_REQUIRED;
+                            }
+                            else if (typeof chunk.type === "string" && chunk.type.startsWith("trigger:")) {
+                                // Future / unknown `trigger:*` legacy control type from
+                                // a pre-upgrade agent — drop so it doesn't reach the AI
+                                // SDK as an unrecognised UIMessageChunk.
+                                continue;
+                            }
+                        }
+                        if (state.skipToTurnComplete) {
+                            if (controlValue === v3_1.TRIGGER_CONTROL_SUBTYPE.TURN_COMPLETE) {
+                                state.skipToTurnComplete = false;
+                            }
+                            continue;
+                        }
+                        if (controlValue === v3_1.TRIGGER_CONTROL_SUBTYPE.UPGRADE_REQUIRED) {
+                            // Server has already triggered the new run via
+                            // `end-and-continue`; the next chunks on this same `.out`
+                            // stream come from v2. Filter the marker for cleanliness
+                            // and keep reading.
+                            continue;
+                        }
+                        if (controlValue === v3_1.TRIGGER_CONTROL_SUBTYPE.TURN_COMPLETE) {
+                            const refreshedToken = (0, v3_1.headerValue)(value.headers, v3_1.PUBLIC_ACCESS_TOKEN_HEADER) ??
+                                legacyChunk?.publicAccessToken;
+                            if (refreshedToken) {
+                                state.publicAccessToken = refreshedToken;
+                            }
+                            state.isStreaming = false;
+                            this.notifySessionChange(chatId, state);
+                            this.coordinator?.release(chatId);
+                            this.coordinator?.broadcastSession(chatId, {
+                                lastEventId: state.lastEventId,
+                            });
+                            if (this.watchMode)
+                                continue;
+                            internalAbort.abort();
+                            try {
+                                controller.close();
+                            }
+                            catch {
+                                /* already closed */
+                            }
+                            return;
+                        }
+                        // Data record — `value.chunk` is the parsed UIMessageChunk
+                        // unwrapped from the S2 record envelope (the parser does the
+                        // JSON unwrap). Drop empty/malformed payloads defensively.
+                        if (value.chunk == null)
+                            continue;
+                        controller.enqueue(value.chunk);
+                    }
+                }
+                catch (error) {
+                    if (error instanceof Error && error.name === "AbortError") {
+                        try {
+                            controller.close();
+                        }
+                        catch {
+                            /* already closed */
+                        }
+                        return;
+                    }
+                    controller.error(error);
+                }
+                finally {
+                    teardownWakeListeners();
+                    this.activeStreams.delete(chatId);
+                    this.coordinator?.release(chatId);
+                }
+            },
+        });
+    }
+}
+exports.TriggerChatTransport = TriggerChatTransport;
+/**
+ * Convenience constructor matching {@link TriggerChatTransport}.
+ */
+function createChatTransport(options) {
+    return new TriggerChatTransport(options);
+}
+// Server-side agent chat re-exports.
+var chat_client_js_1 = require("./chat-client.js");
+Object.defineProperty(exports, "AgentChat", { enumerable: true, get: function () { return chat_client_js_1.AgentChat; } });
+Object.defineProperty(exports, "ChatStream", { enumerable: true, get: function () { return chat_client_js_1.ChatStream; } });
+//# sourceMappingURL=chat.js.map