@trigger.dev/sdk 0.0.0-prerelease-20260827143549 → 0.0.0-prerelease-20260828141059

package/dist/commonjs/v3/ai.js

@@ -984,6 +984,132 @@ async function withChatWriter(fn) {
     await flush();
     return result;
 }
+const CHAT_CUSTOM_AGENT_CLIENT_DATA_ERROR_TEXT = "Invalid client data";
+const chatCustomAgentClientDataParserKey = locals_js_1.locals.create("chat.customAgentClientDataParser");
+const chatCustomAgentClientDataErrorHandlerKey = locals_js_1.locals.create("chat.customAgentClientDataErrorHandler");
+function shouldValidateChatCustomAgentPayload(payload) {
+    return (payload.trigger !== "close" && locals_js_1.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) {
+        v3_1.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";
+    v3_1.logger.warn("chat.customAgent: clientData validation failed", {
+        chatId: payload.chatId,
+        trigger: payload.trigger,
+        error: errorText,
+    });
+    const errorHandler = options.callHandler === false
+        ? undefined
+        : locals_js_1.locals.get(chatCustomAgentClientDataErrorHandlerKey);
+    if (errorHandler) {
+        try {
+            await errorHandler({ error, payload });
+        }
+        catch (handlerError) {
+            v3_1.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_js_1.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_js_1.locals.get(chatCustomAgentClientDataParserKey);
+    if (!parser || payload.trigger === "close") {
+        return payload;
+    }
+    try {
+        return { ...payload, metadata: parser.parseSync(payload.metadata) };
+    }
+    catch (error) {
+        v3_1.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.
  *
@@ -1002,14 +1128,14 @@ async function waitOnChatRoute(route, options) {
             const warm = await router.next(route, { timeoutMs: idleMs });
             if (warm) {
                 span.setAttribute("wait.resolved", "idle");
-                return { ok: true, output: warm.data };
+                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 };
+                return { ok: true, output: buffered.data, record: buffered };
             }
         }
         if (options.skipSuspend) {
@@ -1045,7 +1171,7 @@ async function waitOnChatRoute(route, options) {
                 continue;
             if (options.onResume)
                 await options.onResume();
-            return { ok: true, output: record.data };
+            return { ok: true, output: record.data, record };
         }
     }, {
         attributes: {
@@ -1060,36 +1186,236 @@ async function waitOnChatRoute(route, options) {
         },
     });
 }
+/**
+ * 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_js_1.locals.get(chatObserverClaimedSeqNumsKey) ??
+        new Map();
+    locals_js_1.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_js_1.locals.get(chatCustomAgentClientDataErrorTimingKey) ?? "turn-end";
+                const writeNow = timing === "arrival" || !active;
+                await reportChatCustomAgentClientDataError(payload, result.error, {
+                    writeToStream: writeNow,
+                });
+                if (!writeNow) {
+                    const deferred = locals_js_1.locals.get(chatCustomAgentDeferredClientDataErrorsKey) ?? [];
+                    deferred.push(payload);
+                    locals_js_1.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_js_1.locals.get(chatObserverClaimedSeqNumsKey)?.get(record.seqNum)?.released;
+}
 const messagesInput = {
     id: "chat-messages",
     on(handler) {
-        return chatInputRouter().on(CHAT_ROUTE_MESSAGES, (record) => {
-            const chunk = record.data;
-            void Promise.resolve(handler(chunk.payload)).catch(() => { });
-        });
+        if (!locals_js_1.locals.get(chatCustomAgentClientDataParserKey)) {
+            return subscribeToRawChatMessages(handler);
+        }
+        const deliver = (payload) => handler(payload);
+        return subscribeToValidatedChatMessages(deliver, { onAfterOff: deliver });
     },
     once(options) {
         return new v3_1.InputStreamOncePromise((resolve, reject) => {
-            chatInputRouter()
-                .next(CHAT_ROUTE_MESSAGES, { timeoutMs: options?.timeoutMs })
-                .then((record) => {
-                if (!record) {
-                    resolve({
-                        ok: false,
-                        error: new v3_1.InputStreamTimeoutError("chat-messages", options?.timeoutMs ?? 0),
-                    });
-                    return;
-                }
-                const chunk = record.data;
-                resolve({ ok: true, output: chunk.payload });
-            }, reject);
+            /**
+             * 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 v3_1.InputStreamTimeoutError("chat-messages", options?.timeoutMs ?? 0),
+                        });
+                        return;
+                    }
+                    const claim = observerClaimFor(record);
+                    if (claim) {
+                        chatInputRouter().untake(CHAT_ROUTE_MESSAGES, record);
+                        await claim;
+                        take();
+                        return;
+                    }
+                    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 record = chatInputRouter().peek(CHAT_ROUTE_MESSAGES);
         if (!record)
             return undefined;
-        return record.data.payload;
+        const payload = record.data.payload;
+        return validateChatCustomAgentPayloadSync(payload);
     },
     async hasPending() {
         return chatInputRouter().hasPending(CHAT_ROUTE_MESSAGES);
@@ -1100,21 +1426,67 @@ const messagesInput = {
             (!Number.isFinite(timeoutInSeconds) || timeoutInSeconds < 0)) {
             throw new TypeError("chat.messages.next() timeoutInSeconds must be a finite non-negative number");
         }
-        const record = await chatInputRouter().next(CHAT_ROUTE_MESSAGES, {
-            timeoutMs: timeoutInSeconds === undefined ? undefined : timeoutInSeconds * 1000,
-        });
-        if (!record)
-            return undefined;
-        const chunk = record.data;
-        return { id: record.id, seqNum: record.seqNum, payload: chunk.payload };
+        // 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 v3_1.ManualWaitpointPromise(async (resolve, reject) => {
             try {
-                const result = await waitOnChatRoute(CHAT_ROUTE_MESSAGES, { timeout: options?.timeout, spanName: options?.spanName });
-                resolve(result.ok
-                    ? { ok: true, output: result.output.payload }
-                    : { ok: false, error: result.error ?? new Error("Timed out") });
+                // Same skip-and-wait rule as `waitWithIdleTimeout`, looping back into
+                // the suspending wait rather than surfacing an unvalidated payload.
+                while (true) {
+                    const result = await waitOnChatRoute(CHAT_ROUTE_MESSAGES, { timeout: options?.timeout, spanName: options?.spanName });
+                    if (!result.ok) {
+                        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;
+                    }
+                    const validated = await validateChatCustomAgentPayload(payload);
+                    if (validated.ok) {
+                        resolve({ ok: true, output: validated.payload });
+                        return;
+                    }
+                }
             }
             catch (error) {
                 reject(error);
@@ -1122,10 +1494,31 @@ const messagesInput = {
         });
     },
     async waitWithIdleTimeout(options) {
-        const result = await waitOnChatRoute(CHAT_ROUTE_MESSAGES, options);
-        return result.ok
-            ? { ok: true, output: result.output.payload }
-            : { ok: false, error: result.error };
+        /**
+         * 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 waitOnChatRoute(CHAT_ROUTE_MESSAGES, options);
+            if (!result.ok)
+                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 };
+            }
+        }
     },
     async send(_runId, data, options) {
         await getChatSession().in.send({ kind: "message", payload: data }, options?.requestOptions);
@@ -2029,6 +2422,30 @@ const chatCompactionStateKey = locals_js_1.locals.create("chat.compaction");
 const chatOnCompactedKey = locals_js_1.locals.create("chat.onCompacted");
 /** @internal Full task `ctx` for the active `chat.agent` run (for hooks invoked from nested compaction). */
 const chatAgentRunContextKey = locals_js_1.locals.create("chat.agentRunContext");
+/** @internal When a mid-turn validation failure writes its terminal error. */
+const chatCustomAgentClientDataErrorTimingKey = locals_js_1.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_js_1.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_js_1.locals.create("chat.customAgent.observerClaims");
+/** @internal Marks the root run created by `chat.customAgent()`. */
+const chatCustomAgentRunKey = locals_js_1.locals.create("chat.customAgentRun");
+/** @internal Number of active `chat.createSession()` iterators in this run. */
+const chatActiveSessionIteratorsKey = locals_js_1.locals.create("chat.createSession.activeIterators");
 const chatPrepareMessagesKey = locals_js_1.locals.create("chat.prepareMessages");
 /**
  * @internal The raw `tools` option from `chat.agent({ tools })`, either a
@@ -2984,7 +3401,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 ? (0, v3_1.getSchemaParseFn)(clientDataSchema) : undefined;
+    const parseClientDataSync = clientDataSchema
+        ? getChatCustomAgentSyncSchemaParseFn(clientDataSchema)
+        : undefined;
     const task = (0, shared_js_1.createTask)({
         ...restOptions,
         triggerSource: "agent",
@@ -3003,6 +3424,17 @@ function chatCustomAgent(options) {
             locals_js_1.locals.set(chatSessionHandleKey, sessions_js_1.sessions.open(payload.chatId));
             locals_js_1.locals.set(chatExternalIdKey, payload.chatId);
             locals_js_1.locals.set(chatAgentRunContextKey, runOptions.ctx);
+            locals_js_1.locals.set(chatCustomAgentRunKey, true);
+            if (parseClientData && parseClientDataSync) {
+                locals_js_1.locals.set(chatCustomAgentClientDataParserKey, {
+                    parse: parseClientData,
+                    parseSync: parseClientDataSync,
+                });
+            }
+            if (onClientDataValidationError) {
+                locals_js_1.locals.set(chatCustomAgentClientDataErrorHandlerKey, onClientDataValidationError);
+            }
+            locals_js_1.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`
@@ -3014,7 +3446,62 @@ function chatCustomAgent(options) {
             await installChatInputRouter(payload.chatId, {
                 resuming: Boolean(payload.continuation),
             });
-            return userRun(payload, runOptions);
+            // 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
@@ -3044,6 +3531,7 @@ function chatAgent(options) {
         agentConfig: { type: "ai-sdk-chat" },
         run: async (payload, { signal: runSignal, ctx }) => {
             locals_js_1.locals.set(chatAgentRunContextKey, ctx);
+            locals_js_1.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
@@ -3336,14 +3824,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 {
@@ -3352,7 +3849,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 {
@@ -5337,6 +5834,8 @@ function createChatBuilder(config) {
             return createChatBuilder({
                 ...config,
                 clientDataSchema: cdConfig.schema,
+                clientDataReportErrorAt: cdConfig.reportErrorAt ?? config.clientDataReportErrorAt,
+                clientDataOnValidationError: cdConfig.onValidationError ?? config.clientDataOnValidationError,
             });
         },
         onBoot(fn) {
@@ -5417,6 +5916,10 @@ function createChatBuilder(config) {
             return chatCustomAgent({
                 ...options,
                 ...(config.clientDataSchema ? { clientDataSchema: config.clientDataSchema } : {}),
+                ...(config.clientDataReportErrorAt
+                    ? { clientDataReportErrorAt: config.clientDataReportErrorAt }
+                    : {}),
+                onClientDataValidationError: composeHooks(config.clientDataOnValidationError, options.onClientDataValidationError),
             });
         },
     };
@@ -5469,6 +5972,8 @@ function withUIMessage(config) {
 function withClientData(config) {
     return createChatBuilder({
         clientDataSchema: config.schema,
+        clientDataReportErrorAt: config.reportErrorAt,
+        clientDataOnValidationError: config.onValidationError,
         hooks: {},
     });
 }
@@ -5659,6 +6164,58 @@ function isStopped() {
 function requestUpgrade() {
     locals_js_1.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_js_1.locals.get(chatCustomAgentRunKey) !== true) {
+        throw new Error("chat.endAndContinue() can only be called from inside a chat.customAgent() run");
+    }
+    if ((locals_js_1.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_js_1.locals.get(chatExternalIdKey);
+    const callingRunId = locals_js_1.locals.get(chatAgentRunContextKey)?.run.id;
+    if (!chatId || !callingRunId) {
+        throw new Error("Cannot end and continue without an active chat agent run");
+    }
+    const apiClient = v3_1.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
@@ -5883,6 +6440,7 @@ 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.
@@ -5892,6 +6450,26 @@ async function chatWriteTurnComplete(options) {
         ...(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_js_1.locals.get(chatCustomAgentDeferredClientDataErrorsKey);
+    if (!deferred || deferred.length === 0)
+        return;
+    locals_js_1.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()`
@@ -6278,6 +6856,95 @@ class ChatMessageAccumulator {
         return true;
     }
 }
+function trackActiveChatSessionIterator(iterator) {
+    locals_js_1.locals.set(chatActiveSessionIteratorsKey, (locals_js_1.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_js_1.locals.get(chatActiveSessionIteratorsKey) ?? 1) - 1, 0);
+        locals_js_1.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.
  *
@@ -6332,7 +6999,7 @@ function createChatSession(payload, options) {
             // 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;
@@ -6417,6 +7084,11 @@ function createChatSession(payload, options) {
                             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
@@ -6446,36 +7118,43 @@ function createChatSession(payload, options) {
                      * mid-turn message stays queued on the router, which is what keeps the
                      * resume floor behind it.
                      */
-                    const sessionMsgSub = sessionPendingMessages
-                        ? chatInputRouter().observe(CHAT_ROUTE_MESSAGES, async (record) => {
-                            const msg = record.data.payload;
-                            const lastUIMessage = msg.message;
-                            if (lastUIMessage) {
-                                if (sessionPendingMessages.onReceived) {
-                                    try {
-                                        await sessionPendingMessages.onReceived({
-                                            message: lastUIMessage,
-                                            chatId: currentPayload.chatId,
-                                            turn,
-                                        });
-                                    }
-                                    catch {
-                                        /* non-fatal */
-                                    }
-                                }
+                    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,
-                                        seqNum: record.seqNum,
+                                    await sessionPendingMessages.onReceived({
+                                        message: lastUIMessage,
+                                        chatId: currentPayload.chatId,
+                                        turn,
                                     });
                                 }
                                 catch {
                                     /* non-fatal */
                                 }
                             }
-                        })
+                            if (!isActive())
+                                return;
+                            try {
+                                const modelMsgs = await toModelMessages([lastUIMessage]);
+                                turnSteeringQueue.push({
+                                    uiMessage: lastUIMessage,
+                                    modelMessages: modelMsgs,
+                                    seqNum,
+                                });
+                            }
+                            catch {
+                                /* non-fatal */
+                            }
+                        }
+                    };
+                    const sessionMsgSub = sessionPendingMessages
+                        ? locals_js_1.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
@@ -6730,6 +7409,7 @@ function createChatSession(payload, options) {
                     return { done: true, value: undefined };
                 },
             };
+            return trackActiveChatSessionIterator(iterator);
         },
     };
 }
@@ -7178,6 +7858,8 @@ exports.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}. */
@@ -7376,16 +8058,11 @@ async function writeTurnCompleteChunk(_chatId, publicAccessToken) {
  * @internal
  */
 async function writeUpgradeRequiredChunk() {
-    const ctx = v3_1.taskContext.ctx;
-    const chatId = ctx?.run.id ? getChatIdFromContext() : undefined;
-    const callingRunId = ctx?.run.id;
+    const chatId = locals_js_1.locals.get(chatExternalIdKey);
+    const callingRunId = locals_js_1.locals.get(chatAgentRunContextKey)?.run.id;
     if (chatId && callingRunId) {
-        const apiClient = v3_1.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.
@@ -7400,16 +8077,6 @@ async function writeUpgradeRequiredChunk() {
     const session = getChatSession();
     return session.out.writeControl(v3_1.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_js_1.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.