@trigger.dev/sdk 0.0.0-prerelease-20260310150337 → 0.0.0-prerelease-20260325143642

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

@@ -1,7 +1,8 @@
 import { AnyTask, Task, type inferSchemaIn, type inferSchemaOut, type TaskIdentifier, type TaskOptions, type TaskSchema, type TaskWithSchema } from "@trigger.dev/core/v3";
-import type { ModelMessage, UIMessage, UIMessageChunk, UIMessageStreamOptions } from "ai";
+import type { ModelMessage, UIMessage, UIMessageChunk, UIMessageStreamOptions, LanguageModelUsage } from "ai";
 import { Tool } from "ai";
 import { locals } from "./locals.js";
+import type { ResolvedPrompt } from "./prompt.js";
 import { CHAT_MESSAGES_STREAM_ID, CHAT_STOP_STREAM_ID } from "./chat-constants.js";
 export type ToolCallExecutionOptions = {
     toolCallId: string;
@@ -110,8 +111,8 @@ export type ChatTaskWirePayload<TMessage extends UIMessage = UIMessage, TMetadat
     continuation?: boolean;
     /** The run ID of the previous run (only set when `continuation` is true). */
     previousRunId?: string;
-    /** Override warm timeout for this run (seconds). Set by transport.preload(). */
-    warmTimeoutInSeconds?: number;
+    /** Override idle timeout for this run (seconds). Set by transport.preload(). */
+    idleTimeoutInSeconds?: number;
 };
 /**
  * The payload shape passed to the `chatTask` run function.
@@ -161,7 +162,467 @@ export type ChatTaskSignals = {
  * The full payload passed to a `chatTask` run function.
  * Extends `ChatTaskPayload` (the wire payload) with abort signals.
  */
