@trigger.dev/sdk 4.5.12 → 4.5.14

package/dist/esm/v3/ai.js

@@ -1,4 +1,4 @@
-import { accessoryAttributes, apiClientManager, controlSubtype, generateJWT, getSchemaParseFn, headerValue, InputStreamOncePromise, isAdditionalApiKey, isSchemaZodEsque, logger, ManualWaitpointPromise, OutOfMemoryError, resourceCatalog, SemanticInternalAttributes, SESSION_IN_EVENT_ID_HEADER, sessionStreams, taskContext, TRIGGER_CONTROL_SUBTYPE, } from "@trigger.dev/core/v3";
+import { accessoryAttributes, apiClientManager, controlSubtype, generateJWT, getSchemaParseFn, headerValue, InputStreamOncePromise, isAdditionalApiKey, isSchemaZodEsque, logger, ManualWaitpointPromise, OutOfMemoryError, resourceCatalog, SemanticInternalAttributes, SESSION_IN_CONSUMED_ID_HEADER, SESSION_IN_EVENT_ID_HEADER, sessionStreams, SessionChannelRouter, InputStreamTimeoutError, taskContext, TRIGGER_CONTROL_SUBTYPE, } from "@trigger.dev/core/v3";
 // Runtime VALUES go through the ESM/CJS shim so the CJS build can `require`
 // ESM-only `ai@7` (see ../imports/ai-runtime.ts).
 import { trace } from "@opentelemetry/api";
@@ -103,49 +103,6 @@ async function findLatestSessionInCursor(chatId) {
     }
     return latestCursor;
 }
