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

package/dist/esm/v3/chat.d.ts

@@ -0,0 +1,437 @@
+/**
+ * @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 }),
+ *     }),
+ *   });
+ * }
+ * ```
+ */
+import type { ChatTransport, UIMessage, UIMessageChunk, ChatRequestOptions } from "ai";
+/**
+ * Discriminator passed to per-endpoint `baseURL` and `fetch` callbacks.
+ *
+ * - `"in"` — `POST /realtime/v1/sessions/{chatId}/in/append` (user messages,
+ *   stops, actions).
+ * - `"out"` — `GET /realtime/v1/sessions/{chatId}/out` (SSE response stream).
+ *
+ * Other endpoints (`/api/v1/sessions`, `/api/v1/auth/jwt/claims`) are reached
+ * from the server-side `chat.createStartSessionAction` and `accessToken`
+ * callback, not the transport — they accept the same callback shape on their
+ * own option objects.
+ */
+export type ChatTransportEndpoint = "in" | "out";
+/** Context passed to `baseURL` and `fetch` callbacks. */
+export type ChatTransportEndpointContext = {
+    endpoint: ChatTransportEndpoint;
+    chatId: string;
+};
+/** Resolver form of `baseURL` — return the base for the given endpoint. */
+export type ChatBaseURLResolver = (ctx: ChatTransportEndpointContext) => string;
+/**
+ * Per-request fetch override. Receives the fully-resolved URL and the
+ * RequestInit the transport would have used, plus endpoint context for
+ * routing decisions. Customers can rewrite the URL, inject headers, or
+ * delegate to a custom transport (e.g. a Cloudflare worker fronting
+ * `api.trigger.dev`). Must return a `Response` semantically equivalent to
+ * what `globalThis.fetch(url, init)` would have returned.
+ */
+export type ChatFetchOverride = (url: string, init: RequestInit, ctx: ChatTransportEndpointContext) => Promise<Response>;
+/**
+ * Arguments for the `accessToken` callback. The transport invokes this
+ * whenever it needs a fresh session-scoped PAT — initial use, and
+ * after a 401 from any session-PAT-authed request.
+ *
+ * The callback's job is to return a token, not to start a run.
+ * Customers whose implementation also creates the session (typical for
+ * `chat.createStartSessionAction` server actions) own the trigger
+ * payload server-side — they know their own user/context and don't
+ * need anything from the browser to populate `basePayload.metadata`.
+ */
+export type AccessTokenParams = {
+    /** Conversation id — same value passed to `sendMessage` / `useChat`. */
+    chatId: string;
+};
+/**
+ * Arguments for the `startSession` callback. The transport invokes this
+ * when it needs a session for a chatId — on `transport.preload(chatId)`,
+ * on `transport.start(chatId)`, and lazily on the first `sendMessage`
+ * for any chatId without a cached session.
+ *
+ * The callback typically wraps a server action that calls
+ * `chat.createStartSessionAction(taskId)({ chatId, clientData })`. That
+ * action is idempotent on `(env, externalId)`, so concurrent / repeat
+ * calls converge on the same session.
+ *
+ * The `clientData` field carries the transport's current `clientData`
+ * option — same value the transport merges into per-turn `metadata` on
+ * each `.in` chunk. Passing it through `startSession` makes the first
+ * run's `payload.metadata` (visible in `onPreload` / `onChatStart`)
+ * match what subsequent turns see.
+ *
+ * @typeParam TClientData – Type of the agent's `clientDataSchema` (when
+ * the transport is parameterised with `useTriggerChatTransport<typeof agent>`).
+ */
+export type StartSessionParams<TClientData = unknown> = {
+    /** The Trigger.dev task ID associated with this transport. */
+    taskId: string;
+    /** Conversation id — same value passed to `sendMessage` / `useChat`. */
+    chatId: string;
+    /**
+     * The transport's current `clientData`. Pass through to the server
+     * action's `basePayload.metadata` so the first run's `payload.metadata`
+     * matches per-turn `metadata`.
+     */
+    clientData: TClientData;
+};
+/**
+ * Result returned from the `startSession` callback. Carries the
+ * session-scoped PAT the transport caches and uses for every
+ * `.in/append`, `.out` SSE, and `end-and-continue` call afterward.
+ */
+export type StartSessionResult = {
+    /** Session-scoped PAT — `read:sessions:{chatId} + write:sessions:{chatId}`. */
+    publicAccessToken: string;
+};
+/**
+ * Public surface of {@link TriggerChatTransport}'s session state. Everything
+ * the customer should persist for resumption across page reloads. The
+ * transport addresses by `chatId` everywhere, so this is light: just a PAT,
+ * the last SSE event id, and a couple of UX-state flags.
+ */
+export type ChatSessionPersistedState = {
+    publicAccessToken: string;
+    lastEventId?: string;
+    isStreaming?: boolean;
+};
+/**
+ * Common options for the {@link TriggerChatTransport}.
+ *
+ * @typeParam TClientData – Type of the per-call client data merged into
+ * the wire payload via `metadata`. When the task uses `clientDataSchema`,
+ * pin this to the schema's input type for end-to-end type safety.
+ */
+export type TriggerChatTransportOptions<TClientData = unknown> = {
+    /**
+     * The Trigger.dev task ID this transport drives. Sessions created by
+     * `transport.start(chatId)` are bound to this task — every run the
+     * Session schedules invokes it. Threaded into `startSession` so the
+     * customer's server action knows which task to bind.
+     */
+    task: string;
+    /**
+     * Returns a fresh session-scoped PAT for an existing chat session.
+     * The transport invokes this on a 401/403 from any session-PAT-authed
+     * request — pure refresh, never creates a session.
+     *
+     * Customer implementation typically does
+     * `auth.createPublicToken({ scopes: { read: { sessions: chatId },
+     * write: { sessions: chatId } } })` server-side and returns the token.
+     *
+     * Required so the transport can recover from PAT expiry — never
+     * leaves the consumer in an unrecoverable state.
+     */
+    accessToken: (params: AccessTokenParams) => string | Promise<string>;
+    /**
+     * Creates (or no-ops on existing) a session for the given chatId, and
+     * returns the session-scoped PAT the transport will use afterward.
+     *
+     * Wraps a server action that calls
+     * `chat.createStartSessionAction(taskId)({ chatId, clientData })`.
+     * Customer's server controls authorization, the rest of the
+     * triggerConfig, and any atomic DB writes paired with session creation.
+     *
+     * The transport invokes this:
+     *   - when `transport.start(chatId)` / `transport.preload(chatId)` is called
+     *   - lazily on the first `sendMessage` for a chatId with no cached PAT
+     *
+     * Concurrent and repeat calls dedupe via an in-flight promise + the
+     * customer-side idempotency on `(env, externalId)`.
+     *
+     * Optional only when the customer fully manages session lifecycle
+     * externally (hydrating `sessions: { ... }` and never calling
+     * `start` / `preload`). Most customers should provide it.
+     */
+    startSession?: (params: StartSessionParams<TClientData extends Record<string, unknown> ? TClientData : Record<string, unknown>>) => Promise<StartSessionResult>;
+    /**
+     * Base URL for the Trigger.dev API. Either a single string applied to every
+     * endpoint, or a function called per request that picks a base URL from the
+     * endpoint discriminator and chat ID. @default "https://api.trigger.dev"
+     *
+     * @example Route appends through a proxy, SSE direct:
+     * ```ts
+     * baseURL: ({ endpoint }) =>
+     *   endpoint === "out" ? "https://api.trigger.dev" : "https://proxy.example.com",
+     * ```
+     */
+    baseURL?: string | ChatBaseURLResolver;
+    /**
+     * Base URL for the SSE stream subscription only (`GET .../sessions/{chatId}/out`).
+     * @deprecated Pass a function for `baseURL` instead and branch on
+     * `endpoint === "out"`. `streamBaseURL` continues to work for backwards
+     * compatibility and wins over `baseURL` for the SSE endpoint when both
+     * are set.
+     */
+    streamBaseURL?: string;
+    /**
+     * Optional per-request fetch override. Called with the resolved URL and the
+     * RequestInit the transport built, plus endpoint context. Use this to
+     * inject custom headers (e.g. distributed tracing), redirect via a proxy,
+     * or wrap fetch with retries/logging.
+     *
+     * @example Add a tracing header to every chat request:
+     * ```ts
+     * fetch: (url, init, ctx) => {
+     *   init.headers = new Headers(init.headers);
+     *   init.headers.set("traceparent", currentTraceparent());
+     *   return globalThis.fetch(url, init);
+     * },
+     * ```
+     */
+    fetch?: ChatFetchOverride;
+    /** Additional headers included in every API request. */
+    headers?: Record<string, string>;
+    /**
+     * Seconds to wait for the realtime stream to produce data before timing
+     * out. @default 120
+     */
+    streamTimeoutSeconds?: number;
+    /**
+     * Default client data merged into every wire `metadata`. Per-call
+     * `metadata` overrides transport-level defaults.
+     */
+    clientData?: TClientData extends Record<string, unknown> ? TClientData : Record<string, unknown>;
+    /**
+     * Restore active session state from external storage (e.g. localStorage)
+     * after a page refresh. Hydrated entries skip the start round-trip and
+     * use their `publicAccessToken` directly. On 401, the transport
+     * invokes `accessToken` to refresh.
+     */
+    sessions?: Record<string, ChatSessionPersistedState>;
+    /**
+     * Called whenever a chat session's state changes. Use this to persist
+     * state for reconnection after a page refresh — `null` is passed when
+     * the session is removed.
+     */
+    onSessionChange?: (chatId: string, session: ChatSessionPersistedState | null) => void;
+    /**
+     * Enable multi-tab coordination. When `true`, only one tab at a time
+     * can send messages to a given chatId; other tabs go read-only.
+     *
+     * No-op when `BroadcastChannel` is unavailable. @default false
+     */
+    multiTab?: boolean;
+    /**
+     * Read-only "watch" mode for observing an existing chat run from the
+     * outside (e.g. a dashboard viewer). When `true`, the SSE subscription
+     * stays open across `trigger:turn-complete` so consumers see turn 2,
+     * 3, … through one long-lived stream. Pair with `sessions` hydration
+     * and `reconnectToStream` for the typical viewer flow. @default false
+     */
+    watch?: boolean;
+    /**
+     * Opt-in URL that gives a brand-new chat a head start: instead of
+     * waiting for the trigger.dev agent run to dequeue + boot before
+     * the first LLM call, the transport POSTs the first user message
+     * to a route handler in your warm process (Next.js, etc.) that
+     * exports `chat.handover({ agentId, run })` from
+     * `@trigger.dev/sdk/chat-server`. That handler runs `streamText`
+     * step 1 right away while the agent boots in parallel, then hands
+     * off mid-turn for tool execution (or exits clean for pure-text
+     * turns).
+     *
+     * First turn only. Subsequent turns on the same chat bypass this
+     * URL and write directly to `session.in` — the same direct-trigger
+     * path used when `headStart` is unset. Customers using `headStart`
+     * still need `accessToken` and (optionally) `startSession` for
+     * those subsequent turns.
+     *
+     * NOT a stock `useChat` "endpoint" — this is not the canonical
+     * request URL for every turn, just the warm first-turn shortcut.
+     *
+     * In benchmarks, head-starting drops first-turn TTFC roughly in
+     * half versus the direct-trigger flow (cold-start agent boot +
+     * onTurnStart hook overlap with the LLM TTFB instead of stacking
+     * before it).
+     *
+     * @default undefined (direct-trigger flow on every turn)
+     */
+    headStart?: string;
+};
+/**
+ * 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.
+ */
+export declare class TriggerChatTransport implements ChatTransport<UIMessage> {
+    private readonly taskId;
+    private readonly resolveAccessToken;
+    private readonly resolveStartSession;
+    private readonly resolveBaseURLFn;
+    private readonly fetchOverride;
+    private readonly extraHeaders;
+    private readonly streamTimeoutSeconds;
+    private defaultMetadata;
+    private readonly watchMode;
+    private readonly headStart;
+    private coordinator;
+    private _onSessionChange;
+    private sessions;
+    private activeStreams;
+    private pendingStarts;
+    constructor(options: TriggerChatTransportOptions);
+    /**
+     * 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.
+     */
+    start(chatId: string): Promise<ChatSessionPersistedState>;
+    /**
+     * 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`.
+     */
+    preload(chatId: string): Promise<void>;
+    /**
+     * 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: (options: {
+        trigger: "submit-message" | "regenerate-message";
+        chatId: string;
+        messageId: string | undefined;
+        messages: UIMessage[];
+        abortSignal: AbortSignal | undefined;
+    } & ChatRequestOptions) => Promise<ReadableStream<UIMessageChunk>>;
+    /**
+     * 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.
+     */
+    private sendMessagesViaHandover;
+    /**
+     * 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: (chatId: string, message: UIMessage, metadata?: Record<string, unknown>) => Promise<boolean>;
+    /**
+     * 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: (options: {
+        chatId: string;
+        abortSignal?: AbortSignal | undefined;
+    } & ChatRequestOptions) => Promise<ReadableStream<UIMessageChunk> | null>;
+    /**
+     * Stop the current generation. Sends `{kind:"stop"}` on `.in`; the
+     * agent aborts its `streamText` call but stays alive for the next
+     * message.
+     */
+    stopGeneration: (chatId: string) => Promise<boolean>;
+    /**
+     * 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: (chatId: string, action: unknown) => Promise<ReadableStream<UIMessageChunk>>;
+    getSession: (chatId: string) => ChatSessionPersistedState | undefined;
+    setSession(chatId: string, session: ChatSessionPersistedState): void;
+    setOnSessionChange(callback: ((chatId: string, session: ChatSessionPersistedState | null) => void) | undefined): void;
+    /**
+     * 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: Record<string, unknown> | undefined): void;
+    isReadOnly(chatId: string): boolean;
+    hasClaim(chatId: string): boolean;
+    addReadOnlyListener(fn: (chatId: string, isReadOnly: boolean) => void): void;
+    removeReadOnlyListener(fn: (chatId: string, isReadOnly: boolean) => void): void;
+    broadcastMessages(chatId: string, messages: unknown[]): void;
+    addMessagesListener(fn: (chatId: string, messages: unknown[]) => void): void;
+    removeMessagesListener(fn: (chatId: string, messages: unknown[]) => void): void;
+    dispose(): void;
+    private serializeInputChunk;
+    private toPersisted;
+    private notifySessionChange;
+    /**
+     * 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.
+     */
+    private ensureSessionState;
+    private doStart;
+    /**
+     * 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.
+     */
+    private resolveBaseURL;
+    private doFetch;
+    private appendInputChunk;
+    private callWithAuthRetry;
+    /**
+     * 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`).
+     */
+    private subscribeToSessionStream;
+}
+/**
+ * Convenience constructor matching {@link TriggerChatTransport}.
+ */
+export declare function createChatTransport(options: TriggerChatTransportOptions): TriggerChatTransport;
+export { AgentChat, ChatStream, type AgentChatOptions, type ChatSession, type ChatStreamResult, type ChatToolCall, type ChatToolResult, type InferChatClientData, type InferChatUIMessage, } from "./chat-client.js";