-export type ChatTaskRunPayload<TClientData = unknown> = ChatTaskPayload<TClientData> & ChatTaskSignals;
+export type ChatTaskRunPayload<TClientData = unknown> = ChatTaskPayload<TClientData> & ChatTaskSignals & {
+    /** Token usage from the previous turn. Undefined on turn 0. */
+    previousTurnUsage?: LanguageModelUsage;
+    /** Cumulative token usage across all completed turns so far. */
+    totalUsage: LanguageModelUsage;
+};
+/** Convenience re-export of the AI SDK's `LanguageModelUsage` type. */
+export type ChatTurnUsage = LanguageModelUsage;
+/**
+ * Replace the accumulated conversation messages for the current run.
+ *
+ * Call from `onTurnStart` to compact before `run()` executes, or from
+ * `onTurnComplete` to compact before the next turn. Takes `UIMessage[]`
+ * and converts to `ModelMessage[]` internally.
+ */
+declare function setChatMessages(uiMessages: UIMessage[]): void;
+/** State stored in locals during prepareStep compaction. */
+interface CompactionState {
+    summary: string;
+    baseResponseMessageCount: number;
+}
+/**
+ * Event passed to `summarize` callbacks.
+ */
+export type SummarizeEvent = {
+    /** The current model messages to summarize. */
+    messages: ModelMessage[];
+    /** Full usage object from the triggering step/turn. */
+    usage?: LanguageModelUsage;
+    /** Cumulative token usage across all completed turns. Present in chat.task contexts. */
+    totalUsage?: LanguageModelUsage;
+    /** The chat session ID (if running inside a chat.task). */
+    chatId?: string;
+    /** The current turn number (0-indexed, if inside a chat.task). */
+    turn?: number;
+    /** Custom data from the frontend (if inside a chat.task). */
+    clientData?: unknown;
+    /**
+     * Where compaction is running:
+     * - `"inner"` — between tool-call steps (prepareStep)
+     * - `"outer"` — between turns
+     */
+    source?: "inner" | "outer";
+    /** The step number (0-indexed). Only present when `source` is `"inner"`. */
+    stepNumber?: number;
+};
+/**
+ * Event passed to `compactUIMessages` and `compactModelMessages` callbacks.
+ */
+export type CompactMessagesEvent = {
+    /** The generated summary text. */
+    summary: string;
+    /** The current UI messages (full conversation). */
+    uiMessages: UIMessage[];
+    /** The current model messages (full conversation). */
+    modelMessages: ModelMessage[];
+    /** The chat session ID. */
+    chatId: string;
+    /** The current turn number (0-indexed). */
+    turn: number;
+    /** Custom data from the frontend. */
+    clientData?: unknown;
+    /**
+     * Where compaction is running:
+     * - `"inner"` — between tool-call steps (prepareStep)
+     * - `"outer"` — between turns
+     */
+    source: "inner" | "outer";
+};
+/**
+ * Options for the `compaction` field on `chat.task()`.
+ *
+ * Handles compaction automatically in both the inner loop (prepareStep, between
+ * tool-call steps) and the outer loop (between turns, for single-step responses
+ * where prepareStep never fires).
+ */
+export type ChatTaskCompactionOptions = {
+    /** Decide whether to compact. Return true to trigger compaction. */
+    shouldCompact: (event: ShouldCompactEvent) => boolean | Promise<boolean>;
+    /** Generate a summary from the current messages. Return the summary text. */
+    summarize: (event: SummarizeEvent) => Promise<string>;
+    /**
+     * Transform UI messages after compaction (what gets persisted and displayed).
+     * Default: preserve all UI messages unchanged.
+     *
+     * @example
+     * ```ts
+     * // Flatten to summary
+     * compactUIMessages: ({ summary }) => [{
+     *   id: generateId(), role: "assistant",
+     *   parts: [{ type: "text", text: `[Summary]\n\n${summary}` }],
+     * }],
+     *
+     * // Summary + keep last 4 messages
+     * compactUIMessages: ({ uiMessages, summary }) => [
+     *   { id: generateId(), role: "assistant",
+     *     parts: [{ type: "text", text: `[Summary]\n\n${summary}` }] },
+     *   ...uiMessages.slice(-4),
+     * ],
+     * ```
+     */
+    compactUIMessages?: (event: CompactMessagesEvent) => UIMessage[] | Promise<UIMessage[]>;
+    /**
+     * Transform model messages after compaction (what gets sent to the LLM).
+     * Default: replace all with a single summary message.
+     *
+     * @example
+     * ```ts
+     * // Summary + keep last 2 model messages
+     * compactModelMessages: ({ modelMessages, summary }) => [
+     *   { role: "user", content: summary },
+     *   ...modelMessages.slice(-2),
+     * ],
+     * ```
+     */
+    compactModelMessages?: (event: CompactMessagesEvent) => ModelMessage[] | Promise<ModelMessage[]>;
+};
+/**
+ * Event passed to `shouldInject` and `prepareMessages` callbacks.
+ */
+export type PendingMessagesBatchEvent = {
+    /** All pending UI messages that arrived during streaming (batch). */
+    messages: UIMessage[];
+    /** Current model messages in the conversation. */
+    modelMessages: ModelMessage[];
+    /** Completed steps so far. */
+    steps: CompactionStep[];
+    /** Current step number (0-indexed). */
+    stepNumber: number;
+    /** Chat session ID. */
+    chatId: string;
+    /** Current turn number (0-indexed). */
+    turn: number;
+    /** Custom data from the frontend. */
+    clientData?: unknown;
+};
+/**
+ * Event passed to `onReceived` callback (per-message, as they arrive).
+ */
+export type PendingMessageReceivedEvent = {
+    /** The UI message that arrived during streaming. */
+    message: UIMessage;
+    /** Chat session ID. */
+    chatId: string;
+    /** Current turn number (0-indexed). */
+    turn: number;
+};
+/**
+ * Event passed to `onInjected` callback (batch, after injection).
+ */
+export type PendingMessagesInjectedEvent = {
+    /** All UI messages that were injected. */
+    messages: UIMessage[];
+    /** The model messages that were injected. */
+    injectedModelMessages: ModelMessage[];
+    /** Chat session ID. */
+    chatId: string;
+    /** Current turn number (0-indexed). */
+    turn: number;
+    /** Step number where injection occurred. */
+    stepNumber: number;
+};
+/**
+ * Options for the `pendingMessages` field on `chat.task()`, `chat.createSession()`,
+ * or `ChatMessageAccumulator`.
+ *
+ * Configures how messages that arrive during streaming are handled. When
+ * `shouldInject` is provided and returns `true`, the full batch of pending
+ * messages is injected between tool-call steps via `prepareStep`.
+ * Otherwise, messages queue for the next turn.
+ */
+export type PendingMessagesOptions = {
+    /**
+     * Decide whether to inject pending messages between tool-call steps.
+     * Called once per step boundary with the full batch of pending messages.
+     * If absent, no injection happens — messages only queue for the next turn.
+     */
+    shouldInject?: (event: PendingMessagesBatchEvent) => boolean | Promise<boolean>;
+    /**
+     * Transform the batch of pending messages before injection.
+     * Return the model messages to inject.
+     * Default: convert each UI message via `convertToModelMessages`.
+     */
+    prepare?: (event: PendingMessagesBatchEvent) => ModelMessage[] | Promise<ModelMessage[]>;
+    /** Called when a message arrives during streaming (per-message). */
+    onReceived?: (event: PendingMessageReceivedEvent) => void | Promise<void>;
+    /** Called after a batch of messages is injected via `prepareStep`. */
+    onInjected?: (event: PendingMessagesInjectedEvent) => void | Promise<void>;
+};
+/**
+ * The data part type used to signal that pending messages were injected
+ * between tool-call steps. The frontend can match on this to render
+ * injection points inline in the assistant response.
+ */
+export declare const PENDING_MESSAGE_INJECTED_TYPE: "data-pending-message-injected";
+/**
+ * Event passed to the `prepareMessages` hook.
+ */
+export type PrepareMessagesEvent<TClientData = unknown> = {
+    /** The messages to transform. Return the transformed array. */
+    messages: ModelMessage[];
+    /** Why messages are being prepared. */
+    reason: "run" | "compaction-rebuild" | "compaction-result";
+    /** The chat session ID. */
+    chatId: string;
+    /** The current turn number (0-indexed). */
+    turn: number;
+    /** Custom data from the frontend. */
+    clientData?: TClientData;
+};
+/**
+ * Data shape for `data-compaction` stream chunks emitted during compaction.
+ * Use to type the `data` field when rendering compaction parts in the frontend.
+ */
+export type CompactionChunkData = {
+    status: "compacting" | "complete";
+    totalTokens: number | undefined;
+};
+/**
+ * Event passed to the `onCompacted` callback.
+ */
+export type CompactedEvent = {
+    /** The generated summary text. */
+    summary: string;
+    /** The messages that were compacted (pre-compaction). */
+    messages: ModelMessage[];
+    /** Number of messages before compaction. */
+    messageCount: number;
+    /** Token usage from the step that triggered compaction. */
+    usage: LanguageModelUsage;
+    /** Total token count that triggered compaction. */
+    totalTokens: number | undefined;
+    /** Input token count from the triggering step. */
+    inputTokens: number | undefined;
+    /** Output token count from the triggering step. */
+    outputTokens: number | undefined;
+    /** The step number where compaction occurred (0-indexed). */
+    stepNumber: number;
+    /** The chat session ID (if running inside a chat.task). */
+    chatId?: string;
+    /** The current turn number (if running inside a chat.task). */
+    turn?: number;
+};
+/**
+ * Event passed to `shouldCompact` callbacks.
+ */
+export type ShouldCompactEvent = {
+    /** The current model messages (full conversation). */
+    messages: ModelMessage[];
+    /** Total token count from the triggering step/turn. */
+    totalTokens: number | undefined;
+    /** Input token count from the triggering step/turn. */
+    inputTokens: number | undefined;
+    /** Output token count from the triggering step/turn. */
+    outputTokens: number | undefined;
+    /** Full usage object from the triggering step/turn. */
+    usage?: LanguageModelUsage;
+    /** Cumulative token usage across all completed turns. Present in chat.task contexts. */
+    totalUsage?: LanguageModelUsage;
+    /** The chat session ID (if running inside a chat.task). */
+    chatId?: string;
+    /** The current turn number (0-indexed, if inside a chat.task). */
+    turn?: number;
+    /** Custom data from the frontend (if inside a chat.task). */
+    clientData?: unknown;
+    /**
+     * Where this check is running:
+     * - `"inner"` — between tool-call steps (prepareStep)
+     * - `"outer"` — between turns (after response, before onBeforeTurnComplete)
+     */
+    source?: "inner" | "outer";
+    /** The step number (0-indexed). Only present when `source` is `"inner"`. */
+    stepNumber?: number;
+    /** The steps array from prepareStep. Only present when `source` is `"inner"`. */
+    steps?: CompactionStep[];
+};
+/**
+ * Options for `chat.compaction()` — the high-level prepareStep factory.
+ */
+export type CompactionOptions = {
+    /** Generate a summary from the current messages. Return the summary text. */
+    summarize: (messages: ModelMessage[]) => Promise<string>;
+    /** Token threshold — compact when totalTokens exceeds this. Ignored if `shouldCompact` is provided. */
+    threshold?: number;
+    /** Custom compaction trigger. When provided, used instead of `threshold`. */
+    shouldCompact?: (event: ShouldCompactEvent) => boolean | Promise<boolean>;
+};
+/** A step object as received in prepareStep's `steps` array. */
+export type CompactionStep = {
+    usage: LanguageModelUsage;
+    finishReason: string;
+    content: Array<{
+        type: string;
+        toolCallId?: string;
+    }>;
+    response: {
+        messages: Array<any>;
+    };
+};
+/**
+ * Result of `chat.compact()`. Discriminated union so you can inspect
+ * what happened, but also directly compatible with prepareStep's return type.
+ *
+ * - `"skipped"` — no compaction needed (first step, boundary unsafe, or under threshold). Return `undefined` to prepareStep.
+ * - `"rebuilt"` — previous compaction exists, messages rebuilt from summary + new response messages.
+ * - `"compacted"` — compaction just happened, includes the generated summary.
+ */
+export type CompactResult = {
+    type: "skipped";
+} | {
+    type: "rebuilt";
+    messages: ModelMessage[];
+} | {
+    type: "compacted";
+    messages: ModelMessage[];
+    summary: string;
+};
+/**
+ * Options for `chat.compact()` — the low-level compaction function.
+ */
+export type CompactOptions = {
+    /** Generate a summary from the current messages. Return the summary text. */
+    summarize: (messages: ModelMessage[]) => Promise<string>;
+    /** Token threshold — compact when totalTokens exceeds this. Ignored if `shouldCompact` is provided. */
+    threshold?: number;
+    /** Custom compaction trigger. When provided, used instead of `threshold`. */
+    shouldCompact?: (event: ShouldCompactEvent) => boolean | Promise<boolean>;
+};
+/**
+ * Read the current compaction state. Returns the summary and base message count
+ * if compaction has occurred in this turn, or `undefined` if not.
+ *
+ * Use in a custom `prepareStep` to rebuild from a previous compaction:
+ * ```ts
+ * const state = chat.getCompactionState();
+ * if (state) {
+ *   return { messages: [{ role: "user", content: state.summary }, ...newMsgs] };
+ * }
+ * ```
+ */
+declare function getCompactionState(): CompactionState | undefined;
+/**
+ * Low-level compaction for use inside a custom `prepareStep`.
+ *
+ * Handles the full decision tree: first step, already-compacted rebuild,
+ * boundary safety, threshold check, summarization, stream chunks, state
+ * storage, and accumulator update.
+ *
+ * Returns a `CompactResult` — inspect `result.type` to see what happened,
+ * or convert to a prepareStep return with `result.type === "skipped" ? undefined : result`.
+ *
+ * @example
+ * ```ts
+ * prepareStep: async ({ messages, steps }) => {
+ *   // your custom logic here...
+ *   const result = await chat.compact(messages, steps, {
+ *     threshold: 80_000,
+ *     summarize: async (msgs) => generateText({ model, messages: msgs }).then(r => r.text),
+ *   });
+ *   if (result.type === "compacted") {
+ *     logger.info("Compacted!", { summary: result.summary });
+ *   }
+ *   return result.type === "skipped" ? undefined : result;
+ * },
+ * ```
+ */
+declare function chatCompact(messages: ModelMessage[], steps: CompactionStep[], options: CompactOptions): Promise<CompactResult>;
+/**
+ * Returns a `prepareStep` function that handles context compaction automatically.
+ *
+ * Monitors token usage between tool-call steps. When `totalTokens` exceeds
+ * the threshold, generates a summary via `summarize()`, replaces the message
+ * history, and emits `data-compaction` stream chunks for the frontend.
+ *
+ * @example
+ * ```ts
+ * return streamText({
+ *   ...chat.toStreamTextOptions({ registry }),
+ *   messages: chat.addCacheBreaks(messages),
+ *   prepareStep: chat.compactionStep({
+ *     threshold: 80_000,
+ *     summarize: async (messages) => {
+ *       return generateText({ model, messages: [...messages, { role: "user", content: "Summarize." }] })
+ *         .then((r) => r.text);
+ *     },
+ *   }),
+ *   tools: { ... },
+ * });
+ * ```
+ */
+declare function chatCompactionStep(options: CompactionOptions): (args: {
+    messages: ModelMessage[];
+    steps: CompactionStep[];
+}) => Promise<{
+    messages: ModelMessage[];
+} | undefined>;
+/**
+ * Checks whether it's safe to compact the message history. Returns `false`
+ * if any tool calls are in-flight (incomplete tool invocations without results).
+ *
+ * Call before `chat.setMessages()` to avoid corrupting tool-call state.
+ */
+declare function isCompactionSafe(messages: UIMessage[]): boolean;
+/**
+ * A resolved prompt stored via `chat.prompt.set()`. Either a full `ResolvedPrompt`
+ * from `prompts.define().resolve()`, or a lightweight wrapper around a plain string.
+ */
+export type ChatPromptValue = ResolvedPrompt | {
+    text: string;
+    model: undefined;
+    config: undefined;
+    promptId: string;
+    version: number;
+    labels: string[];
+    toAISDKTelemetry: (additionalMetadata?: Record<string, string>) => {
+        experimental_telemetry: {
+            isEnabled: true;
+            metadata: Record<string, string>;
+        };
+    };
+};
+/**
+ * Store a resolved prompt (or plain string) for the current run.
+ * Call from any hook (`onPreload`, `onChatStart`, `onTurnStart`) or `run()`.
+ */
+declare function setChatPrompt(resolved: ResolvedPrompt | string): void;
+/**
+ * Read the stored prompt. Throws if `chat.prompt.set()` has not been called.
+ */
+declare function getChatPrompt(): ChatPromptValue;
+/**
+ * Options for {@link toStreamTextOptions}.
+ */
+export type ToStreamTextOptionsOptions = {
+    /** Additional telemetry metadata merged into `experimental_telemetry.metadata`. */
+    telemetry?: Record<string, string>;
+    /**
+     * An AI SDK provider registry (from `createProviderRegistry`) or any object
+     * with a `languageModel(id)` method. When provided and the stored prompt has
+     * a `model` string, the resolved `LanguageModel` is included in the returned
+     * options so `streamText` uses it directly.
+     *
+     * The model string should use the `"provider:model-id"` format
+     * (e.g. `"openai:gpt-4o"`, `"anthropic:claude-sonnet-4-6"`).
+     */
+    registry?: {
+        languageModel(modelId: string): unknown;
+    };
+};
+/**
+ * Returns an options object ready to spread into `streamText()`.
+ *
+ * Includes `system`, `experimental_telemetry`, and any config fields
+ * (temperature, maxTokens, etc.) from the stored prompt.
+ *
+ * When a `registry` is provided and the prompt has a `model` string,
+ * the resolved `LanguageModel` is included as `model`.
+ *
+ * If no prompt has been set, returns `{}` (no-op spread).
+ */
+declare function toStreamTextOptions(options?: ToStreamTextOptionsOptions): Record<string, unknown>;
 /**
  * Options for `pipeChat`.
  */
