@trigger.dev/sdk 0.0.0-prerelease-20260911094758 → 0.0.0-prerelease-windows-bundle-fix-20260928100448

package/dist/commonjs/v3/ai.d.ts

@@ -149,6 +149,41 @@ export declare const ai: {
  * ```
  */
 declare function createChatAccessToken<TTask extends AnyTask>(taskId: TaskIdentifier<TTask>): Promise<string>;
+/**
+ * Register work that must land before anything from this turn reaches the
+ * frontend.
+ *
+ * Like {@link chatDefer} the work starts immediately and is never awaited by
+ * the hook that registered it, so it runs alongside the model and costs no
+ * time to first token. Unlike `chat.defer`, the output stream waits for it:
+ * no chunk of the answer is written to the session until it settles. That
+ * makes it the right home for a write the next page load has to see (a
+ * conversation row, a message insert), because a reader that can see the
+ * answer can also see what the write persisted.
+ *
+ * Reach for `chat.defer` instead when the timing does not matter for a
+ * reload: analytics, audit logs, search-index updates.
+ *
+ * This is not a consistency barrier for the turn. The work is still in flight
+ * while the model runs, so a tool, a `prepareStep`, or anything else executing
+ * during the turn can still read the state as it was before the write. It
+ * orders the write against what the frontend can see, nothing more. When the
+ * turn's own code has to read the write back, `await` it instead and accept
+ * the cost.
+ *
+ * A write registered here that fails, or outlasts the internal timeout, lets
+ * the stream through rather than stalling the conversation.
+ *
+ * @example
+ * ```ts
+ * onTurnStart: async ({ chatId, uiMessages }) => {
+ *   chat.deferBeforeOutput(
+ *     db.chat.update({ where: { id: chatId }, data: { messages: uiMessages } })
+ *   );
+ * },
+ * ```
+ */
+declare function chatDeferBeforeOutput(promiseOrFn: Promise<unknown> | (() => Promise<unknown>)): void;
 /**
  * A stream writer passed to chat lifecycle callbacks (`onPreload`, `onChatStart`,
  * `onTurnStart`, `onTurnComplete`, `onCompacted`).
@@ -380,6 +415,8 @@ export type ChatNewToolResult = {
 interface CompactionState {
     summary: string;
     baseResponseMessageCount: number;
+    /** Completed steps summarized this turn; unlike message counts, matches UI step markers. */
+    baseResponseStepCount: number;
 }
 /**
  * Event passed to `summarize` callbacks.
@@ -632,14 +669,24 @@ export type CompactedEvent = {
 export type ShouldCompactEvent = {
     /** The current model messages (full conversation). */
     messages: ModelMessage[];
-    /** Total token count from the triggering step/turn. */
+    /**
+     * Total token count of the triggering model call: the step that just finished
+     * (`"inner"`), or the turn's LAST step (`"outer"`). This is the size of the
+     * context the model held on that call, which is what a compaction decision is
+     * about. It is never the sum over a multi-step turn; see `turnUsage` for that.
+     */
     totalTokens: number | undefined;
-    /** Input token count from the triggering step/turn. */
+    /** Input token count of the triggering model call (see `totalTokens`). */
     inputTokens: number | undefined;
-    /** Output token count from the triggering step/turn. */
+    /** Output token count of the triggering model call (see `totalTokens`). */
     outputTokens: number | undefined;
-    /** Full usage object from the triggering step/turn. */
+    /** Full usage object of the triggering model call (see `totalTokens`). */
     usage?: LanguageModelUsage;
+    /**
+     * The whole turn's usage summed over every step, as the provider billed it.
+     * Only present when `source` is `"outer"`.
+     */
+    turnUsage?: LanguageModelUsage;
     /** Cumulative token usage across all completed turns. Present in chat.agent contexts. */
     totalUsage?: LanguageModelUsage;
     /** The chat session ID (if running inside a chat.agent). */
@@ -943,7 +990,7 @@ type AiStreamTextFn = typeof aiStreamTextSignature;
  * them: `function loop(messages: ModelMessage[], streamText: ChatStreamText)`.
  */
 export type ChatStreamText = AiStreamTextFn;
-declare function toStreamTextOptions(options?: ToStreamTextOptionsOptions): Record<string, unknown>;
+declare function toStreamTextOptions(options?: ToStreamTextOptionsOptions, retain?: boolean): Record<string, unknown>;
 /**
  * Options for `pipeChat`.
  */
@@ -1058,7 +1105,9 @@ declare function chatTurn(): ActionTurn;
  * }
  * ```
  */
-declare function pipeChat(source: UIMessageStreamable | AsyncIterable<unknown> | ReadableStream<unknown>, options?: PipeChatOptions): Promise<void>;
+declare function pipeChat(source: UIMessageStreamable | AsyncIterable<unknown> | ReadableStream<unknown>, options?: PipeChatOptions, capture?: {
+    originalMessages?: UIMessage[];
+}): Promise<void>;
 /**
  * Options for defining a chat task.
  *
@@ -1409,13 +1458,17 @@ export type TurnCompleteEvent<TClientData = unknown, TUIM extends UIMessage = UI
      */
     uiMessages: TUIM[];
     /**
-     * Only the new model messages from this turn (user message(s) + assistant response).
-     * Useful for appending to an existing conversation record.
+     * Model messages for this turn's user message(s) and complete assistant response,
+     * including steps summarized during the turn. Same-ID approval and handover
+     * continuations include the full replacement response, so these are not always
+     * an append-only delta. Persist `messages` for future model context, or upsert
+     * `newUIMessages` by ID for the visible conversation.
      */
     newMessages: ModelMessage[];
     /**
-     * Only the new UI messages from this turn (user message(s) + assistant response).
-     * Useful for inserting individual message records instead of overwriting the full history.
+     * New or updated UI messages from this turn (user message(s) + assistant response).
+     * Upsert by message ID: approval and handover continuations can replace an
+     * existing assistant message.
      */
     newUIMessages: TUIM[];
     /** The assistant's response for this turn, with aborted parts cleaned up when `stopped` is true. Undefined if `pipeChat` was used manually. */
@@ -2864,8 +2917,11 @@ declare class ChatMessageAccumulator {
     modelMessages: ModelMessage[];
     uiMessages: UIMessage[];
     private _compaction?;
+    /** The run a spliced head-start partial contributed, until its response replaces it. */
+    private _handoverRun?;
     private _pendingMessages?;
     private _steeringQueue;
+    private _pendingSteer;
     constructor(options?: {
         compaction?: ChatAgentCompactionOptions;
         pendingMessages?: PendingMessagesOptions;
@@ -2960,8 +3016,10 @@ declare class ChatMessageAccumulator {
     } | undefined>) | undefined;
     /**
      * Run outer-loop compaction if needed. Call after adding the response
-     * and capturing usage. Applies `compactModelMessages` and `compactUIMessages`
-     * callbacks if configured.
+     * and capturing usage. Pass the LAST step's usage (`result.usage`), which is
+     * the context the model held on its final call; `result.totalUsage` sums every
+     * step of a tool-using turn and belongs in `context.turnUsage`. Applies
+     * `compactModelMessages` and `compactUIMessages` callbacks if configured.
      *
      * @returns `true` if compaction was performed, `false` otherwise.
      */
@@ -2969,6 +3027,8 @@ declare class ChatMessageAccumulator {
         chatId?: string;
         turn?: number;
         clientData?: unknown;
+        /** The whole turn summed over its steps (`result.totalUsage`). */
+        turnUsage?: LanguageModelUsage;
         totalUsage?: LanguageModelUsage;
     }): Promise<boolean>;
 }
@@ -3382,6 +3442,7 @@ export declare const chat: {
     cleanupAbortedParts: typeof cleanupAbortedParts;
     /** Register background work that runs in parallel with streaming. See {@link chatDefer}. */
     defer: typeof chatDefer;
+    deferBeforeOutput: typeof chatDeferBeforeOutput;
     /** Queue model messages for injection at the next `prepareStep` boundary. See {@link injectBackgroundContext}. */
     inject: typeof injectBackgroundContext;
     /** Typed chat output stream for writing custom chunks or piping from subtasks. */