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

package/dist/commonjs/v3/ai.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.chat = exports.CHAT_STOP_STREAM_ID = exports.CHAT_MESSAGES_STREAM_ID = exports.CHAT_STREAM_KEY = exports.ai = void 0;
+exports.chat = exports.PENDING_MESSAGE_INJECTED_TYPE = exports.CHAT_STOP_STREAM_ID = exports.CHAT_MESSAGES_STREAM_ID = exports.CHAT_STREAM_KEY = exports.ai = void 0;
 const v3_1 = require("@trigger.dev/core/v3");
 const ai_1 = require("ai");
 const api_1 = require("@opentelemetry/api");
@@ -14,6 +14,14 @@ const chat_constants_js_1 = require("./chat-constants.js");
 Object.defineProperty(exports, "CHAT_MESSAGES_STREAM_ID", { enumerable: true, get: function () { return chat_constants_js_1.CHAT_MESSAGES_STREAM_ID; } });
 Object.defineProperty(exports, "CHAT_STOP_STREAM_ID", { enumerable: true, get: function () { return chat_constants_js_1.CHAT_STOP_STREAM_ID; } });
 const METADATA_KEY = "tool.execute.options";
+/**
+ * Wrapper around `convertToModelMessages` that always passes
+ * `ignoreIncompleteToolCalls: true` to prevent failures from
+ * stopped/aborted conversations with partial tool parts.
+ */
+function toModelMessages(messages) {
+    return (0, ai_1.convertToModelMessages)(messages, { ignoreIncompleteToolCalls: true });
+}
 const chatTurnContextKey = locals_js_1.locals.create("chat.turnContext");
 function toolFromTask(task, options) {
     if (("schema" in task && !task.schema) || ("jsonSchema" in task && !task.jsonSchema)) {
@@ -218,6 +226,537 @@ const chatStopControllerKey = locals_js_1.locals.create("chat.stopController");
 const chatUIStreamStaticKey = locals_js_1.locals.create("chat.uiMessageStreamOptions.static");
 /** Per-turn UIMessageStream options, set via chat.setUIMessageStreamOptions(). @internal */
 const chatUIStreamPerTurnKey = locals_js_1.locals.create("chat.uiMessageStreamOptions.perTurn");
+function emptyUsage() {
+    return {
+        inputTokens: undefined,
+        outputTokens: undefined,
+        totalTokens: undefined,
+        inputTokenDetails: { noCacheTokens: undefined, cacheReadTokens: undefined, cacheWriteTokens: undefined },
+        outputTokenDetails: { textTokens: undefined, reasoningTokens: undefined },
+    };
+}
+function addUsage(a, b) {
+    const add = (x, y) => x != null || y != null ? (x ?? 0) + (y ?? 0) : undefined;
+    return {
+        inputTokens: add(a.inputTokens, b.inputTokens),
+        outputTokens: add(a.outputTokens, b.outputTokens),
+        totalTokens: add(a.totalTokens, b.totalTokens),
+        inputTokenDetails: {
+            noCacheTokens: add(a.inputTokenDetails?.noCacheTokens, b.inputTokenDetails?.noCacheTokens),
+            cacheReadTokens: add(a.inputTokenDetails?.cacheReadTokens, b.inputTokenDetails?.cacheReadTokens),
+            cacheWriteTokens: add(a.inputTokenDetails?.cacheWriteTokens, b.inputTokenDetails?.cacheWriteTokens),
+        },
+        outputTokenDetails: {
+            textTokens: add(a.outputTokenDetails?.textTokens, b.outputTokenDetails?.textTokens),
+            reasoningTokens: add(a.outputTokenDetails?.reasoningTokens, b.outputTokenDetails?.reasoningTokens),
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// chat.setMessages — replace accumulated messages for compaction
+// ---------------------------------------------------------------------------
+/** @internal */
+const chatOverrideMessagesKey = locals_js_1.locals.create("chat.overrideMessages");
+/**
+ * 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.
+ */
+function setChatMessages(uiMessages) {
+    locals_js_1.locals.set(chatOverrideMessagesKey, uiMessages);
+}
+/**
+ * Model-only message override. Set by compaction to replace only the model
+ * messages (what goes to the LLM) without affecting UI messages (what gets
+ * persisted and displayed). This preserves full conversation history for the
+ * user while keeping LLM context compact.
+ * @internal
+ */
+const chatOverrideModelMessagesKey = locals_js_1.locals.create("chat.overrideModelMessages");
+/** @internal */
+const chatCompactionStateKey = locals_js_1.locals.create("chat.compaction");
+const chatOnCompactedKey = locals_js_1.locals.create("chat.onCompacted");
+const chatPrepareMessagesKey = locals_js_1.locals.create("chat.prepareMessages");
+/** @internal */
+const chatTaskCompactionKey = locals_js_1.locals.create("chat.taskCompaction");
+/**
+ * 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.
+ */
+exports.PENDING_MESSAGE_INJECTED_TYPE = "data-pending-message-injected";
+/** @internal */
+const chatPendingMessagesKey = locals_js_1.locals.create("chat.pendingMessages");
+/** @internal */
+const chatSteeringQueueKey = locals_js_1.locals.create("chat.steeringQueue");
+/** @internal — IDs of messages that were successfully injected via prepareStep */
+const chatInjectedMessageIdsKey = locals_js_1.locals.create("chat.injectedMessageIds");
+/**
+ * Check that no tool calls are in-flight in a step's content.
+ * Used before compaction to avoid losing tool state mid-execution.
+ * @internal
+ */
+function isStepBoundarySafe(step) {
+    if (step.finishReason === "error")
+        return false;
+    const callIds = new Set(step.content.filter((p) => p.type === "tool-call").map((p) => p.toolCallId));
+    const settledIds = new Set(step.content
+        .filter((p) => p.type === "tool-result" || p.type === "tool-error")
+        .map((p) => p.toolCallId));
+    return ![...callIds].some((id) => !settledIds.has(id));
+}
+/**
+ * Apply the prepareMessages hook if one is set in locals.
+ * @internal
+ */
+async function applyPrepareMessages(messages, reason) {
+    const hook = locals_js_1.locals.get(chatPrepareMessagesKey);
+    if (!hook)
+        return messages;
+    const turnCtx = locals_js_1.locals.get(chatTurnContextKey);
+    return tracer_js_1.tracer.startActiveSpan("prepareMessages()", async () => {
+        return hook({
+            messages,
+            reason,
+            chatId: turnCtx?.chatId ?? "",
+            turn: turnCtx?.turn ?? 0,
+            clientData: turnCtx?.clientData,
+        });
+    }, {
+        attributes: {
+            [v3_1.SemanticInternalAttributes.STYLE_ICON]: "task-hook-onStart",
+            [v3_1.SemanticInternalAttributes.COLLAPSED]: true,
+            "chat.prepareMessages.reason": reason,
+            "chat.prepareMessages.messageCount": messages.length,
+        },
+    });
+}
+/**
+ * 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] };
+ * }
+ * ```
+ */
+function getCompactionState() {
+    return locals_js_1.locals.get(chatCompactionStateKey);
+}
+/**
+ * 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;
+ * },
+ * ```
+ */
+async function chatCompact(messages, steps, options) {
+    const currentStep = steps.at(-1);
+    // First step — nothing to check
+    if (!currentStep) {
+        return { type: "skipped" };
+    }
+    // Already compacted — rebuild from summary + new response messages
+    const state = locals_js_1.locals.get(chatCompactionStateKey);
+    if (state && isStepBoundarySafe(currentStep)) {
+        return {
+            type: "rebuilt",
+            messages: await applyPrepareMessages([
+                { role: "user", content: state.summary },
+                ...currentStep.response.messages.slice(state.baseResponseMessageCount),
+            ], "compaction-rebuild"),
+        };
+    }
+    // Boundary unsafe — skip
+    if (!isStepBoundarySafe(currentStep)) {
+        return { type: "skipped" };
+    }
+    const totalTokens = currentStep.usage.totalTokens;
+    const inputTokens = currentStep.usage.inputTokens;
+    const outputTokens = currentStep.usage.outputTokens;
+    const turnCtx = locals_js_1.locals.get(chatTurnContextKey);
+    const stepNumber = steps.length - 1;
+    const shouldTrigger = options.shouldCompact
+        ? await options.shouldCompact({
+            messages,
+            totalTokens,
+            inputTokens,
+            outputTokens,
+            usage: currentStep.usage,
+            source: "inner",
+            stepNumber,
+            steps,
+            chatId: turnCtx?.chatId,
+            turn: turnCtx?.turn,
+            clientData: turnCtx?.clientData,
+        })
+        : (totalTokens != null && options.threshold != null && totalTokens > options.threshold);
+    if (!shouldTrigger) {
+        return { type: "skipped" };
+    }
+    const result = await tracer_js_1.tracer.startActiveSpan("context compaction", async (span) => {
+        const compactionId = (0, ai_1.generateId)();
+        let summary;
+        const { waitUntilComplete } = streams_js_1.streams.writer(exports.CHAT_STREAM_KEY, {
+            spanName: "stream compaction chunks",
+            collapsed: true,
+            execute: async ({ write }) => {
+                write({ type: "step-start" });
+                write({
+                    type: "data-compaction",
+                    id: compactionId,
+                    data: { status: "compacting", totalTokens },
+                });
+                // Generate summary
+                summary = await options.summarize(messages);
+                // Store state in locals for subsequent steps
+                locals_js_1.locals.set(chatCompactionStateKey, {
+                    summary,
+                    baseResponseMessageCount: currentStep.response.messages.length,
+                });
+                // Set model-only override — UI messages stay intact for persistence.
+                // The summary becomes the model message history for the next turn,
+                // while accumulatedUIMessages keeps the full conversation for display.
+                locals_js_1.locals.set(chatOverrideModelMessagesKey, [
+                    { role: "assistant", content: [{ type: "text", text: `[Conversation summary]\n\n${summary}` }] },
+                ]);
+                // Fire onCompacted hook
+                const onCompactedHook = locals_js_1.locals.get(chatOnCompactedKey);
+                if (onCompactedHook) {
+                    await onCompactedHook({
+                        summary,
+                        messages,
+                        messageCount: messages.length,
+                        usage: currentStep.usage,
+                        totalTokens,
+                        inputTokens,
+                        outputTokens,
+                        stepNumber,
+                        chatId: turnCtx?.chatId,
+                        turn: turnCtx?.turn,
+                    });
+                }
+                write({
+                    type: "data-compaction",
+                    id: compactionId,
+                    data: { status: "complete", totalTokens },
+                });
+                write({ type: "finish-step" });
+            },
+        });
+        await waitUntilComplete();
+        // Set attributes after we have the summary
+        span.setAttribute("compaction.summary_length", summary.length);
+        return {
+            type: "compacted",
+            messages: await applyPrepareMessages([{ role: "user", content: summary }], "compaction-result"),
+            summary,
+        };
+    }, {
+        attributes: {
+            [v3_1.SemanticInternalAttributes.STYLE_ICON]: "tabler-scissors",
+            "compaction.threshold": options.threshold,
+            "compaction.total_tokens": totalTokens ?? 0,
+            "compaction.input_tokens": inputTokens ?? 0,
+            "compaction.message_count": messages.length,
+            "compaction.step_number": stepNumber,
+            ...(turnCtx?.chatId ? { "compaction.chat_id": turnCtx.chatId } : {}),
+            ...(turnCtx?.turn != null ? { "compaction.turn": turnCtx.turn } : {}),
+            ...(0, v3_1.accessoryAttributes)({
+                items: [
+                    { text: `${totalTokens ?? 0} tokens`, variant: "normal" },
+                    { text: `${messages.length} msgs`, variant: "normal" },
+                ],
+                style: "codepath",
+            }),
+        },
+    });
+    return result;
+}
+/**
+ * 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: { ... },
+ * });
+ * ```
+ */
+function chatCompactionStep(options) {
+    return async ({ messages, steps }) => {
+        const result = await chatCompact(messages, steps, options);
+        return result.type === "skipped" ? undefined : result;
+    };
+}
+// ---------------------------------------------------------------------------
+// Steering queue drain — shared by toStreamTextOptions, session, accumulator
+// ---------------------------------------------------------------------------
+/**
+ * Drain the steering queue as a batch. Calls `shouldInject` once with all
+ * pending messages. If it returns true, calls `prepareMessages` once to
+ * transform the batch, then clears the queue.
+ * Returns the model messages to inject (empty if none).
+ * @internal
+ */
+async function drainSteeringQueue(config, messages, steps, queueOverride) {
+    const queue = queueOverride ?? locals_js_1.locals.get(chatSteeringQueueKey);
+    if (!queue || queue.length === 0)
+        return [];
+    const ctx = locals_js_1.locals.get(chatTurnContextKey);
+    const stepNumber = steps.length - 1;
+    const uiMessages = queue.map((e) => e.uiMessage);
+    const batchEvent = {
+        messages: uiMessages,
+        modelMessages: messages,
+        steps,
+        stepNumber,
+        chatId: ctx?.chatId ?? "",
+        turn: ctx?.turn ?? 0,
+        clientData: ctx?.clientData,
+    };
+    // Call shouldInject once for the whole batch
+    const shouldInject = config.shouldInject
+        ? await config.shouldInject(batchEvent)
+        : false;
+    if (!shouldInject)
+        return [];
+    // Extract message texts for span attributes
+    const messageTexts = uiMessages.map((m) => (m.parts ?? []).filter((p) => p.type === "text").map((p) => p.text).join("") || "");
+    const previewText = messageTexts.length === 1
+        ? messageTexts[0].slice(0, 80)
+        : `${queue.length} messages`;
+    return tracer_js_1.tracer.startActiveSpan("pending message injected", async () => {
+        // Transform the batch — default: concatenate all pre-converted model messages
+        const injected = config.prepare
+            ? await config.prepare(batchEvent)
+            : queue.flatMap((e) => e.modelMessages);
+        // Clear the queue and record injected IDs
+        queue.length = 0;
+        const injectedIds = locals_js_1.locals.get(chatInjectedMessageIdsKey);
+        if (injectedIds) {
+            for (const m of uiMessages)
+                injectedIds.add(m.id);
+        }
+        // Write injection confirmation chunk to the stream so the frontend
+        // knows which messages were injected and where in the response.
+        if (injected.length > 0) {
+            try {
+                const { waitUntilComplete } = streams_js_1.streams.writer(exports.CHAT_STREAM_KEY, {
+                    collapsed: true,
+                    execute: ({ write }) => {
+                        write({
+                            type: exports.PENDING_MESSAGE_INJECTED_TYPE,
+                            id: (0, ai_1.generateId)(),
+                            data: {
+                                messageIds: uiMessages.map((m) => m.id),
+                                messages: uiMessages.map((m, idx) => ({
+                                    id: m.id,
+                                    text: messageTexts[idx] ?? "",
+                                })),
+                            },
+                        });
+                    },
+                });
+                await waitUntilComplete();
+            }
+            catch { /* non-fatal — stream write failed */ }
+        }
+        // Fire onInjected callback
+        if (config.onInjected && injected.length > 0) {
+            try {
+                await config.onInjected({
+                    messages: uiMessages,
+                    injectedModelMessages: injected,
+                    chatId: ctx?.chatId ?? "",
+                    turn: ctx?.turn ?? 0,
+                    stepNumber,
+                });
+            }
+            catch { /* non-fatal */ }
+        }
+        return injected;
+    }, {
+        attributes: {
+            [v3_1.SemanticInternalAttributes.STYLE_ICON]: "tabler-message-forward",
+            "pending.message_count": uiMessages.length,
+            "pending.step_number": stepNumber,
+            "pending.messages": messageTexts,
+            ...(ctx?.chatId ? { "pending.chat_id": ctx.chatId } : {}),
+            ...(ctx?.turn != null ? { "pending.turn": ctx.turn } : {}),
+            ...(0, v3_1.accessoryAttributes)({
+                items: [
+                    { text: `${uiMessages.length} message${uiMessages.length === 1 ? "" : "s"}`, variant: "normal" },
+                    { text: `between steps ${stepNumber} and ${stepNumber + 1}`, variant: "normal" },
+                ],
+                style: "codepath",
+            }),
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// chat.isCompactionSafe — check if it's safe to compact messages
+// ---------------------------------------------------------------------------
+/**
+ * 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.
+ */
+function isCompactionSafe(messages) {
+    for (const msg of messages) {
+        if (msg.role !== "assistant")
+            continue;
+        for (const part of msg.parts) {
+            if (part.type === "tool-invocation") {
+                const state = part.toolInvocation?.state ?? part.state;
+                if (state !== "result" && state !== "error") {
+                    return false;
+                }
+            }
+        }
+    }
+    return true;
+}
+/** @internal */
+const chatPromptKey = locals_js_1.locals.create("chat.prompt");
+/**
+ * Store a resolved prompt (or plain string) for the current run.
+ * Call from any hook (`onPreload`, `onChatStart`, `onTurnStart`) or `run()`.
+ */
+function setChatPrompt(resolved) {
+    if (typeof resolved === "string") {
+        locals_js_1.locals.set(chatPromptKey, {
+            text: resolved,
+            model: undefined,
+            config: undefined,
+            promptId: "",
+            version: 0,
+            labels: [],
+            toAISDKTelemetry: () => ({
+                experimental_telemetry: { isEnabled: true, metadata: {} },
+            }),
+        });
+    }
+    else {
+        locals_js_1.locals.set(chatPromptKey, resolved);
+    }
+}
+/**
+ * Read the stored prompt. Throws if `chat.prompt.set()` has not been called.
+ */
+function getChatPrompt() {
+    const prompt = locals_js_1.locals.get(chatPromptKey);
+    if (!prompt) {
+        throw new Error("chat.prompt() called before chat.prompt.set(). Set a prompt in onPreload, onChatStart, onTurnStart, or run() first.");
+    }
+    return prompt;
+}
+/**
+ * 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).
+ */
+function toStreamTextOptions(options) {
+    const prompt = locals_js_1.locals.get(chatPromptKey);
+    if (!prompt)
+        return {};
+    const result = {
+        system: prompt.text,
+    };
+    // Resolve model via registry if both are present
+    if (options?.registry && prompt.model) {
+        result.model = options.registry.languageModel(prompt.model);
+    }
+    // Spread config (temperature, maxTokens, etc.)
+    if (prompt.config) {
+        Object.assign(result, prompt.config);
+    }
+    // Add telemetry (forward additional metadata from caller)
+    const telemetry = prompt.toAISDKTelemetry(options?.telemetry);
+    Object.assign(result, telemetry);
+    // Auto-inject prepareStep when compaction or pendingMessages is configured.
+    const taskCompaction = locals_js_1.locals.get(chatTaskCompactionKey);
+    const taskPendingMessages = locals_js_1.locals.get(chatPendingMessagesKey);
+    if (taskCompaction || taskPendingMessages) {
+        result.prepareStep = async ({ messages, steps }) => {
+            let resultMessages;
+            // 1. Compaction
+            if (taskCompaction) {
+                const compactResult = await chatCompact(messages, steps, {
+                    shouldCompact: taskCompaction.shouldCompact,
+                    summarize: (msgs) => {
+                        const ctx = locals_js_1.locals.get(chatTurnContextKey);
+                        const lastStep = steps.at(-1);
+                        return taskCompaction.summarize({
+                            messages: msgs,
+                            usage: lastStep?.usage,
+                            source: "inner",
+                            stepNumber: steps.length - 1,
+                            chatId: ctx?.chatId,
+                            turn: ctx?.turn,
+                            clientData: ctx?.clientData,
+                        });
+                    },
+                });
+                if (compactResult.type !== "skipped") {
+                    resultMessages = compactResult.messages;
+                }
+            }
+            // 2. Pending message injection (steering)
+            if (taskPendingMessages) {
+                const injected = await drainSteeringQueue(taskPendingMessages, resultMessages ?? messages, steps);
+                if (injected.length > 0) {
+                    resultMessages = [...(resultMessages ?? messages), ...injected];
+                }
+            }
+            return resultMessages ? { messages: resultMessages } : undefined;
+        };
+    }
+    return result;
+}
 function isUIMessageStreamable(value) {
     return (typeof value === "object" &&
         value !== null &&
@@ -324,7 +863,7 @@ async function pipeChat(source, options) {
  * ```
  */
 function chatTask(options) {
-    const { run: userRun, clientDataSchema, onPreload, onChatStart, onTurnStart, onTurnComplete, maxTurns = 100, turnTimeout = "1h", warmTimeoutInSeconds = 30, chatAccessTokenTTL = "1h", preloadWarmTimeoutInSeconds, preloadTimeout, uiMessageStreamOptions, ...restOptions } = options;
+    const { run: userRun, clientDataSchema, onPreload, onChatStart, onTurnStart, onBeforeTurnComplete, onCompacted, compaction, pendingMessages: pendingMessagesConfig, prepareMessages, onTurnComplete, maxTurns = 100, turnTimeout = "1h", idleTimeoutInSeconds = 30, chatAccessTokenTTL = "1h", preloadIdleTimeoutInSeconds, preloadTimeout, uiMessageStreamOptions, ...restOptions } = options;
     const parseClientData = clientDataSchema
         ? (0, v3_1.getSchemaParseFn)(clientDataSchema)
         : undefined;
@@ -340,6 +879,19 @@ function chatTask(options) {
             if (uiMessageStreamOptions) {
                 locals_js_1.locals.set(chatUIStreamStaticKey, uiMessageStreamOptions);
             }
+            // Store onCompacted hook in locals so chat.compact() can call it
+            if (onCompacted) {
+                locals_js_1.locals.set(chatOnCompactedKey, onCompacted);
+            }
+            if (prepareMessages) {
+                locals_js_1.locals.set(chatPrepareMessagesKey, prepareMessages);
+            }
+            if (compaction) {
+                locals_js_1.locals.set(chatTaskCompactionKey, compaction);
+            }
+            if (pendingMessagesConfig) {
+                locals_js_1.locals.set(chatPendingMessagesKey, pendingMessagesConfig);
+            }
             let currentWirePayload = payload;
             const continuation = payload.continuation ?? false;
             const previousRunId = payload.previousRunId;
@@ -351,6 +903,9 @@ function chatTask(options) {
             // Accumulated UI messages for persistence. Mirrors the model accumulator
             // but in frontend-friendly UIMessage format (with parts, id, etc.).
             let accumulatedUIMessages = [];
+            // Token usage tracking across turns
+            let previousTurnUsage;
+            let cumulativeUsage = emptyUsage();
             // Mutable reference to the current turn's stop controller so the
             // stop input stream listener (registered once) can abort the right turn.
             let currentStopController;
@@ -403,14 +958,14 @@ function chatTask(options) {
                         });
                     }
                     // Wait for the first real message — use preload-specific timeouts if configured
-                    const effectivePreloadWarmTimeout = payload.warmTimeoutInSeconds
-                        ?? preloadWarmTimeoutInSeconds
-                        ?? warmTimeoutInSeconds;
+                    const effectivePreloadIdleTimeout = payload.idleTimeoutInSeconds
+                        ?? preloadIdleTimeoutInSeconds
+                        ?? idleTimeoutInSeconds;
                     const effectivePreloadTimeout = metadata_js_1.metadata.get(TURN_TIMEOUT_METADATA_KEY)
                         ?? preloadTimeout
                         ?? turnTimeout;
-                    const preloadResult = await messagesInput.waitWithWarmup({
-                        warmTimeoutInSeconds: effectivePreloadWarmTimeout,
+                    const preloadResult = await messagesInput.waitWithIdleTimeout({
+                        idleTimeoutInSeconds: effectivePreloadIdleTimeout,
                         timeout: effectivePreloadTimeout,
                         spanName: "waiting for first message",
                     });
@@ -450,9 +1005,12 @@ function chatTask(options) {
                         turnAttributes["chat.client_data"] =
                             typeof wireMetadata === "string" ? wireMetadata : JSON.stringify(wireMetadata);
                     }
-                    const turnResult = await tracer_js_1.tracer.startActiveSpan(`chat turn ${turn + 1}`, async () => {
+                    const turnResult = await tracer_js_1.tracer.startActiveSpan(`chat turn ${turn + 1}`, async (turnSpan) => {
                         locals_js_1.locals.set(chatPipeCountKey, 0);
                         locals_js_1.locals.set(chatDeferKey, new Set());
+                        locals_js_1.locals.set(chatCompactionStateKey, undefined);
+                        locals_js_1.locals.set(chatSteeringQueueKey, []);
+                        locals_js_1.locals.set(chatInjectedMessageIdsKey, new Set());
                         // Store chat context for auto-detection by ai.tool subtasks
                         locals_js_1.locals.set(chatTurnContextKey, {
                             chatId: currentWirePayload.chatId,
@@ -470,7 +1028,39 @@ function chatTask(options) {
                         const combinedSignal = AbortSignal.any([runSignal, stopController.signal]);
                         // Buffer messages that arrive during streaming
                         const pendingMessages = [];
-                        const msgSub = messagesInput.on((msg) => {
+                        const pmConfig = locals_js_1.locals.get(chatPendingMessagesKey);
+                        const msgSub = messagesInput.on(async (msg) => {
+                            // If pendingMessages is configured, route to the steering queue
+                            // instead of the wire buffer. The frontend handles re-sending
+                            // non-injected messages via sendMessage on turn complete.
+                            if (pmConfig) {
+                                const lastUIMessage = msg.messages?.[msg.messages.length - 1];
+                                if (lastUIMessage) {
+                                    if (pmConfig.onReceived) {
+                                        try {
+                                            await pmConfig.onReceived({
+                                                message: lastUIMessage,
+                                                chatId: currentWirePayload.chatId,
+                                                turn,
+                                            });
+                                        }
+                                        catch { /* non-fatal */ }
+                                    }
+                                    try {
+                                        const queue = locals_js_1.locals.get(chatSteeringQueueKey) ?? [];
+                                        // Deduplicate by message ID — guards against double-sends
+                                        if (lastUIMessage.id && queue.some((e) => e.uiMessage.id === lastUIMessage.id)) {
+                                            return;
+                                        }
+                                        const modelMsgs = await toModelMessages([lastUIMessage]);
+                                        queue.push({ uiMessage: lastUIMessage, modelMessages: modelMsgs });
+                                        locals_js_1.locals.set(chatSteeringQueueKey, queue);
+                                    }
+                                    catch { /* conversion failed — skip steering queue */ }
+                                }
+                                return; // Don't add to wire buffer — frontend handles non-injected case
+                            }
+                            // No pendingMessages config — standard wire buffer for next turn
                             pendingMessages.push(msg);
                         });
                         // Clean up any incomplete tool parts in the incoming history.
@@ -482,7 +1072,7 @@ function chatTask(options) {
                         // Convert the incoming UIMessages to model messages and update the accumulator.
                         // Turn 1: full history from the frontend → replaces the accumulator.
                         // Turn 2+: only the new message(s) → appended to the accumulator.
-                        const incomingModelMessages = await (0, ai_1.convertToModelMessages)(cleanedUIMessages);
+                        const incomingModelMessages = await toModelMessages(cleanedUIMessages);
                         // Track new messages for this turn (user input + assistant response).
                         const turnNewModelMessages = [];
                         const turnNewUIMessages = [];
@@ -570,7 +1160,16 @@ function chatTask(options) {
                                     continuation,
                                     previousRunId,
                                     preloaded,
+                                    previousTurnUsage,
+                                    totalUsage: cumulativeUsage,
                                 });
+                                // Check if onTurnStart replaced messages (compaction)
+                                const turnStartOverride = locals_js_1.locals.get(chatOverrideMessagesKey);
+                                if (turnStartOverride) {
+                                    locals_js_1.locals.set(chatOverrideMessagesKey, undefined);
+                                    accumulatedUIMessages = [...turnStartOverride];
+                                    accumulatedMessages = await toModelMessages(turnStartOverride);
+                                }
                             }, {
                                 attributes: {
                                     [v3_1.SemanticInternalAttributes.STYLE_ICON]: "task-hook-onStart",
@@ -595,14 +1194,17 @@ function chatTask(options) {
                         let resolveOnFinish;
                         const onFinishPromise = new Promise((r) => { resolveOnFinish = r; });
                         let onFinishAttached = false;
+                        let runResult;
                         try {
-                            const result = await userRun({
+                            runResult = await userRun({
                                 ...restWire,
-                                messages: accumulatedMessages,
+                                messages: await applyPrepareMessages(accumulatedMessages, "run"),
                                 clientData,
                                 continuation,
                                 previousRunId,
                                 preloaded,
+                                previousTurnUsage,
+                                totalUsage: cumulativeUsage,
                                 signal: combinedSignal,
                                 cancelSignal,
                                 stopSignal,
@@ -610,9 +1212,9 @@ function chatTask(options) {
                             // Auto-pipe if the run function returned a StreamTextResult or similar,
                             // but only if pipeChat() wasn't already called manually during this turn.
                             // We call toUIMessageStream ourselves to attach onFinish for response capture.
-                            if ((locals_js_1.locals.get(chatPipeCountKey) ?? 0) === 0 && isUIMessageStreamable(result)) {
+                            if ((locals_js_1.locals.get(chatPipeCountKey) ?? 0) === 0 && isUIMessageStreamable(runResult)) {
                                 onFinishAttached = true;
-                                const uiStream = result.toUIMessageStream({
+                                const uiStream = runResult.toUIMessageStream({
                                     ...resolveUIMessageStreamOptions(),
                                     onFinish: ({ responseMessage }) => {
                                         capturedResponseMessage = responseMessage;
@@ -642,6 +1244,72 @@ function chatTask(options) {
                         if (onFinishAttached) {
                             await onFinishPromise;
                         }
+                        // Capture token usage from the streamText result (if available).
+                        // totalUsage is a PromiseLike that resolves after the stream is consumed.
+                        let turnUsage;
+                        if (runResult != null && typeof runResult.totalUsage?.then === "function") {
+                            try {
+                                turnUsage = await runResult.totalUsage;
+                            }
+                            catch { /* non-fatal — usage capture failed */ }
+                        }
+                        if (turnUsage) {
+                            cumulativeUsage = addUsage(cumulativeUsage, turnUsage);
+                            previousTurnUsage = turnUsage;
+                            // Add usage attributes to the turn span
+                            if (turnUsage.inputTokens != null) {
+                                turnSpan.setAttribute("gen_ai.usage.input_tokens", turnUsage.inputTokens);
+                            }
+                            if (turnUsage.outputTokens != null) {
+                                turnSpan.setAttribute("gen_ai.usage.output_tokens", turnUsage.outputTokens);
+                            }
+                            if (turnUsage.totalTokens != null) {
+                                turnSpan.setAttribute("gen_ai.usage.total_tokens", turnUsage.totalTokens);
+                            }
+                            if (cumulativeUsage.totalTokens != null) {
+                                turnSpan.setAttribute("gen_ai.usage.cumulative_total_tokens", cumulativeUsage.totalTokens);
+                            }
+                            if (cumulativeUsage.inputTokens != null) {
+                                turnSpan.setAttribute("gen_ai.usage.cumulative_input_tokens", cumulativeUsage.inputTokens);
+                            }
+                            if (cumulativeUsage.outputTokens != null) {
+                                turnSpan.setAttribute("gen_ai.usage.cumulative_output_tokens", cumulativeUsage.outputTokens);
+                            }
+                        }
+                        // Check if run() (e.g. via prepareStep) replaced messages during this turn.
+                        // This supports intra-turn compaction — the compacted messages become the
+                        // new base, and the response gets appended on top.
+                        const runOverride = locals_js_1.locals.get(chatOverrideMessagesKey);
+                        if (runOverride) {
+                            locals_js_1.locals.set(chatOverrideMessagesKey, undefined);
+                            accumulatedUIMessages = [...runOverride];
+                            accumulatedMessages = await toModelMessages(runOverride);
+                        }
+                        // Check if compaction set a model-only override (preserves UI messages).
+                        // Apply compactUIMessages/compactModelMessages callbacks if configured.
+                        const modelOnlyOverride = locals_js_1.locals.get(chatOverrideModelMessagesKey);
+                        if (modelOnlyOverride) {
+                            const compactionSummary = locals_js_1.locals.get(chatCompactionStateKey)?.summary ?? "";
+                            const taskCompactionConfig = locals_js_1.locals.get(chatTaskCompactionKey);
+                            locals_js_1.locals.set(chatOverrideModelMessagesKey, undefined);
+                            const compactEvent = {
+                                summary: compactionSummary,
+                                uiMessages: accumulatedUIMessages,
+                                modelMessages: accumulatedMessages,
+                                chatId: currentWirePayload.chatId,
+                                turn,
+                                clientData,
+                                source: "inner",
+                            };
+                            // Apply model messages: callback or default (use override)
+                            accumulatedMessages = taskCompactionConfig?.compactModelMessages
+                                ? await taskCompactionConfig.compactModelMessages(compactEvent)
+                                : modelOnlyOverride;
+                            // Apply UI messages: callback or default (preserve all)
+                            if (taskCompactionConfig?.compactUIMessages) {
+                                accumulatedUIMessages = await taskCompactionConfig.compactUIMessages(compactEvent);
+                            }
+                        }
                         // Determine if the user stopped generation this turn (not a full run cancel).
                         const wasStopped = stopController.signal.aborted && !runSignal.aborted;
                         // Append the assistant's response (partial or complete) to the accumulator.
@@ -664,7 +1332,7 @@ function chatTask(options) {
                             accumulatedUIMessages.push(capturedResponseMessage);
                             turnNewUIMessages.push(capturedResponseMessage);
                             try {
-                                const responseModelMessages = await (0, ai_1.convertToModelMessages)([
+                                const responseModelMessages = await toModelMessages([
                                     stripProviderMetadata(capturedResponseMessage),
                                 ]);
                                 accumulatedMessages.push(...responseModelMessages);
@@ -680,11 +1348,8 @@ function chatTask(options) {
                         // accumulation (e.g. via a `chat.addMessages()` helper).
                         if (runSignal.aborted)
                             return "exit";
-                        // Write turn-complete control chunk so frontend closes its stream.
-                        // Capture the lastEventId from the stream writer for resume support.
-                        const turnCompleteResult = await writeTurnCompleteChunk(currentWirePayload.chatId, turnAccessToken);
                         // Await deferred background work (e.g. DB writes from onTurnStart)
-                        // before firing onTurnComplete so hooks can rely on the work being done.
+                        // before firing hooks so they can rely on the work being done.
                         const deferredWork = locals_js_1.locals.get(chatDeferKey);
                         if (deferredWork && deferredWork.size > 0) {
                             await Promise.race([
@@ -692,27 +1357,169 @@ function chatTask(options) {
                                 new Promise((r) => setTimeout(r, 5_000)),
                             ]);
                         }
-                        // Fire onTurnComplete after response capture
+                        // Outer-loop compaction: runs between turns for single-step responses
+                        // where prepareStep never fires (no tool calls = no step boundaries).
+                        // Only triggers when: task has compaction configured, prepareStep didn't
+                        // already compact this turn, and shouldCompact returns true.
+                        const outerCompaction = locals_js_1.locals.get(chatTaskCompactionKey);
+                        const innerCompactionState = locals_js_1.locals.get(chatCompactionStateKey);
+                        if (outerCompaction && !innerCompactionState && turnUsage && !wasStopped) {
+                            const shouldTrigger = await outerCompaction.shouldCompact({
+                                messages: accumulatedMessages,
+                                totalTokens: turnUsage.totalTokens,
+                                inputTokens: turnUsage.inputTokens,
+                                outputTokens: turnUsage.outputTokens,
+                                usage: turnUsage,
+                                totalUsage: cumulativeUsage,
+                                chatId: currentWirePayload.chatId,
+                                turn,
+                                clientData,
+                                source: "outer",
+                            });
+                            if (shouldTrigger) {
+                                await tracer_js_1.tracer.startActiveSpan("context compaction (outer loop)", async (compactionSpan) => {
+                                    const compactionId = (0, ai_1.generateId)();
+                                    const { waitUntilComplete } = streams_js_1.streams.writer(exports.CHAT_STREAM_KEY, {
+                                        spanName: "stream compaction chunks",
+                                        collapsed: true,
+                                        execute: async ({ write }) => {
+                                            write({
+                                                type: "data-compaction",
+                                                id: compactionId,
+                                                data: { status: "compacting", totalTokens: turnUsage.totalTokens },
+                                            });
+                                            const summary = await outerCompaction.summarize({
+                                                messages: accumulatedMessages,
+                                                usage: turnUsage,
+                                                totalUsage: cumulativeUsage,
+                                                chatId: currentWirePayload.chatId,
+                                                turn,
+                                                clientData,
+                                                source: "outer",
+                                            });
+                                            // Apply compactModelMessages/compactUIMessages callbacks, or defaults.
+                                            const outerCompactEvent = {
+                                                summary,
+                                                uiMessages: accumulatedUIMessages,
+                                                modelMessages: accumulatedMessages,
+                                                chatId: currentWirePayload.chatId,
+                                                turn,
+                                                clientData,
+                                                source: "outer",
+                                            };
+                                            // Model messages: callback or default (replace with summary)
+                                            accumulatedMessages = outerCompaction.compactModelMessages
+                                                ? await outerCompaction.compactModelMessages(outerCompactEvent)
+                                                : [{ role: "assistant", content: [{ type: "text", text: `[Conversation summary]\n\n${summary}` }] }];
+                                            // UI messages: callback or default (preserve all)
+                                            if (outerCompaction.compactUIMessages) {
+                                                accumulatedUIMessages = await outerCompaction.compactUIMessages(outerCompactEvent);
+                                            }
+                                            // Fire onCompacted hook
+                                            const onCompactedHook = locals_js_1.locals.get(chatOnCompactedKey);
+                                            if (onCompactedHook) {
+                                                await onCompactedHook({
+                                                    summary,
+                                                    messages: accumulatedMessages,
+                                                    messageCount: accumulatedMessages.length,
+                                                    usage: turnUsage,
+                                                    totalTokens: turnUsage.totalTokens,
+                                                    inputTokens: turnUsage.inputTokens,
+                                                    outputTokens: turnUsage.outputTokens,
+                                                    stepNumber: -1, // outer loop, not a step
+                                                    chatId: currentWirePayload.chatId,
+                                                    turn,
+                                                });
+                                            }
+                                            compactionSpan.setAttribute("compaction.summary_length", summary.length);
+                                            write({
+                                                type: "data-compaction",
+                                                id: compactionId,
+                                                data: { status: "complete", totalTokens: turnUsage.totalTokens },
+                                            });
+                                        },
+                                    });
+                                    await waitUntilComplete();
+                                }, {
+                                    attributes: {
+                                        [v3_1.SemanticInternalAttributes.STYLE_ICON]: "tabler-scissors",
+                                        "compaction.total_tokens": turnUsage.totalTokens ?? 0,
+                                        "compaction.input_tokens": turnUsage.inputTokens ?? 0,
+                                        "compaction.message_count": accumulatedMessages.length,
+                                        "compaction.outer_loop": true,
+                                        "compaction.turn": turn,
+                                        ...(currentWirePayload.chatId ? { "compaction.chat_id": currentWirePayload.chatId } : {}),
+                                        ...(0, v3_1.accessoryAttributes)({
+                                            items: [
+                                                { text: `${turnUsage.totalTokens ?? 0} tokens`, variant: "normal" },
+                                                { text: `${accumulatedMessages.length} msgs`, variant: "normal" },
+                                                { text: "outer loop", variant: "normal" },
+                                            ],
+                                            style: "codepath",
+                                        }),
+                                    },
+                                });
+                            }
+                        }
+                        const turnCompleteEvent = {
+                            chatId: currentWirePayload.chatId,
+                            messages: accumulatedMessages,
+                            uiMessages: accumulatedUIMessages,
+                            newMessages: turnNewModelMessages,
+                            newUIMessages: turnNewUIMessages,
+                            responseMessage: capturedResponseMessage,
+                            rawResponseMessage,
+                            turn,
+                            runId: currentRunId,
+                            chatAccessToken: turnAccessToken,
+                            clientData,
+                            stopped: wasStopped,
+                            continuation,
+                            previousRunId,
+                            preloaded,
+                            usage: turnUsage,
+                            totalUsage: cumulativeUsage,
+                        };
+                        // Fire onBeforeTurnComplete — stream is still open so the hook
+                        // can write custom chunks to the frontend (e.g. compaction progress).
+                        if (onBeforeTurnComplete) {
+                            await tracer_js_1.tracer.startActiveSpan("onBeforeTurnComplete()", async () => {
+                                await onBeforeTurnComplete(turnCompleteEvent);
+                                // Check if the hook replaced messages (compaction)
+                                const override = locals_js_1.locals.get(chatOverrideMessagesKey);
+                                if (override) {
+                                    locals_js_1.locals.set(chatOverrideMessagesKey, undefined);
+                                    accumulatedUIMessages = [...override];
+                                    accumulatedMessages = await toModelMessages(override);
+                                    // Update event so onTurnComplete sees compacted messages
+                                    turnCompleteEvent.messages = accumulatedMessages;
+                                    turnCompleteEvent.uiMessages = accumulatedUIMessages;
+                                }
+                            }, {
+                                attributes: {
+                                    [v3_1.SemanticInternalAttributes.STYLE_ICON]: "task-hook-onComplete",
+                                    [v3_1.SemanticInternalAttributes.COLLAPSED]: true,
+                                    "chat.id": currentWirePayload.chatId,
+                                    "chat.turn": turn + 1,
+                                },
+                            });
+                        }
+                        // Write turn-complete control chunk — closes the frontend stream.
+                        const turnCompleteResult = await writeTurnCompleteChunk(currentWirePayload.chatId, turnAccessToken);
+                        // Fire onTurnComplete — stream is closed, use for persistence.
                         if (onTurnComplete) {
                             await tracer_js_1.tracer.startActiveSpan("onTurnComplete()", async () => {
                                 await onTurnComplete({
-                                    chatId: currentWirePayload.chatId,
-                                    messages: accumulatedMessages,
-                                    uiMessages: accumulatedUIMessages,
-                                    newMessages: turnNewModelMessages,
-                                    newUIMessages: turnNewUIMessages,
-                                    responseMessage: capturedResponseMessage,
-                                    rawResponseMessage,
-                                    turn,
-                                    runId: currentRunId,
-                                    chatAccessToken: turnAccessToken,
+                                    ...turnCompleteEvent,
                                     lastEventId: turnCompleteResult.lastEventId,
-                                    clientData,
-                                    stopped: wasStopped,
-                                    continuation,
-                                    previousRunId,
-                                    preloaded,
                                 });
+                                // Check if onTurnComplete replaced messages (compaction)
+                                const turnCompleteOverride = locals_js_1.locals.get(chatOverrideMessagesKey);
+                                if (turnCompleteOverride) {
+                                    locals_js_1.locals.set(chatOverrideMessagesKey, undefined);
+                                    accumulatedUIMessages = [...turnCompleteOverride];
+                                    accumulatedMessages = await toModelMessages(turnCompleteOverride);
+                                }
                             }, {
                                 attributes: {
                                     [v3_1.SemanticInternalAttributes.STYLE_ICON]: "task-hook-onComplete",
@@ -726,19 +1533,24 @@ function chatTask(options) {
                                     "chat.messages.count": accumulatedMessages.length,
                                     "chat.response.parts.count": capturedResponseMessage?.parts?.length ?? 0,
                                     "chat.new_messages.count": turnNewUIMessages.length,
+                                    ...(turnUsage?.inputTokens != null ? { "gen_ai.usage.input_tokens": turnUsage.inputTokens } : {}),
+                                    ...(turnUsage?.outputTokens != null ? { "gen_ai.usage.output_tokens": turnUsage.outputTokens } : {}),
+                                    ...(turnUsage?.totalTokens != null ? { "gen_ai.usage.total_tokens": turnUsage.totalTokens } : {}),
+                                    ...(cumulativeUsage.totalTokens != null ? { "gen_ai.usage.cumulative_total_tokens": cumulativeUsage.totalTokens } : {}),
                                 },
                             });
                         }
-                        // If messages arrived during streaming, use the first one immediately
+                        // If messages arrived during streaming (without pendingMessages config),
+                        // use the first one immediately as the next turn.
                         if (pendingMessages.length > 0) {
                             currentWirePayload = pendingMessages[0];
                             return "continue";
                         }
-                        // Wait for the next message — stay warm briefly, then suspend
-                        const effectiveWarmTimeout = metadata_js_1.metadata.get(WARM_TIMEOUT_METADATA_KEY) ?? warmTimeoutInSeconds;
+                        // Wait for the next message — stay idle briefly, then suspend
+                        const effectiveIdleTimeout = metadata_js_1.metadata.get(IDLE_TIMEOUT_METADATA_KEY) ?? idleTimeoutInSeconds;
                         const effectiveTurnTimeout = metadata_js_1.metadata.get(TURN_TIMEOUT_METADATA_KEY) ?? turnTimeout;
-                        const next = await messagesInput.waitWithWarmup({
-                            warmTimeoutInSeconds: effectiveWarmTimeout,
+                        const next = await messagesInput.waitWithIdleTimeout({
+                            idleTimeoutInSeconds: effectiveIdleTimeout,
                             timeout: effectiveTurnTimeout,
                             spanName: "waiting for next message",
                         });
@@ -787,7 +1599,7 @@ function chatTask(options) {
 // Runtime configuration helpers
 // ---------------------------------------------------------------------------
 const TURN_TIMEOUT_METADATA_KEY = "chat.turnTimeout";
-const WARM_TIMEOUT_METADATA_KEY = "chat.warmTimeout";
+const IDLE_TIMEOUT_METADATA_KEY = "chat.idleTimeout";
 /**
  * Override the turn timeout for subsequent turns in the current run.
  *
@@ -827,24 +1639,24 @@ function setTurnTimeoutInSeconds(seconds) {
     metadata_js_1.metadata.set(TURN_TIMEOUT_METADATA_KEY, `${seconds}s`);
 }
 /**
- * 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 });
  * }
  * ```
  */
-function setWarmTimeoutInSeconds(seconds) {
-    metadata_js_1.metadata.set(WARM_TIMEOUT_METADATA_KEY, seconds);
+function setIdleTimeoutInSeconds(seconds) {
+    metadata_js_1.metadata.set(IDLE_TIMEOUT_METADATA_KEY, seconds);
 }
 /**
  * Override the `toUIMessageStream()` options for the current turn.
@@ -1097,13 +1909,20 @@ async function pipeChatAndCapture(source, options) {
 class ChatMessageAccumulator {
     modelMessages = [];
     uiMessages = [];
+    _compaction;
+    _pendingMessages;
+    _steeringQueue = [];
+    constructor(options) {
+        this._compaction = options?.compaction;
+        this._pendingMessages = options?.pendingMessages;
+    }
     /**
      * Add incoming messages from the transport payload.
      * Returns the full accumulated model messages for `streamText`.
      */
     async addIncoming(messages, trigger, turn) {
         const cleaned = messages.map((m) => m.role === "assistant" ? cleanupAbortedParts(m) : m);
-        const model = await (0, ai_1.convertToModelMessages)(cleaned);
+        const model = await toModelMessages(cleaned);
         if (turn === 0 || trigger === "regenerate-message") {
             this.modelMessages = model;
             this.uiMessages = [...cleaned];
@@ -1118,25 +1937,143 @@ 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.
+     */
+    async setMessages(uiMessages) {
+        this.uiMessages = [...uiMessages];
+        this.modelMessages = await toModelMessages(uiMessages);
+    }
     async addResponse(response) {
         if (!response.id) {
             response = { ...response, id: (0, ai_1.generateId)() };
         }
         this.uiMessages.push(response);
         try {
-            const msgs = await (0, ai_1.convertToModelMessages)([stripProviderMetadata(response)]);
+            const msgs = await toModelMessages([stripProviderMetadata(response)]);
             this.modelMessages.push(...msgs);
         }
         catch {
             // Conversion failed — skip model message accumulation for this response
         }
     }
+    /**
+     * Queue a message for injection via `prepareStep`. Call from a
+     * `messagesInput.on()` listener when a message arrives during streaming.
+     */
+    steer(message, modelMessages) {
+        if (modelMessages) {
+            this._steeringQueue.push({ uiMessage: message, modelMessages });
+        }
+        else {
+            // Defer conversion — will be done in prepareStep if needed
+            this._steeringQueue.push({ uiMessage: message, modelMessages: [] });
+        }
+    }
+    /**
+     * Queue a message for injection, converting to model messages automatically.
+     */
+    async steerAsync(message) {
+        const modelMsgs = await toModelMessages([message]);
+        this._steeringQueue.push({ uiMessage: message, modelMessages: modelMsgs });
+    }
+    /**
+     * Get and clear unconsumed steering messages.
+     */
+    drainSteering() {
+        const result = this._steeringQueue.map((e) => e.uiMessage);
+        this._steeringQueue = [];
+        return result;
+    }
+    /**
+     * Returns a `prepareStep` function that handles both compaction and
+     * pending message injection. Pass to `streamText({ prepareStep: conversation.prepareStep() })`.
+     */
+    prepareStep() {
+        if (!this._compaction && !this._pendingMessages)
+            return undefined;
+        const comp = this._compaction;
+        const pm = this._pendingMessages;
+        const queue = this._steeringQueue;
+        return async ({ messages, steps }) => {
+            let resultMessages;
+            // 1. Compaction
+            if (comp) {
+                const result = await chatCompact(messages, steps, {
+                    shouldCompact: comp.shouldCompact,
+                    summarize: (msgs) => comp.summarize({ messages: msgs, source: "inner" }),
+                });
+                if (result.type !== "skipped") {
+                    resultMessages = result.messages;
+                }
+            }
+            // 2. Pending message injection
+            if (pm && queue.length > 0) {
+                const injected = await drainSteeringQueue(pm, resultMessages ?? messages, steps, queue);
+                if (injected.length > 0) {
+                    resultMessages = [...(resultMessages ?? messages), ...injected];
+                }
+            }
+            return resultMessages ? { messages: resultMessages } : 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.
+     */
+    async compactIfNeeded(usage, context) {
+        if (!this._compaction || !usage)
+            return false;
+        const shouldTrigger = await this._compaction.shouldCompact({
+            messages: this.modelMessages,
+            totalTokens: usage.totalTokens,
+            inputTokens: usage.inputTokens,
+            outputTokens: usage.outputTokens,
+            usage,
+            totalUsage: context?.totalUsage,
+            chatId: context?.chatId,
+            turn: context?.turn,
+            clientData: context?.clientData,
+            source: "outer",
+        });
+        if (!shouldTrigger)
+            return false;
+        const summary = await this._compaction.summarize({
+            messages: this.modelMessages,
+            usage,
+            totalUsage: context?.totalUsage,
+            chatId: context?.chatId,
+            turn: context?.turn,
+            clientData: context?.clientData,
+            source: "outer",
+        });
+        const compactEvent = {
+            summary,
+            uiMessages: this.uiMessages,
+            modelMessages: this.modelMessages,
+            chatId: context?.chatId ?? "",
+            turn: context?.turn ?? 0,
+            clientData: context?.clientData,
+            source: "outer",
+        };
+        this.modelMessages = this._compaction.compactModelMessages
+            ? await this._compaction.compactModelMessages(compactEvent)
+            : [{ role: "assistant", content: [{ type: "text", text: `[Conversation summary]\n\n${summary}` }] }];
+        if (this._compaction.compactUIMessages) {
+            this.uiMessages = await this._compaction.compactUIMessages(compactEvent);
+        }
+        return true;
+    }
 }
 /**
  * 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
@@ -1164,20 +2101,22 @@ class ChatMessageAccumulator {
  * ```
  */
 function createChatSession(payload, options) {
-    const { signal: runSignal, warmTimeoutInSeconds = 30, timeout = "1h", maxTurns = 100, } = options;
+    const { signal: runSignal, idleTimeoutInSeconds = 30, timeout = "1h", maxTurns = 100, compaction: sessionCompaction, pendingMessages: sessionPendingMessages, } = options;
     return {
         [Symbol.asyncIterator]() {
             let currentPayload = payload;
             let turn = -1;
             const stop = createStopSignal();
             const accumulator = new ChatMessageAccumulator();
+            let previousTurnUsage;
+            let cumulativeUsage = emptyUsage();
             return {
                 async next() {
                     turn++;
                     // First turn: handle preload — wait for the first real message
                     if (turn === 0 && currentPayload.trigger === "preload") {
-                        const result = await messagesInput.waitWithWarmup({
-                            warmTimeoutInSeconds: currentPayload.warmTimeoutInSeconds ?? warmTimeoutInSeconds,
+                        const result = await messagesInput.waitWithIdleTimeout({
+                            idleTimeoutInSeconds: currentPayload.idleTimeoutInSeconds ?? idleTimeoutInSeconds,
                             timeout,
                             spanName: "waiting for first message",
                         });
@@ -1189,8 +2128,8 @@ function createChatSession(payload, options) {
                     }
                     // Subsequent turns: wait for the next message
                     if (turn > 0) {
-                        const next = await messagesInput.waitWithWarmup({
-                            warmTimeoutInSeconds,
+                        const next = await messagesInput.waitWithIdleTimeout({
+                            idleTimeoutInSeconds,
                             timeout,
                             spanName: "waiting for next message",
                         });
@@ -1207,6 +2146,44 @@ function createChatSession(payload, options) {
                     }
                     // Reset stop signal for this turn
                     stop.reset();
+                    // Set up steering queue and pending messages config in locals
+                    // so toStreamTextOptions() auto-injects prepareStep for steering
+                    const turnSteeringQueue = [];
+                    locals_js_1.locals.set(chatSteeringQueueKey, turnSteeringQueue);
+                    if (sessionPendingMessages) {
+                        locals_js_1.locals.set(chatPendingMessagesKey, sessionPendingMessages);
+                    }
+                    locals_js_1.locals.set(chatTurnContextKey, {
+                        chatId: currentPayload.chatId,
+                        turn,
+                        continuation: currentPayload.continuation ?? false,
+                        clientData: currentPayload.metadata,
+                    });
+                    // Listen for messages during streaming (steering + next-turn buffer)
+                    const sessionPendingWire = [];
+                    const sessionMsgSub = messagesInput.on(async (msg) => {
+                        sessionPendingWire.push(msg);
+                        if (sessionPendingMessages) {
+                            const lastUIMessage = msg.messages?.[msg.messages.length - 1];
+                            if (lastUIMessage) {
+                                if (sessionPendingMessages.onReceived) {
+                                    try {
+                                        await sessionPendingMessages.onReceived({
+                                            message: lastUIMessage,
+                                            chatId: currentPayload.chatId,
+                                            turn,
+                                        });
+                                    }
+                                    catch { /* non-fatal */ }
+                                }
+                                try {
+                                    const modelMsgs = await toModelMessages([lastUIMessage]);
+                                    turnSteeringQueue.push({ uiMessage: lastUIMessage, modelMessages: modelMsgs });
+                                }
+                                catch { /* non-fatal */ }
+                            }
+                        }
+                    });
                     // Accumulate messages
                     const messages = await accumulator.addIncoming(currentPayload.messages, currentPayload.trigger, turn);
                     const combinedSignal = AbortSignal.any([runSignal, stop.signal]);
@@ -1215,11 +2192,16 @@ function createChatSession(payload, options) {
                         chatId: currentPayload.chatId,
                         trigger: currentPayload.trigger,
                         clientData: currentPayload.metadata,
-                        messages,
-                        uiMessages: accumulator.uiMessages,
+                        get messages() { return accumulator.modelMessages; },
+                        get uiMessages() { return accumulator.uiMessages; },
                         signal: combinedSignal,
                         get stopped() { return stop.signal.aborted && !runSignal.aborted; },
                         continuation: currentPayload.continuation ?? false,
+                        previousTurnUsage,
+                        totalUsage: cumulativeUsage,
+                        async setMessages(uiMessages) {
+                            await accumulator.setMessages(uiMessages);
+                        },
                         async complete(source) {
                             let response;
                             try {
@@ -1229,6 +2211,7 @@ function createChatSession(payload, options) {
                                 if (error instanceof Error && error.name === "AbortError") {
                                     if (runSignal.aborted) {
                                         // Full cancel — don't accumulate
+                                        sessionMsgSub.off();
                                         await chatWriteTurnComplete();
                                         return undefined;
                                     }
@@ -1244,6 +2227,59 @@ function createChatSession(payload, options) {
                                     : response;
                                 await accumulator.addResponse(cleaned);
                             }
+                            // Capture token usage from the streamText result
+                            let turnUsage;
+                            if (typeof source.totalUsage?.then === "function") {
+                                try {
+                                    const usage = await source.totalUsage;
+                                    turnUsage = usage;
+                                    previousTurnUsage = usage;
+                                    cumulativeUsage = addUsage(cumulativeUsage, usage);
+                                }
+                                catch { /* non-fatal */ }
+                            }
+                            // Outer-loop compaction (same logic as chat.task)
+                            if (sessionCompaction && turnUsage && !turnObj.stopped) {
+                                const shouldTrigger = await sessionCompaction.shouldCompact({
+                                    messages: accumulator.modelMessages,
+                                    totalTokens: turnUsage.totalTokens,
+                                    inputTokens: turnUsage.inputTokens,
+                                    outputTokens: turnUsage.outputTokens,
+                                    usage: turnUsage,
+                                    totalUsage: cumulativeUsage,
+                                    chatId: currentPayload.chatId,
+                                    turn,
+                                    clientData: currentPayload.metadata,
+                                    source: "outer",
+                                });
+                                if (shouldTrigger) {
+                                    const summary = await sessionCompaction.summarize({
+                                        messages: accumulator.modelMessages,
+                                        usage: turnUsage,
+                                        totalUsage: cumulativeUsage,
+                                        chatId: currentPayload.chatId,
+                                        turn,
+                                        clientData: currentPayload.metadata,
+                                        source: "outer",
+                                    });
+                                    const compactEvent = {
+                                        summary,
+                                        uiMessages: accumulator.uiMessages,
+                                        modelMessages: accumulator.modelMessages,
+                                        chatId: currentPayload.chatId,
+                                        turn,
+                                        clientData: currentPayload.metadata,
+                                        source: "outer",
+                                    };
+                                    accumulator.modelMessages = sessionCompaction.compactModelMessages
+                                        ? await sessionCompaction.compactModelMessages(compactEvent)
+                                        : [{ role: "assistant", content: [{ type: "text", text: `[Conversation summary]\n\n${summary}` }] }];
+                                    if (sessionCompaction.compactUIMessages) {
+                                        accumulator.uiMessages = await sessionCompaction.compactUIMessages(compactEvent);
+                                    }
+                                }
+                            }
+                            sessionMsgSub.off();
                             await chatWriteTurnComplete();
                             return response;
                         },
@@ -1251,8 +2287,34 @@ function createChatSession(payload, options) {
                             await accumulator.addResponse(response);
                         },
                         async done() {
+                            sessionMsgSub.off();
                             await chatWriteTurnComplete();
                         },
+                        prepareStep() {
+                            const hasCompaction = !!sessionCompaction;
+                            const hasPending = !!sessionPendingMessages;
+                            if (!hasCompaction && !hasPending)
+                                return undefined;
+                            return async ({ messages: stepMsgs, steps }) => {
+                                let resultMessages;
+                                if (sessionCompaction) {
+                                    const compactResult = await chatCompact(stepMsgs, steps, {
+                                        shouldCompact: sessionCompaction.shouldCompact,
+                                        summarize: (msgs) => sessionCompaction.summarize({ messages: msgs, source: "inner" }),
+                                    });
+                                    if (compactResult.type !== "skipped") {
+                                        resultMessages = compactResult.messages;
+                                    }
+                                }
+                                if (sessionPendingMessages) {
+                                    const injected = await drainSteeringQueue(sessionPendingMessages, resultMessages ?? stepMsgs, steps, turnSteeringQueue);
+                                    if (injected.length > 0) {
+                                        resultMessages = [...(resultMessages ?? stepMsgs), ...injected];
+                                    }
+                                }
+                                return resultMessages ? { messages: resultMessages } : undefined;
+                            };
+                        },
                     };
                     return { done: false, value: turnObj };
                 },
@@ -1457,8 +2519,8 @@ exports.chat = {
     setTurnTimeout,
     /** Override the turn timeout at runtime (seconds). See {@link setTurnTimeoutInSeconds}. */
     setTurnTimeoutInSeconds,
-    /** Override the warm timeout at runtime. See {@link setWarmTimeoutInSeconds}. */
-    setWarmTimeoutInSeconds,
+    /** Override the idle timeout at runtime. See {@link setIdleTimeoutInSeconds}. */
+    setIdleTimeoutInSeconds,
     /** Override toUIMessageStream() options for the current turn. See {@link setUIMessageStreamOptions}. */
     setUIMessageStreamOptions,
     /** Check if the current turn was stopped by the user. See {@link isStopped}. */
@@ -1481,6 +2543,33 @@ exports.chat = {
     MessageAccumulator: ChatMessageAccumulator,
     /** Create a chat session (async iterator). See {@link createChatSession}. */
     createSession: 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: Object.assign(getChatPrompt, { set: 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,
+    /**
+     * Replace the accumulated conversation messages for compaction.
+     * Call from `onTurnStart` or `onTurnComplete`. Takes `UIMessage[]` and
+     * converts to `ModelMessage[]` internally.
+     */
+    setMessages: setChatMessages,
+    /** Check if it's safe to compact messages (no in-flight tool calls). */
+    isCompactionSafe,
+    /** Returns a `prepareStep` function that handles context compaction automatically. */
+    compactionStep: chatCompactionStep,
+    /** Low-level compaction for use inside a custom `prepareStep`. */
+    compact: chatCompact,
+    /** Read the current compaction state (summary + base message count). */
+    getCompactionState,
 };
 /**
  * Writes a turn-complete control chunk to the chat output stream.