@@ -312,6 +773,10 @@ export type TurnStartEvent<TClientData = unknown> = {
     previousRunId?: string;
     /** Whether this run was preloaded before the first message. */
     preloaded: boolean;
+    /** Token usage from the previous turn. Undefined on turn 0. */
+    previousTurnUsage?: LanguageModelUsage;
+    /** Cumulative token usage across all completed turns so far. */
+    totalUsage: LanguageModelUsage;
 };
 /**
  * Event passed to the `onTurnComplete` callback.
@@ -362,6 +827,10 @@ export type TurnCompleteEvent<TClientData = unknown> = {
     previousRunId?: string;
     /** Whether this run was preloaded before the first message. */
     preloaded: boolean;
+    /** Token usage for this turn. Undefined if usage couldn't be captured (e.g. manual pipeChat). */
+    usage?: LanguageModelUsage;
+    /** Cumulative token usage across all turns in this run (including this turn). */
+    totalUsage: LanguageModelUsage;
 };
 export type ChatTaskOptions<TIdentifier extends string, TClientDataSchema extends TaskSchema | undefined = undefined> = Omit<TaskOptions<TIdentifier, ChatTaskWirePayload, unknown>, "run"> & {
     /**
@@ -437,10 +906,83 @@ export type ChatTaskOptions<TIdentifier extends string, TClientDataSchema extend
      */
     onTurnStart?: (event: TurnStartEvent<inferSchemaOut<TClientDataSchema>>) => Promise<void> | void;
     /**
-     * Called after each turn completes (after the response is captured, before waiting
-     * for the next message). Also fires on the final turn.
+     * Called after the response is captured but before the stream closes.
+     * The stream is still open, so you can write custom chunks to the frontend
+     * (e.g. compaction progress). Use this for compaction, post-processing,
+     * or any work where the user should see real-time status updates.
+     *
+     * @example
+     * ```ts
+     * onBeforeTurnComplete: async ({ messages, uiMessages, usage }) => {
+     *   if (usage?.inputTokens && usage.inputTokens > 5000) {
+     *     await chat.stream.append({ type: "data-compaction", id: generateId(), data: { status: "compacting" } });
+     *     // ... compact messages ...
+     *     chat.setMessages(compactedMessages);
+     *     await chat.stream.append({ type: "data-compaction", id: generateId(), data: { status: "complete" } });
+     *   }
+     * }
+     * ```
+     */
+    onBeforeTurnComplete?: (event: TurnCompleteEvent<inferSchemaOut<TClientDataSchema>>) => Promise<void> | void;
+    /**
+     * Called when conversation compaction occurs (via `chat.compact()` or
+     * `chat.compactionStep()`). Use for logging, billing, or persisting the summary.
+     *
+     * @example
+     * ```ts
+     * onCompacted: async ({ summary, totalTokens, chatId }) => {
+     *   logger.info("Compacted", { totalTokens, chatId });
+     *   await db.compactionLog.create({ data: { chatId, summary } });
+     * }
+     * ```
+     */
+    onCompacted?: (event: CompactedEvent) => Promise<void> | void;
+    /**
+     * Automatic context compaction. When provided, compaction runs automatically
+     * in both the inner loop (prepareStep, between tool-call steps) and the
+     * outer loop (between turns, for single-step responses where prepareStep
+     * never fires).
      *
-     * Use this to persist the conversation to your database after each assistant response.
+     * The `shouldCompact` callback decides when to compact, and `summarize`
+     * generates the summary. The prepareStep is auto-injected into
+     * `chat.toStreamTextOptions()` — if you provide your own `prepareStep`
+     * after spreading, it overrides the auto-injected one.
+     *
+     * @example
+     * ```ts
+     * chat.task({
+     *   id: "my-chat",
+     *   compaction: {
+     *     shouldCompact: ({ totalTokens }) => (totalTokens ?? 0) > 80_000,
+     *     summarize: async (messages) =>
+     *       generateText({ model, messages: [...messages, { role: "user", content: "Summarize." }] })
+     *         .then((r) => r.text),
+     *   },
+     *   run: async ({ messages, signal }) => {
+     *     return streamText({ ...chat.toStreamTextOptions({ registry }), messages });
+     *   },
+     * });
+     * ```
+     */
+    compaction?: ChatTaskCompactionOptions;
+    /**
+     * Configure how messages that arrive during streaming are handled.
+     *
+     * By default, messages queue for the next turn. When `shouldInject` is provided
+     * and returns `true`, messages are injected between tool-call steps via
+     * `prepareStep` — allowing users to steer the agent mid-execution.
+     *
+     * @example
+     * ```ts
+     * pendingMessages: {
+     *   shouldInject: ({ steps }) => steps.length > 0,
+     *   onReceived: ({ message }) => logger.info("Steering message received"),
+     * },
+     * ```
+     */
+    pendingMessages?: PendingMessagesOptions;
+    /**
+     * conversation to your database after each assistant response.
      *
      * @example
      * ```ts
@@ -466,16 +1008,16 @@ export type ChatTaskOptions<TIdentifier extends string, TClientDataSchema extend
      */
     turnTimeout?: string;
     /**
-     * How long (in seconds) to keep the run warm after each turn before suspending.
-     * During this window the run stays active and can respond instantly to the
-     * next message. After this timeout, the run suspends (frees compute) and waits
-     * via `inputStream.wait()`.
+     * How long (in seconds) the run stays idle (active, using compute) after each
+     * turn, waiting for the next message. During this window responses are instant.
+     * After this timeout the run suspends (frees compute) and waits via
+     * `inputStream.wait()`.
      *
      * Set to `0` to suspend immediately after each turn.
      *
      * @default 30
      */
-    warmTimeoutInSeconds?: number;
+    idleTimeoutInSeconds?: number;
     /**
      * How long the `chatAccessToken` (scoped to this run) remains valid.
      * A fresh token is minted after each turn, so this only needs to cover
@@ -487,14 +1029,14 @@ export type ChatTaskOptions<TIdentifier extends string, TClientDataSchema extend
      */
     chatAccessTokenTTL?: string;
     /**
-     * How long (in seconds) to keep the run warm after `onPreload` fires,
+     * How long (in seconds) the run stays idle after `onPreload` fires,
      * waiting for the first message before suspending.
      *
      * Only applies to preloaded runs (triggered via `transport.preload()`).
      *
-     * @default Same as `warmTimeoutInSeconds`
+     * @default Same as `idleTimeoutInSeconds`
      */
-    preloadWarmTimeoutInSeconds?: number;
+    preloadIdleTimeoutInSeconds?: number;
     /**
      * How long to wait (suspended) for the first message after a preloaded run starts.
      * If no message arrives within this time, the run ends.
@@ -504,6 +1046,27 @@ export type ChatTaskOptions<TIdentifier extends string, TClientDataSchema extend
      * @default Same as `turnTimeout`
      */
     preloadTimeout?: string;
+    /**
+     * Transform model messages before they're used anywhere — in `run()`,
+     * in compaction rebuilds, and in compaction results.
+     *
+     * Define once, applied everywhere. Use for Anthropic cache breaks,
+     * injecting system context, stripping PII, etc.
+     *
+     * @example
+     * ```ts
+     * prepareMessages: async ({ messages, reason }) => {
+     *   // Add Anthropic cache breaks to the last message
+     *   if (messages.length === 0) return messages;
+     *   const last = messages[messages.length - 1];
+     *   return [...messages.slice(0, -1), {
+     *     ...last,
+     *     providerOptions: { ...last.providerOptions, anthropic: { cacheControl: { type: "ephemeral" } } },
+     *   }];
+     * }
+     * ```
+     */
+    prepareMessages?: (event: PrepareMessagesEvent<inferSchemaOut<TClientDataSchema>>) => ModelMessage[] | Promise<ModelMessage[]>;
     /**
      * Default options for `toUIMessageStream()` when auto-piping or using
      * `turn.complete()` / `chat.pipeAndCapture()`.
@@ -596,23 +1159,23 @@ declare function setTurnTimeout(duration: string): void;
  */
 declare function setTurnTimeoutInSeconds(seconds: number): void;
 /**
- * Override the warm timeout for subsequent turns in the current run.
+ * Override the idle timeout for subsequent turns in the current run.
  *
- * The warm timeout controls how long the run stays active (using compute)
+ * The idle timeout controls how long the run stays active (using compute)
  * after each turn, waiting for the next message. During this window,
  * responses are instant. After it expires, the run suspends.
  *
- * @param seconds - Number of seconds to stay warm (0 to suspend immediately)
+ * @param seconds - Number of seconds to stay idle (0 to suspend immediately)
  *
  * @example
  * ```ts
  * run: async ({ messages, signal }) => {
- *   chat.setWarmTimeoutInSeconds(60);
+ *   chat.setIdleTimeoutInSeconds(60);
  *   return streamText({ model, messages, abortSignal: signal });
  * }
  * ```
  */
-declare function setWarmTimeoutInSeconds(seconds: number): void;
+declare function setIdleTimeoutInSeconds(seconds: number): void;
 /**
  * Override the `toUIMessageStream()` options for the current turn.
  *
@@ -778,6 +1341,13 @@ declare function pipeChatAndCapture(source: UIMessageStreamable, options?: {
 declare class ChatMessageAccumulator {
     modelMessages: ModelMessage[];
     uiMessages: UIMessage[];
+    private _compaction?;
+    private _pendingMessages?;
+    private _steeringQueue;
+    constructor(options?: {
+        compaction?: ChatTaskCompactionOptions;
+        pendingMessages?: PendingMessagesOptions;
+    });
     /**
      * Add incoming messages from the transport payload.
      * Returns the full accumulated model messages for `streamText`.
@@ -787,17 +1357,62 @@ declare class ChatMessageAccumulator {
      * Add the assistant's response to the accumulator.
      * Call after `pipeAndCapture` with the captured response.
      */
+    /**
+     * Replace all accumulated messages (for compaction).
+     * Converts UIMessages to ModelMessages internally.
+     */
+    setMessages(uiMessages: UIMessage[]): Promise<void>;
     addResponse(response: UIMessage): Promise<void>;
+    /**
+     * Queue a message for injection via `prepareStep`. Call from a
+     * `messagesInput.on()` listener when a message arrives during streaming.
+     */
+    steer(message: UIMessage, modelMessages?: ModelMessage[]): void;
+    /**
+     * Queue a message for injection, converting to model messages automatically.
+     */
+    steerAsync(message: UIMessage): Promise<void>;
+    /**
+     * Get and clear unconsumed steering messages.
+     */
+    drainSteering(): UIMessage[];
+    /**
+     * Returns a `prepareStep` function that handles both compaction and
+     * pending message injection. Pass to `streamText({ prepareStep: conversation.prepareStep() })`.
+     */
+    prepareStep(): ((args: {
+        messages: ModelMessage[];
+        steps: CompactionStep[];
+    }) => Promise<{
+        messages: ModelMessage[];
+    } | undefined>) | undefined;
+    /**
+     * Run outer-loop compaction if needed. Call after adding the response
+     * and capturing usage. Applies `compactModelMessages` and `compactUIMessages`
+     * callbacks if configured.
+     *
+     * @returns `true` if compaction was performed, `false` otherwise.
+     */
+    compactIfNeeded(usage: LanguageModelUsage | undefined, context?: {
+        chatId?: string;
+        turn?: number;
+        clientData?: unknown;
+        totalUsage?: LanguageModelUsage;
+    }): Promise<boolean>;
 }
 export type ChatSessionOptions = {
     /** Run-level cancel signal (from task context). */
     signal: AbortSignal;
-    /** Seconds to stay warm between turns before suspending. @default 30 */
-    warmTimeoutInSeconds?: number;
+    /** Seconds to stay idle between turns before suspending. @default 30 */
+    idleTimeoutInSeconds?: number;
     /** Duration string for suspend timeout. @default "1h" */
     timeout?: string;
     /** Max turns before ending. @default 100 */
     maxTurns?: number;
+    /** Automatic context compaction — same options as `chat.task({ compaction })`. */
+    compaction?: ChatTaskCompactionOptions;
+    /** Configure mid-execution message injection — same options as `chat.task({ pendingMessages })`. */
+    pendingMessages?: PendingMessagesOptions;
 };
 export type ChatTurn = {
     /** Turn number (0-indexed). */
@@ -809,15 +1424,25 @@ export type ChatTurn = {
     /** Client data from the transport (`metadata` field on the wire payload). */
     clientData: unknown;
     /** Full accumulated model messages — pass directly to `streamText`. */
-    messages: ModelMessage[];
+    readonly messages: ModelMessage[];
     /** Full accumulated UI messages — use for persistence. */
-    uiMessages: UIMessage[];
+    readonly uiMessages: UIMessage[];
     /** Combined stop+cancel AbortSignal (fresh each turn). */
     signal: AbortSignal;
     /** Whether the user stopped generation this turn. */
     readonly stopped: boolean;
     /** Whether this is a continuation run. */
     continuation: boolean;
+    /** Token usage from the previous turn. Undefined on turn 0. */
+    previousTurnUsage?: LanguageModelUsage;
+    /** Cumulative token usage across all completed turns so far. */
+    totalUsage: LanguageModelUsage;
+    /**
+     * Replace accumulated messages (for compaction). Takes UIMessages and
+     * converts to ModelMessages internally. After calling this, `turn.messages`
+     * reflects the compacted history.
+     */
+    setMessages(uiMessages: UIMessage[]): Promise<void>;
     /**
      * Easy path: pipe stream, capture response, accumulate it,
      * clean up aborted parts if stopped, and write turn-complete chunk.
@@ -833,12 +1458,23 @@ export type ChatTurn = {
      * Use with `chat.pipeAndCapture` when you need control between pipe and done.
      */
     addResponse(response: UIMessage): Promise<void>;
+    /**
+     * Returns a `prepareStep` function that handles both compaction and
+     * pending message injection. Pass to `streamText({ prepareStep: turn.prepareStep() })`.
+     * Only needed when not using `chat.toStreamTextOptions()` (which auto-injects it).
+     */
+    prepareStep(): ((args: {
+        messages: ModelMessage[];
+        steps: CompactionStep[];
+    }) => Promise<{
+        messages: ModelMessage[];
+    } | undefined>) | undefined;
 };
 /**
  * Create a chat session that yields turns as an async iterator.
  *
  * Handles: preload wait, stop signals, message accumulation, turn-complete
- * signaling, and warm/suspend between turns. You control: initialization,
+ * signaling, and idle/suspend between turns. You control: initialization,
  * model/tool selection, persistence, and any custom per-turn logic.
  *
  * @example
@@ -953,8 +1589,8 @@ export declare const chat: {
     setTurnTimeout: typeof setTurnTimeout;
     /** Override the turn timeout at runtime (seconds). See {@link setTurnTimeoutInSeconds}. */
     setTurnTimeoutInSeconds: typeof setTurnTimeoutInSeconds;
-    /** Override the warm timeout at runtime. See {@link setWarmTimeoutInSeconds}. */
-    setWarmTimeoutInSeconds: typeof setWarmTimeoutInSeconds;
+    /** Override the idle timeout at runtime. See {@link setIdleTimeoutInSeconds}. */
+    setIdleTimeoutInSeconds: typeof setIdleTimeoutInSeconds;
     /** Override toUIMessageStream() options for the current turn. See {@link setUIMessageStreamOptions}. */
     setUIMessageStreamOptions: typeof setUIMessageStreamOptions;
     /** Check if the current turn was stopped by the user. See {@link isStopped}. */
@@ -977,4 +1613,33 @@ export declare const chat: {
     MessageAccumulator: typeof ChatMessageAccumulator;
     /** Create a chat session (async iterator). See {@link createChatSession}. */
     createSession: typeof createChatSession;
+    /**
+     * Store and retrieve a resolved prompt for the current run.
+     *
+     * - `chat.prompt.set(resolved)` — store a `ResolvedPrompt` or plain string
+     * - `chat.prompt()` — read the stored prompt (throws if not set)
+     */
+    prompt: typeof getChatPrompt & {
+        set: typeof setChatPrompt;
+    };
+    /**
+     * Returns an options object ready to spread into `streamText()`.
+     * Reads the stored prompt and returns `{ system, experimental_telemetry, ...config }`.
+     * Returns `{}` if no prompt has been set.
+     */
+    toStreamTextOptions: typeof toStreamTextOptions;
+    /**
+     * Replace the accumulated conversation messages for compaction.
+     * Call from `onTurnStart` or `onTurnComplete`. Takes `UIMessage[]` and
+     * converts to `ModelMessage[]` internally.
+     */
+    setMessages: typeof setChatMessages;
+    /** Check if it's safe to compact messages (no in-flight tool calls). */
+    isCompactionSafe: typeof isCompactionSafe;
+    /** Returns a `prepareStep` function that handles context compaction automatically. */
+    compactionStep: typeof chatCompactionStep;
+    /** Low-level compaction for use inside a custom `prepareStep`. */
+    compact: typeof chatCompact;
+    /** Read the current compaction state (summary + base message count). */
+    getCompactionState: typeof getCompactionState;
 };