-/** Test-only entry point for the records-based cursor scan. @internal */
-export async function __findLatestSessionInCursorForTests(chatId) {
-    return findLatestSessionInCursor(chatId);
-}
-/**
- * Seed the `.in` resume cursor for custom-agent loops (`chat.customAgent`
- * raw loops and `chat.createSession`) the way `chat.agent`'s boot does.
- *
- * MUST run before anything attaches a `.in` listener (`createStopSignal`,
- * `chat.messages.on`, the first wait): attaching opens the SSE tail with
- * `Last-Event-ID` from the seeded cursor, so attach-then-seed replays
- * every record from seq 0 — already-answered user messages get delivered
- * into the new run's first wait and the loop re-answers them.
- *
- * Seeds both cursors: `setLastSeqNum` controls the SSE `Last-Event-ID`,
- * `setLastDispatchedSeqNum` gates waiter dispatch — seeding only the
- * former still re-delivers records the manager buffered before the seed.
- *
- * No-ops on fresh boots and when a cursor is already seeded (e.g. the
- * `chatCustomAgent` wrapper ran before a nested `createChatSession`).
- * @internal
- */
-async function seedSessionInResumeCursorForCustomLoop(payload) {
-    if (sessionStreams.lastSeqNum(payload.chatId, "in") !== undefined)
-        return;
-    // No continuation/attempt gate: the wire may omit `continuation` on a
-    // run that still has prior turns (chat.agent covers that case via its
-    // snapshot). The scan doubles as the prior-state probe — a fresh
-    // session has no turn-complete on `.out`, returns no cursor, and
-    // seeds nothing. Cost on fresh boots is one non-blocking records read.
-    try {
-        const cursor = await findLatestSessionInCursor(payload.chatId);
-        if (cursor !== undefined) {
-            sessionStreams.setLastSeqNum(payload.chatId, "in", cursor);
-            sessionStreams.setLastDispatchedSeqNum(payload.chatId, "in", cursor);
-        }
-    }
-    catch (error) {
-        logger.warn("chat session: session.in resume cursor lookup failed; old messages may replay", {
-            error: error instanceof Error ? error.message : String(error),
-        });
-    }
-}
 let readChatSnapshotImpl;
 export function __setReadChatSnapshotImplForTests(impl) {
     readChatSnapshotImpl = impl;
@@ -1009,90 +966,508 @@ async function withChatWriter(fn) {
     await flush();
     return result;
 }
-// Input streams for bidirectional chat communication
-//
-// Both `messagesInput` and `stopInput` are thin facades over the current
-// run's Session `.in` channel. The Session carries a single tagged stream
-// (`ChatInputChunk`); these facades filter by `kind` so existing call
-// sites (both internal and exposed via `chat.messages` / `chat.createStopSignal`)
-// keep their original shape. Each accessor resolves the session handle
-// lazily via `getChatSession()` so the module-level references stay
-// compatible with the pre-migration wiring.
+const CHAT_CUSTOM_AGENT_CLIENT_DATA_ERROR_TEXT = "Invalid client data";
+const chatCustomAgentClientDataParserKey = locals.create("chat.customAgentClientDataParser");
+const chatCustomAgentClientDataErrorHandlerKey = locals.create("chat.customAgentClientDataErrorHandler");
+function shouldValidateChatCustomAgentPayload(payload) {
+    return (payload.trigger !== "close" && locals.get(chatCustomAgentClientDataParserKey) !== undefined);
+}
+function assertChatCustomAgentSyncParseResult(result) {
+    if (result && typeof result.then === "function") {
+        void Promise.resolve(result).catch(() => { });
+        throw new Error("chat.messages.peek() cannot validate clientData with an asynchronous schema. " +
+            "Use chat.messages.once(), chat.messages.wait(), or chat.messages.waitWithIdleTimeout().");
+    }
+    return result;
+}
+function getChatCustomAgentSyncSchemaParseFn(schema) {
+    const parser = schema;
+    if (typeof parser === "function" && typeof parser.assert === "function") {
+        return parser.assert.bind(parser);
+    }
+    if (typeof parser === "function") {
+        return (value) => assertChatCustomAgentSyncParseResult(parser(value));
+    }
+    if (typeof parser.parse === "function") {
+        return (value) => assertChatCustomAgentSyncParseResult(parser.parse(value));
+    }
+    if (typeof parser.validateSync === "function") {
+        return parser.validateSync.bind(parser);
+    }
+    if (typeof parser.create === "function") {
+        return parser.create.bind(parser);
+    }
+    if (typeof parser.assert === "function") {
+        return (value) => {
+            parser.assert(value);
+            return value;
+        };
+    }
+    return () => {
+        throw new Error("chat.messages.peek() cannot validate clientData with this schema. " +
+            "Use chat.messages.once(), chat.messages.wait(), or chat.messages.waitWithIdleTimeout().");
+    };
+}
+async function writeChatCustomAgentClientDataErrorToStream(payload) {
+    try {
+        await withChatWriter((writer) => {
+            writer.write({
+                type: "error",
+                errorText: CHAT_CUSTOM_AGENT_CLIENT_DATA_ERROR_TEXT,
+            });
+        });
+        await chatWriteTurnComplete();
+    }
+    catch (signalError) {
+        logger.warn("chat.customAgent: failed to report clientData validation error", {
+            chatId: payload.chatId,
+            trigger: payload.trigger,
+            error: signalError instanceof Error ? signalError.message : String(signalError),
+        });
+    }
+}
+async function reportChatCustomAgentClientDataError(payload, error, options) {
+    const errorText = error instanceof Error ? error.message : "An unexpected error occurred";
+    logger.warn("chat.customAgent: clientData validation failed", {
+        chatId: payload.chatId,
+        trigger: payload.trigger,
+        error: errorText,
+    });
+    const errorHandler = options.callHandler === false
+        ? undefined
+        : locals.get(chatCustomAgentClientDataErrorHandlerKey);
+    if (errorHandler) {
+        try {
+            await errorHandler({ error, payload });
+        }
+        catch (handlerError) {
+            logger.warn("chat.customAgent: clientData validation error handler failed", {
+                chatId: payload.chatId,
+                trigger: payload.trigger,
+                error: handlerError instanceof Error ? handlerError.message : String(handlerError),
+            });
+        }
+    }
+    if (!options.writeToStream) {
+        return;
+    }
+    await writeChatCustomAgentClientDataErrorToStream(payload);
+}
+async function parseChatCustomAgentPayload(payload) {
+    const parser = locals.get(chatCustomAgentClientDataParserKey);
+    if (!parser || payload.trigger === "close") {
+        return { ok: true, payload };
+    }
+    try {
+        const metadata = await parser.parse(payload.metadata);
+        return { ok: true, payload: { ...payload, metadata } };
+    }
+    catch (error) {
+        return { ok: false, error };
+    }
+}
+async function validateChatCustomAgentPayload(payload, options = {}) {
+    const result = await parseChatCustomAgentPayload(payload);
+    if (!result.ok) {
+        await reportChatCustomAgentClientDataError(payload, result.error, {
+            writeToStream: options.writeErrorToStream ?? true,
+        });
+    }
+    return result;
+}
+function validateChatCustomAgentPayloadSync(payload) {
+    const parser = locals.get(chatCustomAgentClientDataParserKey);
+    if (!parser || payload.trigger === "close") {
+        return payload;
+    }
+    try {
+        return { ...payload, metadata: parser.parseSync(payload.metadata) };
+    }
+    catch (error) {
+        logger.warn("chat.customAgent: clientData validation failed in chat.messages.peek()", {
+            chatId: payload.chatId,
+            trigger: payload.trigger,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        throw error;
+    }
+}
+/**
+ * Read one record from a route, suspending the run if nothing is there yet.
+ *
+ * The wake and the read are separate steps: the channel wakes the run, then the
+ * router hands over whatever it routed. Nothing else can take the record in
+ * between, which is what keeps the published cursors and the delivered record
+ * in agreement.
+ * @internal
+ */
+async function waitOnChatRoute(route, options) {
+    const router = chatInputRouter();
+    const session = getChatSession();
+    return tracer.startActiveSpan(options.spanName ?? `chat.${route}.wait()`, async (span) => {
+        const idleMs = (options.idleTimeoutInSeconds ?? 0) * 1000;
+        if (idleMs > 0) {
+            const warm = await router.next(route, { timeoutMs: idleMs });
+            if (warm) {
+                span.setAttribute("wait.resolved", "idle");
+                return { ok: true, output: warm.data, record: warm };
+            }
+        }
+        else {
+            const buffered = await router.next(route, { timeoutMs: 0 });
+            if (buffered) {
+                span.setAttribute("wait.resolved", "buffered");
+                return { ok: true, output: buffered.data, record: buffered };
+            }
+        }
+        if (options.skipSuspend) {
+            span.setAttribute("wait.resolved", "skipped");
+            return {
+                ok: false,
+                error: new Error("Idle timeout elapsed and skipSuspend is set"),
+            };
+        }
+        if (options.onSuspend)
+            await options.onSuspend();
+        span.setAttribute("wait.resolved", "suspended");
+        while (true) {
+            /**
+             * The floor doubles as the wake cursor: the server completes the
+             * waitpoint immediately if anything sits after this sequence, so a
+             * floor that has advanced past an unread record parks a waitpoint
+             * nothing will complete. Recorded on the span so a run that never woke
+             * can be diagnosed from its trace alone.
+             */
+            const wakeFrom = router.resumeFloor();
+            span.setAttribute("wait.lastSeqNum", wakeFrom ?? -1);
+            const wake = await session.in.awaitWake({
+                timeout: options.timeout,
+                lastSeqNum: wakeFrom,
+            });
+            if (!wake.ok) {
+                span.recordException(wake.error);
+                return { ok: false, error: wake.error };
+            }
+            const record = await router.next(route);
+            if (!record)
+                continue;
+            if (options.onResume)
+                await options.onResume();
+            return { ok: true, output: record.data, record };
+        }
+    }, {
+        attributes: {
+            [SemanticInternalAttributes.STYLE_ICON]: "sessions",
+            session: session.id,
+            io: "in",
+            route,
+            ...accessoryAttributes({
+                items: [{ text: `${session.id}.in:${route}`, variant: "normal" }],
+                style: "codepath",
+            }),
+        },
+    });
+}
+/**
+ * Raw `.in` message delivery, with no client-data validation.
+ *
+ * Sits directly on the router's `messages` route, so a record handed to the
+ * handler is consumed and the resume floor is free to advance past it.
+ */
+function subscribeToRawChatMessages(handler) {
+    return chatInputRouter().on(CHAT_ROUTE_MESSAGES, (record) => {
+        const chunk = record.data;
+        void Promise.resolve(handler(chunk.payload)).catch(() => { });
+    });
+}
+/**
+ * Message delivery with client-data validation in front of it.
+ *
+ * Parses are chained so payloads are validated in wire order, which is the
+ * point of the feature: a later message must not be validated against state a
+ * earlier one has not established yet.
+ *
+ * The handler is dispatched but **not** awaited by that chain. Awaiting it
+ * would serialise user code, so one slow or never-resolving handler would stall
+ * delivery of every later message, and only when a schema is declared. Raw
+ * delivery has always been fire-and-forget, so awaiting here would also make
+ * handler concurrency differ between the validated and unvalidated paths for no
+ * stated reason.
+ *
+ * `off()` detaches from the router but does not cancel work already chained:
+ * the parse chain is a live promise chain and runs to completion on its own, so
+ * a frame that arrives just before a turn closes is still parsed and a failure
+ * is still reported (through the `!active` branch). Nothing therefore has to
+ * wait on it, which is why no `drain()` hook is exposed. The one uncovered edge
+ * is a parse still in flight when the task itself returns, where teardown can
+ * cut the report short; give this a bounded wait at the run-end boundary rather
+ * than an unbounded one, since the chain awaits a user-supplied schema.
+ */
+function subscribeToValidatedChatMessages(handler, options = {}) {
+    let active = true;
+    let delivery = Promise.resolve();
+    const subscription = subscribeToRawChatMessages((payload) => {
+        delivery = delivery
+            .then(async () => {
+            const result = await parseChatCustomAgentPayload(payload);
+            if (!result.ok) {
+                if (active) {
+                    // Completing the turn here could close an active response.
+                    await reportChatCustomAgentClientDataError(payload, result.error, {
+                        writeToStream: false,
+                    });
+                }
+                else if (options.onInvalidAfterOff) {
+                    await options.onInvalidAfterOff(payload, result.error);
+                }
+                else {
+                    // The subscription was removed while parsing. Keep the failure
+                    // observable without invoking a user callback after off().
+                    await reportChatCustomAgentClientDataError(payload, result.error, {
+                        writeToStream: false,
+                        callHandler: false,
+                    });
+                }
+                return;
+            }
+            if (active) {
+                void Promise.resolve(handler(result.payload, () => active)).catch(() => { });
+            }
+            else {
+                void Promise.resolve(options.onAfterOff?.(result.payload)).catch(() => { });
+            }
+        })
+            .catch(() => { });
+    });
+    return {
+        off() {
+            active = false;
+            subscription.off();
+        },
+    };
+}
+/**
+ * Validated delivery that does **not** consume.
+ *
+ * The steering path must observe rather than take: a record it does not inject
+ * has to stay queued so a later turn answers it. Validation still runs in wire
+ * order in front of the handler, so `clientData` is parsed before steering code
+ * sees it, and a frame whose parse finishes after the turn closed needs no
+ * buffer of its own, because the record was never removed from the channel.
+ */
+function observeValidatedChatMessages(
+/**
+ * Receives the observed record's own `seqNum`. It is passed per record rather
+ * than tracked outside, because the handler runs after an await: with two
+ * frames in flight a shared slot already holds the newer sequence by the time
+ * the older frame's parse resolves, and the steering queue would then take
+ * the wrong record off the channel.
+ */
+handler) {
+    let active = true;
+    let delivery = Promise.resolve();
+    const claims = locals.get(chatObserverClaimedSeqNumsKey) ??
+        new Map();
+    locals.set(chatObserverClaimedSeqNumsKey, claims);
+    const subscription = chatInputRouter().observe(CHAT_ROUTE_MESSAGES, (record) => {
+        const payload = record.data.payload;
+        const seqNum = record.seqNum;
+        /**
+         * Claimed synchronously, before any await, so a read cannot validate the
+         * same record. The promise lets a read wait for the outcome rather than
+         * spin on a record it is not allowed to take.
+         */
+        let release;
+        const released = new Promise((resolve) => {
+            release = resolve;
+        });
+        claims.set(record.seqNum, { released, release });
+        const releaseClaim = () => {
+            claims.delete(record.seqNum);
+            release();
+        };
+        delivery = delivery
+            .then(async () => {
+            const result = await parseChatCustomAgentPayload(payload);
+            if (!result.ok) {
+                /**
+                 * Reported once, then taken off the channel.
+                 *
+                 * Observing does not consume, so without this the record would be
+                 * read again by the next turn and parsed a second time, firing a
+                 * user-supplied schema and reporting the same failure twice. A frame
+                 * that fails validation is never going to be answered by this run or
+                 * a later one, so removing it loses nothing that was still owed.
+                 */
+                const timing = locals.get(chatCustomAgentClientDataErrorTimingKey) ?? "turn-end";
+                const writeNow = timing === "arrival" || !active;
+                await reportChatCustomAgentClientDataError(payload, result.error, {
+                    writeToStream: writeNow,
+                });
+                if (!writeNow) {
+                    const deferred = locals.get(chatCustomAgentDeferredClientDataErrorsKey) ?? [];
+                    deferred.push(payload);
+                    locals.set(chatCustomAgentDeferredClientDataErrorsKey, deferred);
+                }
+                // Drop the record: an invalid frame is never answered, by this run or
+                // a later one. Released so a waiting read stops waiting, finds it
+                // gone, and goes back to waiting for the next message.
+                chatInputRouter().take(CHAT_ROUTE_MESSAGES, record.seqNum);
+                releaseClaim();
+                return;
+            }
+            // Valid, so release. The record is still queued, and whichever comes
+            // first, an injection or a later turn's read, now owns it.
+            releaseClaim();
+            void Promise.resolve(handler(result.payload, seqNum, () => active)).catch(() => { });
+        })
+            .catch(() => { });
+    });
+    return {
+        off() {
+            active = false;
+            subscription.off();
+        },
+    };
+}
+/**
+ * Whether a record is currently owned by the validating observer.
+ *
+ * A read that pulls one puts it back and keeps waiting, so the observer's parse
+ * stays the only one and the record is not consumed out from under it.
+ */
+function observerClaimFor(record) {
+    return locals.get(chatObserverClaimedSeqNumsKey)?.get(record.seqNum)?.released;
+}
 const messagesInput = {
     id: "chat-messages",
     on(handler) {
-        return getChatSession().in.on((chunk) => {
-            if (chunk.kind === "message") {
-                // Returning `true` marks the record CONSUMED at the manager level:
-                // it is neither buffered for a later `once()` nor re-delivered by
-                // the buffer drain when the next turn re-attaches its handler.
-                // Without this, a message arriving mid-stream was delivered twice
-                // and ran a duplicate turn.
-                void Promise.resolve(handler(chunk.payload)).catch(() => { });
-                return true;
-            }
-            return undefined;
-        });
+        if (!locals.get(chatCustomAgentClientDataParserKey)) {
+            return subscribeToRawChatMessages(handler);
+        }
+        const deliver = (payload) => handler(payload);
+        return subscribeToValidatedChatMessages(deliver, { onAfterOff: deliver });
     },
     once(options) {
-        const ctx = taskContext.ctx;
-        const runId = ctx?.run.id;
         return new InputStreamOncePromise((resolve, reject) => {
-            tracer
-                .startActiveSpan(options?.spanName ?? `chat.messages.once()`, async () => {
-                while (true) {
-                    const result = await getChatSession().in.once(options);
-                    if (!result.ok) {
-                        resolve(result);
+            /**
+             * Same skip-and-wait rule as `waitWithIdleTimeout`: a payload that fails
+             * validation is reported and not surfaced. The timeout is a total budget
+             * across retries, so skipping a frame cannot extend the wait forever.
+             */
+            const deadline = options?.timeoutMs === undefined ? undefined : Date.now() + options.timeoutMs;
+            const take = () => {
+                chatInputRouter()
+                    .next(CHAT_ROUTE_MESSAGES, {
+                    timeoutMs: deadline === undefined ? undefined : Math.max(0, deadline - Date.now()),
+                })
+                    .then(async (record) => {
+                    if (!record) {
+                        resolve({
+                            ok: false,
+                            error: new InputStreamTimeoutError("chat-messages", options?.timeoutMs ?? 0),
+                        });
                         return;
                     }
-                    if (result.output.kind === "message") {
-                        resolve({ ok: true, output: result.output.payload });
+                    const claim = observerClaimFor(record);
+                    if (claim) {
+                        chatInputRouter().untake(CHAT_ROUTE_MESSAGES, record);
+                        await claim;
+                        take();
                         return;
                     }
-                    // Non-message chunks (stops) are handled by the stopInput
-                    // facade's persistent listener; loop and wait for the next.
-                }
-            }, {
-                attributes: {
-                    [SemanticInternalAttributes.STYLE_ICON]: "streams",
-                    [SemanticInternalAttributes.ENTITY_TYPE]: "input-stream",
-                    ...(runId
-                        ? {
-                            [SemanticInternalAttributes.ENTITY_ID]: `${runId}:chat-messages`,
-                        }
-                        : {}),
-                    streamId: "chat-messages",
-                    ...accessoryAttributes({
-                        items: [{ text: "chat-messages", variant: "normal" }],
-                        style: "codepath",
-                    }),
-                },
-            })
-                .catch(reject);
+                    const payload = record.data.payload;
+                    if (!shouldValidateChatCustomAgentPayload(payload)) {
+                        resolve({ ok: true, output: payload });
+                        return;
+                    }
+                    const validated = await validateChatCustomAgentPayload(payload);
+                    if (validated.ok) {
+                        resolve({ ok: true, output: validated.payload });
+                        return;
+                    }
+                    take();
+                }, reject);
+            };
+            take();
         });
     },
     peek() {
-        const chunk = getChatSession().in.peek();
-        if (chunk && chunk.kind === "message")
-            return chunk.payload;
-        return undefined;
+        const record = chatInputRouter().peek(CHAT_ROUTE_MESSAGES);
+        if (!record)
+            return undefined;
+        const payload = record.data.payload;
+        return validateChatCustomAgentPayloadSync(payload);
+    },
+    async hasPending() {
+        return chatInputRouter().hasPending(CHAT_ROUTE_MESSAGES);
+    },
+    async next(options) {
+        const timeoutInSeconds = options?.timeoutInSeconds;
+        if (timeoutInSeconds !== undefined &&
+            (!Number.isFinite(timeoutInSeconds) || timeoutInSeconds < 0)) {
+            throw new TypeError("chat.messages.next() timeoutInSeconds must be a finite non-negative number");
+        }
+        // Consuming read, so it takes the same claim-and-validate path as the other
+        // reads: a record the observer still owns is put back and awaited, and an
+        // invalid payload is reported and skipped rather than surfaced raw.
+        const totalMs = timeoutInSeconds === undefined ? undefined : timeoutInSeconds * 1000;
+        /**
+         * The caller's timeout is a total budget, not a per-attempt one. Skipping an
+         * invalid frame must not buy another full wait, or a client sending invalid
+         * frames faster than the timeout would keep the read blocked indefinitely
+         * and it would never return.
+         */
+        const deadline = totalMs === undefined ? undefined : Date.now() + totalMs;
+        while (true) {
+            const record = await chatInputRouter().next(CHAT_ROUTE_MESSAGES, {
+                timeoutMs: deadline === undefined ? undefined : Math.max(0, deadline - Date.now()),
+            });
+            if (!record)
+                return undefined;
+            const claim = observerClaimFor(record);
+            if (claim) {
+                chatInputRouter().untake(CHAT_ROUTE_MESSAGES, record);
+                await claim;
+                continue;
+            }
+            const chunk = record.data;
+            if (!shouldValidateChatCustomAgentPayload(chunk.payload)) {
+                return { id: record.id, seqNum: record.seqNum, payload: chunk.payload };
+            }
+            const validated = await validateChatCustomAgentPayload(chunk.payload);
+            if (validated.ok) {
+                return { id: record.id, seqNum: record.seqNum, payload: validated.payload };
+            }
+        }
     },
     wait(options) {
         return new ManualWaitpointPromise(async (resolve, reject) => {
             try {
+                // Same skip-and-wait rule as `waitWithIdleTimeout`, looping back into
+                // the suspending wait rather than surfacing an unvalidated payload.
                 while (true) {
-                    const result = await getChatSession().in.wait(options);
+                    const result = await waitOnChatRoute(CHAT_ROUTE_MESSAGES, { timeout: options?.timeout, spanName: options?.spanName });
                     if (!result.ok) {
-                        resolve(result);
+                        resolve({ ok: false, error: result.error ?? new Error("Timed out") });
+                        return;
+                    }
+                    const claim = observerClaimFor(result.record);
+                    if (claim) {
+                        chatInputRouter().untake(CHAT_ROUTE_MESSAGES, result.record);
+                        await claim;
+                        continue;
+                    }
+                    const payload = result.output.payload;
+                    if (!shouldValidateChatCustomAgentPayload(payload)) {
+                        resolve({ ok: true, output: payload });
                         return;
                     }
-                    if (result.output.kind === "message") {
-                        resolve({ ok: true, output: result.output.payload });
+                    const validated = await validateChatCustomAgentPayload(payload);
+                    if (validated.ok) {
+                        resolve({ ok: true, output: validated.payload });
                         return;
                     }
-                    // Stop chunks are handled by the stopInput facade's persistent
-                    // listener; loop back into the suspending wait.
                 }
             }
             catch (error) {
@@ -1101,102 +1476,75 @@ const messagesInput = {
         });
     },
     async waitWithIdleTimeout(options) {
+        /**
+         * A payload that fails client-data validation is reported and skipped
+         * rather than surfaced, so the caller never sees an unvalidated
+         * `clientData`. The loop waits for the next message instead of returning an
+         * error, which keeps a single bad client send from ending the turn.
+         */
         while (true) {
-            const result = await getChatSession().in.waitWithIdleTimeout(options);
+            const result = await waitOnChatRoute(CHAT_ROUTE_MESSAGES, options);
             if (!result.ok)
-                return result;
-            if (result.output.kind === "message") {
-                return { ok: true, output: result.output.payload };
+                return { ok: false, error: result.error };
+            const claim = observerClaimFor(result.record);
+            if (claim) {
+                chatInputRouter().untake(CHAT_ROUTE_MESSAGES, result.record);
+                await claim;
+                continue;
+            }
+            const payload = result.output.payload;
+            if (!shouldValidateChatCustomAgentPayload(payload)) {
+                return { ok: true, output: payload };
+            }
+            const validated = await validateChatCustomAgentPayload(payload);
+            if (validated.ok) {
+                return { ok: true, output: validated.payload };
             }
-            // Swallow stop-kind chunks — persistent stop listener already handled
-            // the abort; we just loop for the next message.
         }
     },
     async send(_runId, data, options) {
-        // The `runId` argument is kept for signature parity with
-        // `RealtimeDefinedInputStream` but ignored — sessions are addressed
-        // by sessionId, not runId. Callers producing messages from outside
-        // the run should prefer the transport's `session.in.send(...)` path.
         await getChatSession().in.send({ kind: "message", payload: data }, options?.requestOptions);
     },
 };
 const stopInput = {
     id: "chat-stop",
     on(handler) {
-        return getChatSession().in.on((chunk) => {
-            if (chunk.kind === "stop") {
-                // Consume stop records (see the messages facade above). A stop is
-                // only meaningful to the turn it interrupts — buffering it would
-                // let a stale stop abort a future turn.
-                void Promise.resolve(handler({ stop: true, message: chunk.message })).catch(() => { });
-                return true;
-            }
-            return undefined;
+        return chatInputRouter().on(CHAT_ROUTE_STOP, (record) => {
+            const chunk = record.data;
+            void Promise.resolve(handler({ stop: true, message: chunk.message })).catch(() => { });
         });
     },
     once(options) {
-        const ctx = taskContext.ctx;
-        const runId = ctx?.run.id;
         return new InputStreamOncePromise((resolve, reject) => {
-            tracer
-                .startActiveSpan(options?.spanName ?? `chat.stop.once()`, async () => {
-                while (true) {
-                    const result = await getChatSession().in.once(options);
-                    if (!result.ok) {
-                        resolve(result);
-                        return;
-                    }
-                    if (result.output.kind === "stop") {
-                        resolve({
-                            ok: true,
-                            output: { stop: true, message: result.output.message },
-                        });
-                        return;
-                    }
+            chatInputRouter()
+                .next(CHAT_ROUTE_STOP, { timeoutMs: options?.timeoutMs })
+                .then((record) => {
+                if (!record) {
+                    resolve({
+                        ok: false,
+                        error: new InputStreamTimeoutError("chat-stop", options?.timeoutMs ?? 0),
+                    });
+                    return;
                 }
-            }, {
-                attributes: {
-                    [SemanticInternalAttributes.STYLE_ICON]: "streams",
-                    [SemanticInternalAttributes.ENTITY_TYPE]: "input-stream",
-                    ...(runId
-                        ? {
-                            [SemanticInternalAttributes.ENTITY_ID]: `${runId}:chat-stop`,
-                        }
-                        : {}),
-                    streamId: "chat-stop",
-                    ...accessoryAttributes({
-                        items: [{ text: "chat-stop", variant: "normal" }],
-                        style: "codepath",
-                    }),
-                },
-            })
-                .catch(reject);
+                const chunk = record.data;
+                resolve({ ok: true, output: { stop: true, message: chunk.message } });
+            }, reject);
         });
     },
     peek() {
-        const chunk = getChatSession().in.peek();
-        if (chunk && chunk.kind === "stop") {
-            return { stop: true, message: chunk.message };
-        }
-        return undefined;
+        const record = chatInputRouter().peek(CHAT_ROUTE_STOP);
+        if (!record)
+            return undefined;
+        const chunk = record.data;
+        return { stop: true, message: chunk.message };
     },
     wait(options) {
         return new ManualWaitpointPromise(async (resolve, reject) => {
             try {
-                while (true) {
-                    const result = await getChatSession().in.wait(options);
-                    if (!result.ok) {
-                        resolve(result);
-                        return;
-                    }
-                    if (result.output.kind === "stop") {
-                        resolve({
-                            ok: true,
-                            output: { stop: true, message: result.output.message },
-                        });
-                        return;
-                    }
-                }
+                const result = await waitOnChatRoute(CHAT_ROUTE_STOP, { timeout: options?.timeout, spanName: options?.spanName });
+                resolve(result.ok
+                    ? { ok: true, output: { stop: true, message: result.output.message } }
+                    : { ok: false, error: result.error ?? new Error("Timed out") });
             }
             catch (error) {
                 reject(error);
@@ -1204,14 +1552,10 @@ const stopInput = {
         });
     },
     async waitWithIdleTimeout(options) {
-        while (true) {
-            const result = await getChatSession().in.waitWithIdleTimeout(options);
-            if (!result.ok)
-                return result;
-            if (result.output.kind === "stop") {
-                return { ok: true, output: { stop: true, message: result.output.message } };
-            }
-        }
+        const result = await waitOnChatRoute(CHAT_ROUTE_STOP, options);
+        return result.ok
+            ? { ok: true, output: { stop: true, message: result.output.message } }
+            : { ok: false, error: result.error };
     },
     async send(_runId, data, options) {
         await getChatSession().in.send({ kind: "stop", message: data?.message }, options?.requestOptions);
@@ -1225,17 +1569,8 @@ const stopInput = {
  */
 const handoverInput = {
     async waitWithIdleTimeout(options) {
-        while (true) {
-            const result = await getChatSession().in.waitWithIdleTimeout(options);
-            if (!result.ok)
-                return result;
-            if (result.output.kind === "handover" || result.output.kind === "handover-skip") {
-                return { ok: true, output: result.output };
-            }
-            // Other kinds (message, stop) are not expected during handover-prepare.
-            // Loop back; the message and stop facades have their own listeners
-            // running so signals on those kinds aren't lost.
-        }
+        const result = await waitOnChatRoute(CHAT_ROUTE_HANDOVER, options);
+        return result.ok ? { ok: true, output: result.output } : result;
     },
 };
 /**
@@ -1251,22 +1586,229 @@ const handoverInput = {
  * For the common case prefer `accumulator.consumeHandover()`, which also seeds
  * `payload.headStartMessages` and applies the partial for you.
  *
- * Must be called at turn 0 before any `chat.messages.waitWithIdleTimeout` —
- * that facade consumes and discards non-message chunks, which would swallow the
- * handover signal.
+ * Safe to call at any point in turn 0: the handover signal has its own route,
+ * so a message facade waiting at the same time cannot take it.
  */
 async function waitForHandover(options) {
     if (options.payload.trigger !== "handover-prepare")
         return null;
-    const result = await handoverInput.waitWithIdleTimeout({
-        idleTimeoutInSeconds: options.idleTimeoutInSeconds ?? options.payload.idleTimeoutInSeconds ?? 60,
-        timeout: options.timeout,
-        spanName: options.spanName ?? "waiting for handover signal",
+    try {
+        const result = await handoverInput.waitWithIdleTimeout({
+            idleTimeoutInSeconds: options.idleTimeoutInSeconds ?? options.payload.idleTimeoutInSeconds ?? 60,
+            timeout: options.timeout,
+            spanName: options.spanName ?? "waiting for handover signal",
+        });
+        // Non-ok = idle timeout or the warm handler crashed without signaling.
+        if (!result.ok)
+            return null;
+        return result.output;
+    }
+    finally {
+        chatInputRouter().clearRoute(CHAT_ROUTE_HANDOVER);
+    }
+}
+/**
+ * Everything `session.in` carries, and what happens to each kind.
+ *
+ * A route's two properties are what make the resume protocol derivable rather
+ * than hand-maintained. `messages` is replayable because losing a user message
+ * is data loss. `stop` is neither queued nor replayable: it only means anything
+ * to the turn that is live when it lands, and a replayed one would abort
+ * whichever turn happened to be running. `handover` is queued but not
+ * replayable, because it can arrive before its consumer is ready yet is
+ * meaningless to any later boot.
+ *
+ * A kind absent from this table has no consumer, so the router discards it
+ * instead of letting it park at the head of a queue.
+ * @internal
+ */
+const CHAT_INPUT_ROUTES = {
+    kindOf: (data) => data?.kind,
+    routes: [
+        { name: "messages", delivery: "queue", replayable: true, kinds: ["message"] },
+        { name: "stop", delivery: "at-arrival", replayable: false, kinds: ["stop"] },
+        {
+            name: "handover",
+            delivery: "queue",
+            replayable: false,
+            kinds: ["handover", "handover-skip"],
+        },
+    ],
+};
+const CHAT_ROUTE_MESSAGES = "messages";
+const CHAT_ROUTE_STOP = "stop";
+const CHAT_ROUTE_HANDOVER = "handover";
+/**
+ * The `.in` router for the run this worker is currently serving.
+ *
+ * One slot rather than a map, because the facades have to reach the same router
+ * the boot attached without depending on a locals scope being active. Tagged
+ * with the run as well as the chat: a warm process is reused across runs and the
+ * executor tears the channel subscription down at the end of each one, so
+ * reusing a router across runs would leave the new run with no input at all. A
+ * nested `chat.createSession` within the same run still shares it.
+ * @internal
+ */
+let currentChatInputRouter;
+/**
+ * Both cursors from the latest `turn-complete` on `.out`, in one scan.
+ *
+ * Absent for a chat whose turns predate the headers, in which case the router
+ * starts from the beginning of the channel and nothing is treated as replayed.
+ * @internal
+ */
+async function findLatestSessionInCheckpoint(chatId) {
+    const apiClient = apiClientManager.clientOrThrow();
+    const response = await apiClient.readSessionStreamRecords(chatId, "out");
+    const checkpoint = {};
+    for (const record of response.records) {
+        if (controlSubtype(record.headers) !== TRIGGER_CONTROL_SUBTYPE.TURN_COMPLETE)
+            continue;
+        const resumeFrom = Number.parseInt(headerValue(record.headers, SESSION_IN_EVENT_ID_HEADER) ?? "", 10);
+        if (Number.isFinite(resumeFrom))
+            checkpoint.resumeFrom = resumeFrom;
+        const appliedThrough = Number.parseInt(headerValue(record.headers, SESSION_IN_CONSUMED_ID_HEADER) ?? "", 10);
+        if (Number.isFinite(appliedThrough))
+            checkpoint.appliedThrough = appliedThrough;
+    }
+    return checkpoint;
+}
+/**
+ * The highest `.in` sequence already on the channel at boot, above the floor.
+ *
+ * Everything already on the channel when a run boots is, by definition, not
+ * arriving live on this run, so the channel's own tail is the end of this run's
+ * replay window.
+ *
+ * The turn boundary's value is not enough on its own. A boundary is written when
+ * a turn ends, so a control record that arrived after the last boundary is not
+ * covered by it, and a boundary written by an older SDK does not carry one at
+ * all. Both cases leave an already-applied record looking live.
+ *
+ * Bounded by `afterEventId` when a floor is known, which is the common case, so
+ * the read covers the replay window rather than the conversation. An absent
+ * floor means no boundary has committed a cursor yet, and the channel is still
+ * short.
+ *
+ * Returns `undefined` if the read fails; the caller then falls back to the
+ * floor, which is the previous release's behaviour.
+ * @internal
+ */
+async function findSessionInReplayWindowEnd(chatId, afterSeqNum) {
+    try {
+        const apiClient = apiClientManager.clientOrThrow();
+        const response = await apiClient.readSessionStreamRecords(chatId, "in", {
+            ...(afterSeqNum === undefined ? {} : { afterEventId: String(afterSeqNum) }),
+        });
+        let highest;
+        for (const record of response.records) {
+            const seqNum = typeof record.seqNum === "number" ? record.seqNum : Number.NaN;
+            if (Number.isFinite(seqNum) && (highest === undefined || seqNum > highest)) {
+                highest = seqNum;
+            }
+        }
+        return highest;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Attach the `.in` router for this run.
+ *
+ * Reads the checkpoint and subscribes in one call, so there is no window in
+ * which a listener is attached before the resume cursor is seeded. Attaching
+ * first would open the tail at sequence 0 and replay every record the previous
+ * run already answered, which is a mistake the previous shape of this code made
+ * possible and this shape does not.
+ *
+ * The router consumes every record at dispatch, so the channel's own buffer
+ * stays empty for chat and its cursor bookkeeping never engages. Delivery,
+ * ordering and the published cursors are the router's, entirely.
+ * @internal
+ */
+async function installChatInputRouter(chatId, options) {
+    const entry = chatInputRouterEntry(chatId);
+    if (entry.attached)
+        return entry.router;
+    let checkpoint = {};
+    try {
+        checkpoint = await findLatestSessionInCheckpoint(chatId);
+    }
+    catch (error) {
+        logger.warn("chat session: session.in resume cursor lookup failed; old messages may replay", {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+    if (checkpoint.resumeFrom === undefined && options?.fallbackResumeFrom !== undefined) {
+        checkpoint.resumeFrom = options.fallbackResumeFrom;
+    }
+    // Only a resuming run has a replay window. On a first boot nothing has been
+    // applied by anyone, so treating what is already on the channel as replayed
+    // would discard a signal that arrived before the agent got here, which is
+    // exactly how a head-start handover reaches a cold run.
+    const resuming = checkpoint.resumeFrom !== undefined || options?.resuming === true;
+    if (resuming) {
+        const replayWindowEnd = await findSessionInReplayWindowEnd(chatId, checkpoint.resumeFrom);
+        if (replayWindowEnd !== undefined) {
+            checkpoint.appliedThrough = Math.max(checkpoint.appliedThrough ?? replayWindowEnd, replayWindowEnd);
+        }
+    }
+    const router = entry.router;
+    router.restore(checkpoint);
+    const floor = router.resumeFrom();
+    if (floor !== undefined) {
+        sessionStreams.setLastSeqNum(chatId, "in", floor);
+        sessionStreams.setLastDispatchedSeqNum(chatId, "in", floor);
+    }
+    sessionStreams.onRecord(chatId, "in", (record) => {
+        router.ingest(record);
+        return true;
     });
-    // Non-ok = idle timeout or the warm handler crashed without signaling.
-    if (!result.ok)
-        return null;
-    return result.output;
+    entry.attached = true;
+    return router;
+}
+function chatInputRouterEntry(chatId) {
+    const runId = taskContext.ctx?.run.id;
+    if (currentChatInputRouter?.chatId === chatId && currentChatInputRouter.runId === runId) {
+        return currentChatInputRouter;
+    }
+    currentChatInputRouter = {
+        chatId,
+        runId,
+        router: new SessionChannelRouter(CHAT_INPUT_ROUTES, {
+            onDrop: (record, reason) => {
+                if (reason === "unroutable" || reason === "malformed") {
+                    logger.warn("chat: discarded a session.in record nothing on this worker can consume", {
+                        reason,
+                        seqNum: record.seqNum,
+                    });
+                }
+            },
+        }),
+        attached: false,
+    };
+    return currentChatInputRouter;
+}
+/** Drop the router so the next boot attaches a fresh one. @internal */
+export function __resetChatInputRouterForTests() {
+    currentChatInputRouter = undefined;
+}
+/** The cursors this run would publish on its next turn boundary. @internal */
+export function __chatInputCheckpointForTests() {
+    return currentChatInputRouter?.router.checkpoint() ?? {};
+}
+/** Test-only entry point for the turn-boundary cursor scan. @internal */
+export async function __findLatestSessionInCheckpointForTests(chatId) {
+    return findLatestSessionInCheckpoint(chatId);
+}
+/**
+ * This chat's router. Created on first use so a facade reached before the
+ * install still shares the one the install will attach.
+ * @internal
+ */
+function chatInputRouter() {
+    return chatInputRouterEntry(getChatSession().id).router;
 }
 /**
  * Per-turn deferred promises. Registered via `chat.defer()`, awaited
@@ -1862,6 +2404,30 @@ const chatCompactionStateKey = locals.create("chat.compaction");
 const chatOnCompactedKey = locals.create("chat.onCompacted");
 /** @internal Full task `ctx` for the active `chat.agent` run (for hooks invoked from nested compaction). */
 const chatAgentRunContextKey = locals.create("chat.agentRunContext");
+/** @internal When a mid-turn validation failure writes its terminal error. */
+const chatCustomAgentClientDataErrorTimingKey = locals.create("chat.customAgent.clientDataErrorTiming");
+/**
+ * @internal Client-data errors held back until the open turn closes.
+ *
+ * The default timing exists so a bad send cannot truncate an answer already
+ * being read, which means the write has to happen later rather than not at all:
+ * the callback and the task log are server-side, so dropping the stream write
+ * would leave the client with no signal that its frame was rejected.
+ */
+const chatCustomAgentDeferredClientDataErrorsKey = locals.create("chat.customAgent.deferredClientDataErrors");
+/**
+ * @internal Sequences the validating observer has claimed.
+ *
+ * The observer watches without consuming, so a record it is still validating is
+ * also visible to a turn's read. Claiming makes ownership single: a read that
+ * pulls a claimed record puts it back and keeps waiting, so exactly one of them
+ * validates it and the schema runs once per frame.
+ */
+const chatObserverClaimedSeqNumsKey = locals.create("chat.customAgent.observerClaims");
+/** @internal Marks the root run created by `chat.customAgent()`. */
+const chatCustomAgentRunKey = locals.create("chat.customAgentRun");
+/** @internal Number of active `chat.createSession()` iterators in this run. */
+const chatActiveSessionIteratorsKey = locals.create("chat.createSession.activeIterators");
 const chatPrepareMessagesKey = locals.create("chat.prepareMessages");
 /**
  * @internal The raw `tools` option from `chat.agent({ tools })`, either a
@@ -2267,7 +2833,14 @@ async function drainSteeringQueue(config, messages, steps, queueOverride) {
         return [];
     const ctx = locals.get(chatTurnContextKey);
     const stepNumber = steps.length - 1;
-    const uiMessages = queue.map((e) => e.uiMessage);
+    /**
+     * Snapshot, because `shouldInject` and `prepare` can await. A record arriving
+     * during either is not in this batch, so it must not be consumed by it: the
+     * callbacks never saw it and could not have injected it, and taking it would
+     * lose a message that should become a later turn instead.
+     */
+    const batch = [...queue];
+    const uiMessages = batch.map((e) => e.uiMessage);
     const batchEvent = {
         messages: uiMessages,
         modelMessages: messages,
@@ -2281,22 +2854,79 @@ async function drainSteeringQueue(config, messages, steps, queueOverride) {
     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 ?? [])
+    const textOfUIMessage = (m) => (m.parts ?? [])
         .filter((p) => p.type === "text")
         .map((p) => p.text)
-        .join("") || "");
+        .join("") || "";
+    // Span attributes describe the offered batch; the chunk and callback below
+    // describe what was actually claimed and injected.
+    const messageTexts = uiMessages.map(textOfUIMessage);
     const _previewText = messageTexts.length === 1 ? messageTexts[0].slice(0, 80) : `${queue.length} messages`;
     return 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;
+        /**
+         * Claim before transforming, and inject only what was claimed.
+         *
+         * Injection is the point of consumption: the records were only observed
+         * on arrival, so they are still queued on the router and still holding
+         * the resume floor, and taking them here is what stops the same message
+         * also being answered as a later turn. A declined batch never reaches
+         * this line, so its records stay queued and become later turns, which is
+         * what "messages queue for the next turn" means.
+         *
+         * A failed claim means something else already consumed that record while
+         * `shouldInject` was awaiting, so it is already being answered as a turn
+         * of its own. Injecting it as well would process the same message twice.
+         * An entry with no `seqNum` did not come from a channel record (the
+         * accumulator's own queue), so there is nothing to claim and it is kept.
+         */
+        const router = chatInputRouter();
+        const claimed = [];
+        const takenRecords = [];
+        for (const entry of batch) {
+            if (entry.seqNum === undefined) {
+                claimed.push(entry);
+                continue;
+            }
+            const record = router.take(CHAT_ROUTE_MESSAGES, entry.seqNum);
+            if (!record)
+                continue;
+            takenRecords.push(record);
+            claimed.push(entry);
+        }
+        for (const entry of claimed) {
+            const at = queue.indexOf(entry);
+            if (at !== -1)
+                queue.splice(at, 1);
+        }
+        if (claimed.length === 0)
+            return [];
+        /**
+         * Give the claim back if the transform fails. `prepare` is caller code and
+         * can throw; the records have already left the router by this point, so
+         * without returning them a failed transform would consume the messages and
+         * they would never be answered at all.
+         */
+        const releaseClaim = () => {
+            for (const record of takenRecords)
+                router.untake(CHAT_ROUTE_MESSAGES, record);
+            for (const entry of claimed)
+                if (!queue.includes(entry))
+                    queue.push(entry);
+        };
+        const claimedUIMessages = claimed.map((e) => e.uiMessage);
+        let injected;
+        try {
+            injected = config.prepare
+                ? await config.prepare({ ...batchEvent, messages: claimedUIMessages })
+                : claimed.flatMap((e) => e.modelMessages);
+        }
+        catch (err) {
+            releaseClaim();
+            throw err;
+        }
         const injectedIds = locals.get(chatInjectedMessageIdsKey);
         if (injectedIds) {
-            for (const m of uiMessages)
+            for (const m of claimedUIMessages)
                 injectedIds.add(m.id);
         }
         // Write injection confirmation chunk to the stream so the frontend
@@ -2310,10 +2940,10 @@ async function drainSteeringQueue(config, messages, steps, queueOverride) {
                             type: PENDING_MESSAGE_INJECTED_TYPE,
                             id: generateMessageId(),
                             data: {
-                                messageIds: uiMessages.map((m) => m.id),
-                                messages: uiMessages.map((m, idx) => ({
+                                messageIds: claimedUIMessages.map((m) => m.id),
+                                messages: claimedUIMessages.map((m) => ({
                                     id: m.id,
-                                    text: messageTexts[idx] ?? "",
+                                    text: textOfUIMessage(m),
                                 })),
                             },
                         });
@@ -2329,7 +2959,7 @@ async function drainSteeringQueue(config, messages, steps, queueOverride) {
         if (config.onInjected && injected.length > 0) {
             try {
                 await config.onInjected({
-                    messages: uiMessages,
+                    messages: claimedUIMessages,
                     injectedModelMessages: injected,
                     chatId: ctx?.chatId ?? "",
                     turn: ctx?.turn ?? 0,
@@ -2763,7 +3393,11 @@ async function pipeChat(source, options) {
     await waitUntilComplete();
 }
 function chatCustomAgent(options) {
-    const { clientDataSchema, run: userRun, ...restOptions } = options;
+    const { clientDataSchema, onClientDataValidationError, clientDataReportErrorAt, run: userRun, ...restOptions } = options;
+    const parseClientData = clientDataSchema ? getSchemaParseFn(clientDataSchema) : undefined;
+    const parseClientDataSync = clientDataSchema
+        ? getChatCustomAgentSyncSchemaParseFn(clientDataSchema)
+        : undefined;
     const task = createTask({
         ...restOptions,
         triggerSource: "agent",
@@ -2782,6 +3416,17 @@ function chatCustomAgent(options) {
             locals.set(chatSessionHandleKey, sessions.open(payload.chatId));
             locals.set(chatExternalIdKey, payload.chatId);
             locals.set(chatAgentRunContextKey, runOptions.ctx);
+            locals.set(chatCustomAgentRunKey, true);
+            if (parseClientData && parseClientDataSync) {
+                locals.set(chatCustomAgentClientDataParserKey, {
+                    parse: parseClientData,
+                    parseSync: parseClientDataSync,
+                });
+            }
+            if (onClientDataValidationError) {
+                locals.set(chatCustomAgentClientDataErrorHandlerKey, onClientDataValidationError);
+            }
+            locals.set(chatCustomAgentClientDataErrorTimingKey, clientDataReportErrorAt ?? "turn-end");
             // Initialize the turn-complete trim slot so `chat.writeTurnComplete`
             // trims `session.out` back to the previous turn boundary. Without
             // this the slot is undefined and the trim never runs, so `.out`
@@ -2790,11 +3435,65 @@ function chatCustomAgent(options) {
             markChatAgentRunForStreamsWarning();
             taskContext.setConversationId(payload.chatId);
             stampConversationIdOnActiveSpan(payload.chatId);
-            // Seed the `.in` resume cursor before user code attaches any `.in`
-            // listener — otherwise a continuation boot replays already-answered
-            // messages into the loop's first wait.
-            await seedSessionInResumeCursorForCustomLoop(payload);
-            return userRun(payload, runOptions);
+            await installChatInputRouter(payload.chatId, {
+                resuming: Boolean(payload.continuation),
+            });
+            // Keep the schema-free path identical to the original custom-agent
+            // wrapper, including when userRun starts executing.
+            if (!parseClientData) {
+                return userRun(payload, runOptions);
+            }
+            const isHandoverBoot = payload.trigger === "handover-prepare";
+            const isMessagelessBoot = payload.trigger === "preload" ||
+                (payload.continuation === true &&
+                    payload.message === undefined &&
+                    payload.trigger !== "action" &&
+                    payload.trigger !== "regenerate-message" &&
+                    !isHandoverBoot);
+            const validated = await validateChatCustomAgentPayload(payload, {
+                // Preload and continuation boots do not represent a submitted turn,
+                // so there is no sender waiting for a terminal frame. Handover errors
+                // must be written after the warm response flushes and signals below.
+                writeErrorToStream: !isMessagelessBoot && !isHandoverBoot,
+            });
+            if (validated.ok) {
+                return userRun(validated.payload, runOptions);
+            }
+            if (isHandoverBoot) {
+                const signal = await waitForHandover({
+                    payload,
+                    timeout: "1h",
+                    spanName: "waiting for handover signal (invalid clientData)",
+                });
+                if (!signal || signal.kind === "handover-skip") {
+                    return;
+                }
+                // The head-start writer flushes before sending this signal. Writing
+                // the terminal error now preserves stream order and closes the stitch.
+                await writeChatCustomAgentClientDataErrorToStream(payload);
+                return;
+            }
+            // The Session base payload is sticky across continuation runs. If it is
+            // invalid, returning here would boot the same bad metadata again on the
+            // next message. Stay attached and wait for a valid wire frame instead.
+            const next = await messagesInput.waitWithIdleTimeout({
+                idleTimeoutInSeconds: payload.idleTimeoutInSeconds ?? 30,
+                timeout: "1h",
+                spanName: "waiting for valid clientData",
+            });
+            if (!next.ok || next.output.trigger === "close") {
+                return;
+            }
+            // Normal input frames omit run-level boot context. Carry it forward so
+            // a continuation still tells the custom loop to restore prior state.
+            const recoveredPayload = {
+                ...next.output,
+                continuation: next.output.continuation ?? payload.continuation,
+                previousRunId: next.output.previousRunId ?? payload.previousRunId,
+                sessionId: next.output.sessionId ?? payload.sessionId,
+                idleTimeoutInSeconds: next.output.idleTimeoutInSeconds ?? payload.idleTimeoutInSeconds,
+            };
+            return userRun(recoveredPayload, runOptions);
         },
     });
     // Register clientDataSchema so the CLI converts it to JSONSchema
@@ -2824,6 +3523,7 @@ function chatAgent(options) {
         agentConfig: { type: "ai-sdk-chat" },
         run: async (payload, { signal: runSignal, ctx }) => {
             locals.set(chatAgentRunContextKey, ctx);
+            locals.set(chatCustomAgentRunKey, false);
             // On AI SDK 7, register the `@ai-sdk/otel` integration (once per process)
             // so `experimental_telemetry` spans flow into the run trace. Awaited here
             // at run boot — before any `streamText` — and a no-op on v5/v6 or when the
@@ -2916,11 +3616,6 @@ function chatAgent(options) {
             // default, `inFlightUsers`). The turn-loop checks this queue ahead of
             // `messagesInput.waitWithIdleTimeout` so recovered turns fire first.
             const bootInjectedQueue = [];
-            // Messages consumed by a turn's `messagesInput.on` handler, dispatched
-            // one per turn by the end-of-turn pickup. Loop-level on purpose:
-            // consuming a record advances the committed `.in` cursor, so entries
-            // dropped with a turn-local buffer are lost permanently.
-            const pendingWireMessages = [];
             const couldHavePriorState = payload.continuation === true || ctx.attempt.number > 1;
             // `.in` resume cursor, computed at most once per boot. The boot
             // block below resolves it (snapshot field or records scan) and the
@@ -3043,49 +3738,16 @@ function chatAgent(options) {
                     },
                 });
             }
-            // ── session.in resume cursor ───────────────────────────────────
-            //
-            // A fresh worker subscribes to `session.in` from seq 0 and would
-            // re-deliver every record ever appended — including user messages
-            // from turns already completed on a prior run. Without a cursor,
-            // the loop would re-process them as fresh turns and the slim-wire
-            // merge would replace-by-id against snapshot-restored copies,
-            // yielding no-op replaces while the customer's actual new message
-            // waits in the queue.
+            // ── session.in router ──────────────────────────────────────────
             //
-            // The cursor is the seq_num of the last `.in` record the prior
-            // worker committed to processing, persisted on each `turn-complete`
-            // control record as a `session-in-event-id` sibling header. The
-            // boot scan reads the header off `.out`'s latest turn-complete and
-            // seeds the manager so the upcoming `.in` SSE subscribe opens with
-            // `Last-Event-ID: <cursor>` — S2 starts after that seq and old
-            // messages never reach this worker.
-            //
-            // Applies in three cases (any of which means `.in` has records
-            // belonging to completed turns the new run should skip):
-            //  - OOM retry (`ctx.attempt.number > 1`)
-            //  - Continuation run (`payload.continuation === true`) — prior run
-            //    crashed / was canceled / requested upgrade
-            //  - Snapshot exists at all (catches edge cases where the wire
-            //    didn't set `continuation` but a snapshot indicates prior turns)
-            const needsResumeCursor = ctx.attempt.number > 1 || payload.continuation === true || bootSnapshot !== undefined;
-            if (needsResumeCursor) {
-                try {
-                    // Reuse the cursor the boot block already resolved (snapshot
-                    // field or records scan) — only scan here when the boot block
-                    // was skipped (hydrateMessages, or snapshot-only signals).
-                    const cursor = bootInCursorResolved
-                        ? bootInCursor
-                        : await findLatestSessionInCursor(payload.chatId);
-                    if (cursor !== undefined) {
-                        sessionStreams.setLastSeqNum(payload.chatId, "in", cursor);
-                        sessionStreams.setLastDispatchedSeqNum(payload.chatId, "in", cursor);
-                    }
-                }
-                catch (error) {
-                    logger.warn("chat.agent: session.in resume cursor lookup failed; old messages may replay", { error: error instanceof Error ? error.message : String(error) });
-                }
-            }
+            // Reads the turn boundary and subscribes in one call. `bootInCursor` is
+            // only a fallback: the boot block above may already have resolved a
+            // cursor from the snapshot, which is used when the boundary itself
+            // carries none.
+            await installChatInputRouter(payload.chatId, {
+                fallbackResumeFrom: bootInCursorResolved ? bootInCursor : undefined,
+                resuming: Boolean(payload.continuation) || ctx.attempt.number > 1,
+            });
             // ── Recovery boot + chain reconstruction ────────────────────────
             if (!hydrateMessages) {
                 const settledMessages = mergeByIdReplaceWins(bootSnapshot?.messages ?? [], replayedSettled);
@@ -3154,14 +3816,23 @@ function chatAgent(options) {
                             hookBeforeBoot = hookResult.beforeBoot;
                     }
                 }
-                // Default: splice partial + the user it was answering into
-                // the chain so follow-ups like "keep going" still have context.
+                // Default: splice partial + the user it was answering into the chain
+                // so follow-ups like "keep going" still have context, and re-dispatch
+                // the users that arrived after it.
+                //
+                // The splice needs a follow-up user to answer — it consumes
+                // `inFlightUsers[0]` into the chain instead of dispatching it. With
+                // exactly ONE in-flight user (the plain OOM / crash-mid-answer case)
+                // there is nothing left to dispatch, so splicing would strand that
+                // user unanswered and idle the run. Require `length > 1` on both
+                // branches: at n=1 the orphan partial is dropped and the interrupted
+                // user is re-dispatched as a fresh turn instead.
                 let seedChain;
                 let recoveredTurns;
                 if (hookChain !== undefined) {
                     seedChain = hookChain;
                 }
-                else if (partialAssistant !== undefined && inFlightUsers.length > 0) {
+                else if (partialAssistant !== undefined && inFlightUsers.length > 1) {
                     seedChain = [...settledMessages, inFlightUsers[0], partialAssistant];
                 }
                 else {
@@ -3170,7 +3841,7 @@ function chatAgent(options) {
                 if (hookRecoveredTurns !== undefined) {
                     recoveredTurns = hookRecoveredTurns;
                 }
-                else if (partialAssistant !== undefined && inFlightUsers.length > 0) {
+                else if (partialAssistant !== undefined && inFlightUsers.length > 1) {
                     recoveredTurns = inFlightUsers.slice(1);
                 }
                 else {
@@ -3723,11 +4394,18 @@ function chatAgent(options) {
                             const cancelSignal = runSignal;
                             const combinedSignal = AbortSignal.any([runSignal, stopController.signal]);
                             const pmConfig = 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) {
+                            /**
+                             * Only attached when there is a steering config to feed. Without
+                             * one a mid-turn message is left queued on the router, which is
+                             * what holds the resume floor behind it: a record handed to a
+                             * handler counts as terminally decided, so buffering one here
+                             * published a cursor past a message held only in memory and a
+                             * crash before the next turn lost it.
+                             */
+                            const msgSub = pmConfig
+                                ? chatInputRouter().observe(CHAT_ROUTE_MESSAGES, async (record) => {
+                                    const msg = record.data
+                                        .payload;
                                     // Slim wire: at most one delta message per record. The
                                     // pendingMessages handler reads `msg.message` directly
                                     // instead of slicing an array — a wire record arrives
@@ -3758,6 +4436,7 @@ function chatAgent(options) {
                                             queue.push({
                                                 uiMessage: lastUIMessage,
                                                 modelMessages: modelMsgs,
+                                                seqNum: record.seqNum,
                                             });
                                             locals.set(chatSteeringQueueKey, queue);
                                         }
@@ -3765,11 +4444,8 @@ function chatAgent(options) {
                                             /* 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
-                                pendingWireMessages.push(msg);
-                            });
+                                })
+                                : undefined;
                             turnMsgSub = msgSub;
                             // Track new messages for this turn (user input + assistant response).
                             const turnNewModelMessages = [];
@@ -4091,7 +4767,7 @@ function chatAgent(options) {
                             // The turn counter is decremented so the next iteration
                             // sees the same `turn` value — actions don't count.
                             if (isAction) {
-                                msgSub.off();
+                                msgSub?.off();
                                 if ((locals.get(chatPipeCountKey) ?? 0) === 0 &&
                                     isUIMessageStreamable(actionStreamResult)) {
                                     try {
@@ -4348,7 +5024,7 @@ function chatAgent(options) {
                                     }
                                 }
                                 finally {
-                                    msgSub.off();
+                                    msgSub?.off();
                                 }
                                 // Wait for onFinish to fire — on abort this may resolve slightly
                                 // after pipeChat, since the stream's cancel() handler is async.
@@ -4792,7 +5468,7 @@ function chatAgent(options) {
                                 if (!hydrateMessages) {
                                     try {
                                         await tracer.startActiveSpan("snapshot.write", async () => {
-                                            const snapshotInCursor = getChatSession().in.lastDispatchedSeqNum();
+                                            const snapshotInCursor = chatInputRouter().resumeFloor();
                                             await writeChatSnapshot(sessionIdForSnapshot, {
                                                 version: 1,
                                                 savedAt: Date.now(),
@@ -4831,13 +5507,6 @@ function chatAgent(options) {
                                 currentWirePayload = bootInjectedQueue.shift();
                                 return "continue";
                             }
-                            // If messages arrived during streaming (without pendingMessages config),
-                            // dispatch the oldest as the next turn. The rest stay queued
-                            // and drain one per turn.
-                            if (pendingWireMessages.length > 0) {
-                                currentWirePayload = pendingWireMessages.shift();
-                                return "continue";
-                            }
                             // chat.requestUpgrade() was called — exit the loop so the
                             // transport triggers a new run on the latest version.
                             // chat.endRun() — same exit, no upgrade semantics.
@@ -5071,7 +5740,7 @@ function chatAgent(options) {
                         // neither the snapshot nor the replayable `.in` tail.
                         if (!hydrateMessages) {
                             try {
-                                const errorSnapshotInCursor = getChatSession().in.lastDispatchedSeqNum();
+                                const errorSnapshotInCursor = chatInputRouter().resumeFloor();
                                 await writeChatSnapshot(sessionIdForSnapshot, {
                                     version: 1,
                                     savedAt: Date.now(),
@@ -5098,11 +5767,6 @@ function chatAgent(options) {
                             currentWirePayload = bootInjectedQueue.shift();
                             continue;
                         }
-                        // Same for messages buffered during the errored turn — already consumed, idling strands them.
-                        if (pendingWireMessages.length > 0) {
-                            currentWirePayload = pendingWireMessages.shift();
-                            continue;
-                        }
                         // Wait for the next message — same as after a successful turn
                         const effectiveIdleTimeout = metadata.get(IDLE_TIMEOUT_METADATA_KEY) ??
                             idleTimeoutInSeconds;
@@ -5162,6 +5826,8 @@ function createChatBuilder(config) {
             return createChatBuilder({
                 ...config,
                 clientDataSchema: cdConfig.schema,
+                clientDataReportErrorAt: cdConfig.reportErrorAt ?? config.clientDataReportErrorAt,
+                clientDataOnValidationError: cdConfig.onValidationError ?? config.clientDataOnValidationError,
             });
         },
         onBoot(fn) {
@@ -5242,6 +5908,10 @@ function createChatBuilder(config) {
             return chatCustomAgent({
                 ...options,
                 ...(config.clientDataSchema ? { clientDataSchema: config.clientDataSchema } : {}),
+                ...(config.clientDataReportErrorAt
+                    ? { clientDataReportErrorAt: config.clientDataReportErrorAt }
+                    : {}),
+                onClientDataValidationError: composeHooks(config.clientDataOnValidationError, options.onClientDataValidationError),
             });
         },
     };
@@ -5294,6 +5964,8 @@ function withUIMessage(config) {
 function withClientData(config) {
     return createChatBuilder({
         clientDataSchema: config.schema,
+        clientDataReportErrorAt: config.reportErrorAt,
+        clientDataOnValidationError: config.onValidationError,
         hooks: {},
     });
 }
@@ -5484,6 +6156,58 @@ function isStopped() {
 function requestUpgrade() {
     locals.set(chatUpgradeRequestedKey, true);
 }
+/**
+ * Hand off the current custom agent Session to a fresh run.
+ *
+ * This is the low-level handoff for a fully hand-rolled
+ * `chat.customAgent()` loop. This method rejects while a
+ * `chat.createSession()` iterator is active. Close the iterator before calling
+ * it. If `return()` races an active `next()`, it waits for that read to settle
+ * before releasing the handoff guard. Call only between turns and after
+ * detaching input listeners for the old run. If the old run completed its
+ * current turn, persist its state and call {@link chatWriteTurnComplete} before
+ * handing off.
+ * Do not write a new turn boundary after input that the continuation run should
+ * process has been dispatched: the boundary acknowledges that input.
+ *
+ * The server starts the continuation run but does not stop this run, so return
+ * from the task immediately after awaiting this function. The promise rejects
+ * if the server cannot complete the handoff.
+ *
+ * Pending Session input that the old run has not consumed remains on the
+ * durable `.in` stream and is delivered to the continuation run.
+ *
+ * @example
+ * ```ts
+ * // Detach any chat.messages.on() subscriptions you created.
+ * await persistMessages();
+ * await chat.writeTurnComplete();
+ * await chat.endAndContinue();
+ * return;
+ * ```
+ */
+async function endAndContinue() {
+    if (locals.get(chatCustomAgentRunKey) !== true) {
+        throw new Error("chat.endAndContinue() can only be called from inside a chat.customAgent() run");
+    }
+    if ((locals.get(chatActiveSessionIteratorsKey) ?? 0) > 0) {
+        throw new Error("chat.endAndContinue() cannot be called while a chat.createSession() iterator is active. Close the iterator, then call chat.endAndContinue().");
+    }
+    await performEndAndContinue();
+}
+/** @internal Shared server handoff used by managed and custom agent loops. */
+async function performEndAndContinue() {
+    const chatId = locals.get(chatExternalIdKey);
+    const callingRunId = locals.get(chatAgentRunContextKey)?.run.id;
+    if (!chatId || !callingRunId) {
+        throw new Error("Cannot end and continue without an active chat agent run");
+    }
+    const apiClient = apiClientManager.clientOrThrow();
+    await apiClient.endAndContinueSession(chatId, {
+        callingRunId,
+        reason: "upgrade",
+    });
+}
 /**
  * Exit the run after the current turn completes, without waiting for the
  * next message. Unlike {@link requestUpgrade}, no upgrade-required signal
@@ -5689,10 +6413,14 @@ function createStopSignal() {
  * task instead of round-tripping them back from the client:
  * - `lastEventId` — the turn-complete control record's seq_num on
  *   `session.out`; where the next turn's output stream resumes.
- * - `sessionInEventId` — the committed-consume cursor on `session.in` as of
- *   this turn-complete, letting a raw loop correlate the boundary with the
- *   exact input record it acknowledged. Trigger owns input-cursor recovery,
- *   so this is for correlation / out-of-sync detection, not required.
+ * - `sessionInEventId` — the safe-to-resume-from cursor on `session.in` as of
+ *   this turn-complete. It is the highest sequence that can be resumed past
+ *   without skipping an unhandled message, so it is held back behind any
+ *   message still buffered unconsumed and is NOT necessarily the sequence of
+ *   the record this turn answered. Trigger owns input-cursor recovery, so this
+ *   is for correlation / out-of-sync detection, not required. Treat it as a
+ *   lower bound: a value below the record you just handled is expected, not a
+ *   sign of a lost turn.
  *
  * Either is `undefined` when the corresponding cursor isn't available.
  *
@@ -5704,15 +6432,36 @@ function createStopSignal() {
  * ```
  */
 async function chatWriteTurnComplete(options) {
+    await flushDeferredChatCustomAgentClientDataErrors();
     const result = await writeTurnCompleteChunk(undefined, options?.publicAccessToken);
     // Same cursor written to the `session-in-event-id` header inside
     // `writeTurnCompleteChunk`; surfaced here so the caller can persist it.
-    const inCursor = getChatSession().in.lastDispatchedSeqNum();
+    const inCursor = chatInputRouter().resumeFloor();
     return {
         lastEventId: result?.lastEventId,
         ...(inCursor !== undefined ? { sessionInEventId: String(inCursor) } : {}),
     };
 }
+/**
+ * Writes the client-data errors held back by the default `"turn-end"` timing.
+ *
+ * Ordered before the turn-complete chunk, matching the error-then-turn-complete
+ * shape the submitted-turn and async-read paths already write.
+ */
+async function flushDeferredChatCustomAgentClientDataErrors() {
+    const deferred = locals.get(chatCustomAgentDeferredClientDataErrorsKey);
+    if (!deferred || deferred.length === 0)
+        return;
+    locals.set(chatCustomAgentDeferredClientDataErrorsKey, []);
+    for (const payload of deferred) {
+        try {
+            await writeChatCustomAgentClientDataErrorToStream(payload);
+        }
+        catch {
+            /* non-fatal */
+        }
+    }
+}
 /**
  * Pass every chunk through untouched while recording it in `buffer`. Handles
  * both the `AsyncIterable` and `ReadableStream` shapes `toUIMessageStream()`
@@ -6099,6 +6848,95 @@ class ChatMessageAccumulator {
         return true;
     }
 }
+function trackActiveChatSessionIterator(iterator) {
+    locals.set(chatActiveSessionIteratorsKey, (locals.get(chatActiveSessionIteratorsKey) ?? 0) + 1);
+    let active = true;
+    let closing = false;
+    let activeNextCalls = 0;
+    let closePromise;
+    const nextSettledWaiters = new Set();
+    function finish() {
+        if (!active)
+            return;
+        active = false;
+        const remaining = Math.max((locals.get(chatActiveSessionIteratorsKey) ?? 1) - 1, 0);
+        locals.set(chatActiveSessionIteratorsKey, remaining);
+    }
+    function settleNextCall() {
+        activeNextCalls = Math.max(activeNextCalls - 1, 0);
+        if (activeNextCalls > 0)
+            return;
+        for (const resolve of nextSettledWaiters) {
+            resolve();
+        }
+        nextSettledWaiters.clear();
+    }
+    function waitForNextCalls() {
+        if (activeNextCalls === 0)
+            return Promise.resolve();
+        return new Promise((resolve) => nextSettledWaiters.add(resolve));
+    }
+    function closeIterator() {
+        closing = true;
+        if (!closePromise) {
+            closePromise = (async () => {
+                // A blocked next() can install a new message listener after it resumes.
+                // Let every started call settle, then make the inner cleanup final.
+                await waitForNextCalls();
+                try {
+                    return iterator.return
+                        ? await iterator.return()
+                        : { done: true, value: undefined };
+                }
+                finally {
+                    finish();
+                }
+            })();
+        }
+        return closePromise;
+    }
+    return {
+        async next() {
+            if (closing) {
+                return { done: true, value: undefined };
+            }
+            activeNextCalls++;
+            let result;
+            try {
+                result = await iterator.next();
+            }
+            catch (error) {
+                settleNextCall();
+                try {
+                    await closeIterator();
+                }
+                catch {
+                    // Preserve the original iterator error after best-effort cleanup.
+                }
+                throw error;
+            }
+            settleNextCall();
+            if (result.done) {
+                try {
+                    await closeIterator();
+                }
+                catch {
+                    // The inner next() already ended cleanly; cleanup remains best-effort.
+                }
+            }
+            else if (closing) {
+                // return() won the race. Do not expose a turn the caller has already
+                // abandoned; without a new turn-complete boundary its input remains
+                // replayable by the continuation run.
+                return { done: true, value: undefined };
+            }
+            return result;
+        },
+        return() {
+            return closeIterator();
+        },
+    };
+}
 /**
  * Create a chat session that yields turns as an async iterator.
  *
@@ -6150,20 +6988,18 @@ function createChatSession(payload, options) {
             const accumulator = new ChatMessageAccumulator();
             let previousTurnUsage;
             let cumulativeUsage = emptyUsage();
-            // Messages consumed mid-turn, dispatched one per next(). Iterator-level
-            // for the same reason as the agent loop's `pendingWireMessages`:
-            // consumed records never replay, so a turn-local buffer loses them.
-            const sessionPendingWire = [];
             // The current turn's message subscription — detached defensively at the
             // top of next() in case user code threw without complete()/done().
             let activeMsgSub;
-            return {
+            const iterator = {
                 async next() {
                     activeMsgSub?.off();
                     activeMsgSub = undefined;
                     if (!booted) {
                         booted = true;
-                        await seedSessionInResumeCursorForCustomLoop(currentPayload);
+                        await installChatInputRouter(currentPayload.chatId, {
+                            resuming: Boolean(currentPayload.continuation),
+                        });
                         stop = createStopSignal();
                     }
                     turn++;
@@ -6220,29 +7056,32 @@ function createChatSession(payload, options) {
                             currentPayload = { ...currentPayload, continuation: true };
                         }
                     }
-                    // Subsequent turns: drain buffered mid-turn messages first (they
-                    // were consumed and won't be re-delivered), then wait.
+                    /**
+                     * Subsequent turns take the next message from the router. A record
+                     * that arrived mid-turn is already queued there, so this returns it
+                     * without suspending.
+                     */
                     if (turn > 0) {
-                        if (sessionPendingWire.length > 0) {
-                            currentPayload = sessionPendingWire.shift();
+                        // chat.requestUpgrade() / chat.endRun() — exit before waiting
+                        if (locals.get(chatUpgradeRequestedKey) || locals.get(chatEndRunRequestedKey)) {
+                            stop.cleanup();
+                            return { done: true, value: undefined };
                         }
-                        else {
-                            // chat.requestUpgrade() / chat.endRun() — exit before waiting
-                            if (locals.get(chatUpgradeRequestedKey) || locals.get(chatEndRunRequestedKey)) {
-                                stop.cleanup();
-                                return { done: true, value: undefined };
-                            }
-                            const next = await messagesInput.waitWithIdleTimeout({
-                                idleTimeoutInSeconds,
-                                timeout,
-                                spanName: "waiting for next message",
-                            });
-                            if (!next.ok || runSignal.aborted) {
-                                stop.cleanup();
-                                return { done: true, value: undefined };
-                            }
-                            currentPayload = next.output;
+                        const next = await messagesInput.waitWithIdleTimeout({
+                            idleTimeoutInSeconds,
+                            timeout,
+                            spanName: "waiting for next message",
+                        });
+                        if (!next.ok || runSignal.aborted) {
+                            stop.cleanup();
+                            return { done: true, value: undefined };
                         }
+                        /**
+                         * The facade validated `clientData` against the configured schema
+                         * before returning, so the parsed shape is what arrives here. The
+                         * cast carries that across the untyped wire payload boundary.
+                         */
+                        currentPayload = next.output;
                     }
                     // Check limits
                     if (turn >= maxTurns || runSignal.aborted) {
@@ -6266,39 +7105,49 @@ function createChatSession(payload, options) {
                         continuation: currentPayload.continuation ?? false,
                         clientData: currentPayload.metadata,
                     });
-                    // Listen for messages during streaming (steering + next-turn buffer)
-                    const sessionMsgSub = messagesInput.on(async (msg) => {
-                        if (sessionPendingMessages) {
-                            // Steering route — the frontend re-sends non-injected
-                            // messages on turn complete, so don't also buffer the wire.
-                            // Slim wire: at most one delta message per record. Read
-                            // `msg.message` directly — no array slicing needed.
-                            const lastUIMessage = msg.message;
-                            if (lastUIMessage) {
-                                if (sessionPendingMessages.onReceived) {
-                                    try {
-                                        await sessionPendingMessages.onReceived({
-                                            message: lastUIMessage,
-                                            chatId: currentPayload.chatId,
-                                            turn,
-                                        });
-                                    }
-                                    catch {
-                                        /* non-fatal */
-                                    }
-                                }
+                    /**
+                     * Only attached when there is a steering config to feed. Without one a
+                     * mid-turn message stays queued on the router, which is what keeps the
+                     * resume floor behind it.
+                     */
+                    const handleSteeringMessage = async (msg, seqNum, isActive = () => true) => {
+                        const lastUIMessage = msg.message;
+                        if (lastUIMessage) {
+                            if (sessionPendingMessages?.onReceived) {
                                 try {
-                                    const modelMsgs = await toModelMessages([lastUIMessage]);
-                                    turnSteeringQueue.push({ uiMessage: lastUIMessage, modelMessages: modelMsgs });
+                                    await sessionPendingMessages.onReceived({
+                                        message: lastUIMessage,
+                                        chatId: currentPayload.chatId,
+                                        turn,
+                                    });
                                 }
                                 catch {
                                     /* non-fatal */
                                 }
                             }
-                            return;
+                            if (!isActive())
+                                return;
+                            try {
+                                const modelMsgs = await toModelMessages([lastUIMessage]);
+                                turnSteeringQueue.push({
+                                    uiMessage: lastUIMessage,
+                                    modelMessages: modelMsgs,
+                                    seqNum,
+                                });
+                            }
+                            catch {
+                                /* non-fatal */
+                            }
                         }
-                        sessionPendingWire.push(msg);
-                    });
+                    };
+                    const sessionMsgSub = sessionPendingMessages
+                        ? locals.get(chatCustomAgentClientDataParserKey)
+                            ? observeValidatedChatMessages((msg, seqNum, isActive) => handleSteeringMessage(msg, seqNum, isActive))
+                            : chatInputRouter().observe(CHAT_ROUTE_MESSAGES, (record) => {
+                                const msg = record.data.payload;
+                                void handleSteeringMessage(msg, record.seqNum);
+                            })
+                        : undefined;
                     activeMsgSub = sessionMsgSub;
                     // Accumulate messages. Slim wire: pass the single delta message as
                     // a 0-or-1-length array. The accumulator's behavior is unchanged —
@@ -6320,7 +7169,7 @@ function createChatSession(payload, options) {
                     // chat.requestUpgrade() called before this turn — signal transport and exit
                     if (locals.get(chatUpgradeRequestedKey)) {
                         await writeUpgradeRequiredChunk();
-                        sessionMsgSub.off();
+                        sessionMsgSub?.off();
                         stop.cleanup();
                         return { done: true, value: undefined };
                     }
@@ -6360,7 +7209,7 @@ function createChatSession(payload, options) {
                                 if (!response || response.role !== "assistant") {
                                     throw new Error("turn.complete() could not find the spliced handover response");
                                 }
-                                sessionMsgSub.off();
+                                sessionMsgSub?.off();
                                 await chatWriteTurnComplete();
                                 return response;
                             }
@@ -6377,7 +7226,7 @@ function createChatSession(payload, options) {
                                 });
                                 if (runSignal.aborted) {
                                     // Full cancel — don't accumulate
-                                    sessionMsgSub.off();
+                                    sessionMsgSub?.off();
                                     await chatWriteTurnComplete();
                                     return undefined;
                                 }
@@ -6400,7 +7249,7 @@ function createChatSession(payload, options) {
                             finally {
                                 // Detach at stream end (like the agent loop): the steering queue
                                 // can't inject anymore, so later arrivals must buffer for the next turn.
-                                sessionMsgSub.off();
+                                sessionMsgSub?.off();
                             }
                             if (response) {
                                 const cleaned = stop.signal.aborted && !runSignal.aborted
@@ -6496,7 +7345,7 @@ function createChatSession(payload, options) {
                                     }
                                 }
                             }
-                            sessionMsgSub.off();
+                            sessionMsgSub?.off();
                             await chatWriteTurnComplete();
                             return response;
                         },
@@ -6513,7 +7362,7 @@ function createChatSession(payload, options) {
                             await accumulator.addResponse(response);
                         },
                         async done() {
-                            sessionMsgSub.off();
+                            sessionMsgSub?.off();
                             await chatWriteTurnComplete();
                         },
                         prepareStep() {
@@ -6552,6 +7401,7 @@ function createChatSession(payload, options) {
                     return { done: true, value: undefined };
                 },
             };
+            return trackActiveChatSessionIterator(iterator);
         },
     };
 }
@@ -7000,6 +7850,8 @@ export const chat = {
     isStopped,
     /** Request that the run exits after the current turn so the next message starts on the latest version. See {@link requestUpgrade}. */
     requestUpgrade,
+    /** Hand off a custom agent Session to a fresh run. See {@link endAndContinue}. */
+    endAndContinue,
     /** Exit the run after the current turn completes, without any upgrade signal. See {@link endRun}. */
     endRun,
     /** Clean up aborted parts from a UIMessage. See {@link cleanupAbortedParts}. */
@@ -7107,6 +7959,16 @@ export const chat = {
  */
 async function writeTurnCompleteChunk(_chatId, publicAccessToken) {
     const session = getChatSession();
+    // A handover-prepare boot claims the handover kinds so a signal arriving
+    // before `waitForHandover` attaches is not drained. Released here rather than
+    // only in `waitForHandover`, because a loop that never calls it would
+    // otherwise hold the claim for the life of the run and leave a handover
+    // record parked at the head of the channel, where it wedges
+    // `chat.messages.next()`. Every surface reaches a turn boundary through this
+    // function, including the managed agent, which does not call the public
+    // `chat.writeTurnComplete`. By the time a turn completes the handover window
+    // is over either way.
+    chatInputRouter().clearRoute(CHAT_ROUTE_HANDOVER);
     // 1. Write the turn-complete control record. The ack's `lastEventId` is
     //    this record's seq_num — that's the trim target for the NEXT turn.
     //
@@ -7121,10 +7983,15 @@ async function writeTurnCompleteChunk(_chatId, publicAccessToken) {
     if (publicAccessToken) {
         extraHeaders.push(["public-access-token", publicAccessToken]);
     }
-    const inCursor = session.in.lastDispatchedSeqNum();
+    const routerCheckpoint = chatInputRouter().checkpoint();
+    const inCursor = routerCheckpoint.resumeFrom;
     if (inCursor !== undefined) {
         extraHeaders.push([SESSION_IN_EVENT_ID_HEADER, String(inCursor)]);
     }
+    const consumedCursor = routerCheckpoint.appliedThrough;
+    if (consumedCursor !== undefined) {
+        extraHeaders.push([SESSION_IN_CONSUMED_ID_HEADER, String(consumedCursor)]);
+    }
     const result = await session.out.writeControl(TRIGGER_CONTROL_SUBTYPE.TURN_COMPLETE, extraHeaders);
     const T_N = result.lastEventId ? Number.parseInt(result.lastEventId, 10) : undefined;
     // 2. Trim back to the previous turn-complete, if we have one. Skipping on
@@ -7183,16 +8050,11 @@ async function writeTurnCompleteChunk(_chatId, publicAccessToken) {
  * @internal
  */
 async function writeUpgradeRequiredChunk() {
-    const ctx = taskContext.ctx;
-    const chatId = ctx?.run.id ? getChatIdFromContext() : undefined;
-    const callingRunId = ctx?.run.id;
+    const chatId = locals.get(chatExternalIdKey);
+    const callingRunId = locals.get(chatAgentRunContextKey)?.run.id;
     if (chatId && callingRunId) {
-        const apiClient = apiClientManager.clientOrThrow();
         try {
-            await apiClient.endAndContinueSession(chatId, {
-                callingRunId,
-                reason: "upgrade",
-            });
+            await performEndAndContinue();
         }
         catch (error) {
             // Non-fatal: the next `.in/append` re-triggers via the probe.
@@ -7207,16 +8069,6 @@ async function writeUpgradeRequiredChunk() {
     const session = getChatSession();
     return session.out.writeControl(TRIGGER_CONTROL_SUBTYPE.UPGRADE_REQUIRED);
 }
-/**
- * Resolves the current chat's `chatId` (used as session externalId) from
- * the bound session handle. Returns `undefined` if no agent is bound —
- * shouldn't happen at the call sites that invoke
- * `writeUpgradeRequiredChunk`, but defensive against misuse.
- * @internal
- */
-function getChatIdFromContext() {
-    return locals.get(chatSessionHandleKey)?.id;
-}
 /**
  * Extracts the text content of the last user message from a UIMessage array.
  * Returns undefined if no user message is found.