/** * Text Activity * * Handles agentic text generation, one-shot text generation, and agentic structured output. * This is a self-contained module with implementation, types, and JSDoc. */ import { devtoolsMiddleware } from '@tanstack/ai-event-client' import { undoNullWidening } from '@tanstack/ai-utils' import { streamToText } from '../../stream-to-response.js' import { normalizeReasoning } from '../../reasoning' import { resolveDebugOption } from '../../logger/resolve' import { EventType } from '../../types' import { INTERRUPT_BINDING_METADATA_KEY, InterruptResumeValidationError, readInterruptBinding, readUnopenedInterruptBinding, validateInterruptResumeBatch, } from '../../interrupt-resume' import { INTERRUPT_BINDING_VERSION } from '../../interrupts' import { INTERRUPT_PAYLOAD_METADATA_KEY, createInterruptBinding, rehydrateInterruptRequest, } from '../../interrupt-definition' import { readGenericInterruptContinuation } from '../../generic-interrupt-continuation' import type { GenericInterruptRequest, InterruptDefinition, } from '../../interrupt-definition' import { canonicalInterruptJson, digestInterruptJson, } from '../../interrupt-serialization' import { readErrorUsage, rebuildTokenUsage } from '../../utilities/ag-ui-usage' import { uiMessagesToWire } from '../../utilities/ag-ui-wire' import { tanstackMetadata, withTanstackMetadata, } from '../../utilities/merge-metadata' import { subagentHostMessageId } from '../../utilities/subagent-wire' import { withDurabilityBatchHint } from '../../utilities/durability-batch' import { normalizeStreamChunk } from '../../utilities/normalize-stream-chunk' import { isRedactedThinkingId } from '../../utilities/reasoning-encrypted-value' import { restorePublicUsage } from '../../utilities/restore-inbound-chunk' import type { AdapterYieldChunk } from '../../utilities/adapter-yield-chunk' import type { ChatResult } from '../../stream-to-response.js' import { normalizeToolResult, parseToolOutput, textToolResultMark, toolResultErrorText, } from '../../utilities/tool-result' import { isProviderExecutedToolCall } from '../../utilities/provider-executed' import { buildBlockOrder } from '../../utilities/block-order' import type { BlockOrderEntry } from '../../utilities/block-order' import { assertMessagesFileSourceSupport } from '../../utilities/content-source' import { sanitizeProviderRequest } from '../../utilities/sanitize-unicode' import { planMidConversationChanges } from '../../utilities/mid-conversation' import { normalizeSystemPrompts } from '../../system-prompts' import { transformMessagesForReplay } from '../../utilities/replay-messages' import { LazyToolManager } from './tools/lazy-tool-manager' import { assertUniqueToolNames } from './tools/unique-tool-names' import type { DefinedAgent } from './agents/define-agent' import { providerKeys } from '../../byok/env-keys' import { assertNoReservedFields, collectNamedText, createSubagentSink, createSyntheticSubagentTools, normalizeRouterPick, rebindInterrupts, spawnNamedAgents, stepInput, subagentCallMessages, withChildUsage, } from './agents/spawn' import type { RoutedPlan, SpawnEntry, SubagentSink, SubagentsBag, } from './agents/spawn' import { SUBAGENT_PLAN_KEY, readSubagentTurn } from './agents/turn' import { MiddlewareAbortError, ToolCallManager, approvalResolution, executeToolCalls, } from './tools/tool-calls' import { convertSchemaForStructuredOutput, convertSchemaToJsonSchema, isStandardSchema, parseWithStandardSchema, validateWithStandardSchema, } from './tools/schema-converter' import { hashSchemaInput, normalizeApprovalSchema, } from './tools/approval-schema' import { combineStrategies, maxIterations as maxIterationsStrategy, untilFinishReason, } from './agent-loop-strategies' import { isCancelRequestedReason } from './cancel' import { applyActivityDeltaToRecords, applyActivitySnapshotToRecords, interleaveActivityRecords, peelInboundActivities, } from './activity-records' import { appendUiResourceToModelMessages, convertMessagesToModelMessages, generateMessageId, modelMessagesToUIMessages, safeJsonStringify, uiResourcePartFromCustomValue, } from './messages' import { MiddlewareRunner } from './middleware/compose' import { getRunDetached } from './middleware/run-store' import { LoadChildCapability } from './middleware/load-child' import { publishRunDetachedSignal } from '../../delivery-detach' import { publishRunDisconnectHandler } from '../../delivery-disconnect' import { provideSandboxRuntime } from './middleware/sandbox-runtime' import { provideRunDisconnect } from './middleware/run-disconnect' import { CapabilityRegistry } from './middleware/capabilities' import { validateCapabilities } from './middleware/validate' import { MCPManager } from './mcp/manager' import type { InterruptBinding, InterruptSubmissionError, ToolApprovalResolution, } from '../../interrupts' import type { ApprovalRequest, ClientToolRequest, ExecuteToolCallsResult, McpInputRequest, ToolExecutionMiddlewareHooks, ToolResult, ToolResumeExecutionState, } from './tools/tool-calls' import type { ApprovalSchemaConfig, InferToolName, } from './tools/tool-definition' import type { AnyTextAdapter, StructuredOutputOptions, StructuredOutputResult, } from './adapter' import type { ActivityRecord, AgentLoopStrategy, AnyTool, ChatStream, ConstrainedModelMessage, CustomEvent, EmitCustomEventOptions, InferSchemaType, Interrupt, JSONSchema, LazyToolsConfig, MidConversationChange, ModelMessage, ModelMessageBlock, PromptCacheOptions, ProviderTool, ResolvedPromptCache, RunErrorEvent, RunFinishedEvent, SchemaInput, StreamChunk, StructuredOutputCompleteEvent, StructuredOutputPart, StructuredOutputStream, TanStackMessageMetadata, TextMessageContentEvent, TextOptions, TokenUsage, ToolCall, ToolCallArgsEvent, ReasoningEncryptedValueEvent, ToolCallEndEvent, ToolCallResultEvent, ToolCallStartEvent, ToolChoice, FetchWrapper, ToolExecutionContext, ToolInputResponse, UIMessage, } from '../../types' import type { AnyChatMiddleware, ChatMiddleware, ChatMiddlewareConfig, ChatMiddlewareContext, ChatResumeGenericResolution, ChatResumeToolState, InterruptResolutionCollection, SandboxFileHookEvent, StructuredOutputMiddlewareConfig, } from './middleware/types' import { provideGenericInterruptDefinitionRegistry } from './middleware/generic-interrupts' import type { CheckCoverage } from './middleware/builder' import type { SystemPrompt } from '../../system-prompts' import type { InternalLogger } from '../../logger/internal-logger' import type { DebugOption } from '../../logger/types' import type { ContextFromMiddleware, ContextFromTool, DefinedContext, MergeContext, UnionToIntersection, } from './runtime-context-types' import type { ChatMCPOptions } from './mcp/types' import type { AdapterReasoning, ReasoningOption, ReasoningOptionFor, } from '../../reasoning' /** One entry of the per-iteration arrival order (see `turnParts`). */ type TurnPart = | { type: 'thinking'; index: number } | { type: 'text'; content: string } | { type: 'call'; id: string; providerExecuted: boolean } /** * The order map for one assistant message built from `parts`. Calls that are * not in `toolCalls` are left out, because the message does not carry them. * Calls that the stream did not report go last, their default place. */ function turnBlockOrder( parts: ReadonlyArray, toolCalls: ReadonlyArray, ): Array | undefined { const unplaced = new Set(toolCalls.map((toolCall) => toolCall.id)) const entries = parts.flatMap((part): Array => { if (part.type === 'thinking') return [{ type: 'thinking' }] if (part.type === 'text') return [{ type: 'text', text: part.content }] return unplaced.delete(part.id) ? [{ type: 'tool-call', id: part.id }] : [] }) for (const id of unplaced) entries.push({ type: 'tool-call', id }) return buildBlockOrder(entries) } /** * The tool result of a call in an answer cut at the output limit. Middleware * `onAfterToolCall` can replace it: the error of such a call has the code * `'max_tokens'`. */ const TRUNCATED_TOOL_RESULT = 'The answer stopped at the output limit, so no tool call in it ran. Send the tool calls again. Do not repeat text you already wrote. If one call has a large input, split the work into smaller calls.' // =========================== // Activity Kind // =========================== /** The adapter kind this activity handles */ export const kind = 'text' as const type AnyRuntimeTool = AnyTool type RuntimeToolWithApproval = AnyRuntimeTool & { approvalSchema?: ApprovalSchemaConfig } const interruptBindingMetadataKey = INTERRUPT_BINDING_METADATA_KEY /** Most `ctx.retry()` calls kept for one model call. */ const MAX_MODEL_ERROR_RETRIES = 2 /** Resume entries a subagent tool call owns. The parent run skips them. */ const CHILD_RESUME_IDS = Symbol('tanstack.ai.childResumeIds') /** * A durable resume check that `withPersistence` leaves on the init config. * The run calls it after the whole `onConfig` chain, so it checks the resume * against the tools that a later middleware added too. */ const DURABLE_RESUME = Symbol.for('tanstack.ai.durableResume') interface StructuralInterruptFailure { error: Error errors: ReadonlyArray } function isInterruptSubmissionError( value: unknown, ): value is InterruptSubmissionError { if (value === null || typeof value !== 'object' || Array.isArray(value)) { return false } if ( !('scope' in value) || !('code' in value) || !('message' in value) || !('source' in value) || !('retryable' in value) || !('threadId' in value) || !('interruptedRunId' in value) || !('generation' in value) || typeof value.code !== 'string' || typeof value.message !== 'string' || typeof value.retryable !== 'boolean' || typeof value.threadId !== 'string' || typeof value.interruptedRunId !== 'string' || typeof value.generation !== 'number' ) { return false } if (value.scope === 'item') { return ( 'interruptId' in value && typeof value.interruptId === 'string' && (value.source === 'client' || value.source === 'server') ) } return ( value.scope === 'batch' && 'interruptIds' in value && Array.isArray(value.interruptIds) && value.interruptIds.every((id) => typeof id === 'string') && (value.source === 'client' || value.source === 'server' || value.source === 'transport') ) } function structuralInterruptFailure( error: unknown, ): StructuralInterruptFailure | undefined { if ( !(error instanceof Error) || error.name !== 'InterruptResumeValidationError' || !('errors' in error) || !Array.isArray(error.errors) || error.errors.length === 0 || !error.errors.every(isInterruptSubmissionError) ) { return undefined } return { error, errors: error.errors, } } function normalizePublicInterruptBinding( value: unknown, expectedInterruptId: string, ): InterruptBinding | undefined { return readInterruptBinding({ id: expectedInterruptId, reason: '', metadata: { [INTERRUPT_BINDING_METADATA_KEY]: value }, }) } // The leaf context-inference primitives (KnownContext, MergeContext, // UnionToIntersection, DefinedContext, ContextFromTool, ContextFromMiddleware) // are shared with the tool execution layer — see ./runtime-context-types. type ContextFromConsumer = ContextFromTool | ContextFromMiddleware type RequiredContextFromConsumerUnion = T extends unknown ? undefined extends ContextFromConsumer ? never : ContextFromConsumer : never type ContextFromConsumerUnion = [ UnionToIntersection>>, ] extends [never] ? never : [RequiredContextFromConsumerUnion] extends [never] ? UnionToIntersection>> | undefined : UnionToIntersection>> type ContextFromArray = T extends readonly [infer THead, ...infer TTail] ? MergeContext, ContextFromArray> : T extends ReadonlyArray ? ContextFromConsumerUnion : never type ContextFromInputs = MergeContext< ContextFromArray>, ContextFromArray> > type InferredContext = [ ContextFromInputs, ] extends [never] ? unknown : ContextFromInputs type RegistryInterrupt< TInterrupts extends ReadonlyArray>, > = [TInterrupts[number]] extends [never] ? never : TInterrupts[number] type DuplicateInterruptDefinitionId< TInterrupts extends ReadonlyArray>, TSeenIds extends string = never, > = TInterrupts extends readonly [infer THead, ...infer TTail] ? THead extends InterruptDefinition ? string extends TId ? TTail extends ReadonlyArray> ? DuplicateInterruptDefinitionId : never : TId extends TSeenIds ? TId : TTail extends ReadonlyArray> ? DuplicateInterruptDefinitionId : never : never : never type CheckUniqueInterruptDefinitions< TInterrupts extends ReadonlyArray>, > = [DuplicateInterruptDefinitionId] extends [never] ? unknown : { readonly '✖ Duplicate interrupt definition id in chat({ interrupts }).': never } type InlineChatContext = MergeContext< ContextFromArray>, TContext > type RegistryChatMiddleware< TContext, TInterrupts extends ReadonlyArray>, > = ChatMiddleware> type MiddlewareInterruptDefinitions = TMiddleware extends ReadonlyArray ? TMiddlewareItem extends ChatMiddleware ? TDefinitions : never : never type IsAny = 0 extends 1 & TValue ? true : false type CheckInterruptRegistry< TInterrupts extends ReadonlyArray>, TMiddleware, > = IsAny> extends true ? unknown : [MiddlewareInterruptDefinitions] extends [never] ? unknown : [ Exclude< MiddlewareInterruptDefinitions, RegistryInterrupt >, ] extends [never] ? unknown : { readonly '✖ Middleware emits an interrupt definition that is not registered in chat({ interrupts }).': never } type RuntimeContextOption = [ MergeContext, TContext>, ] extends [never] ? { context?: TContext } : undefined extends MergeContext< ContextFromInputs, TContext > ? { context?: MergeContext, TContext> } : { context: MergeContext, TContext> } type ExactMiddlewareOption< TTools, TContext, TInterrupts extends ReadonlyArray>, TMiddleware extends Array | undefined, > = [TMiddleware] extends [undefined] ? Array< RegistryChatMiddleware< InlineChatContext, NoInfer > > : TMiddleware & (TMiddleware extends Array< RegistryChatMiddleware< InlineChatContext>, NoInfer > > ? Array< RegistryChatMiddleware< InlineChatContext, NoInfer > > : CheckInterruptRegistry) & CheckCoverage>> /** The `name` literals of a `tools` array. */ type ToolNames = TTools extends ReadonlyArray ? Extract, string> : never type TextActivityOptionsWithContext< TAdapter extends AnyTextAdapter, TSchema extends SchemaInput | undefined, TStream extends boolean, TTools extends TextActivityOptions['tools'], TInterrupts extends ReadonlyArray> = [], TContext = unknown, TMiddleware extends Array | undefined = undefined, TAgents extends ReadonlyArray = ReadonlyArray, > = Omit< TextActivityOptions, 'tools' | 'middleware' | 'context' | 'interrupts' | 'toolChoice' > & TypedChatFields /** * The `chat()` options of `ctx.chat` on a subagent. `threadId` is optional: * the child run fills it. */ export type BoundTextActivityOptions< TAdapter extends AnyTextAdapter, TSchema extends SchemaInput | undefined, TStream extends boolean, TTools extends TextActivityOptions['tools'], TInterrupts extends ReadonlyArray> = [], TContext = unknown, TMiddleware extends Array | undefined = undefined, TAgents extends ReadonlyArray = ReadonlyArray, > = WithOptionalThreadId< Omit< TextActivityOptions, 'tools' | 'middleware' | 'context' | 'interrupts' | 'toolChoice' > > & TypedChatFields /** Activity options with an optional `threadId`. */ export type WithOptionalThreadId = Omit & { threadId?: string } /** The `chat()` fields whose types come from the tools and middleware. */ type TypedChatFields< TTools, TInterrupts extends ReadonlyArray>, TContext, TMiddleware extends Array | undefined, > = { tools?: TTools /** {@link TextActivityOptions.toolChoice}, with the names of `tools` as suggestions. */ toolChoice?: ToolChoice> interrupts?: TInterrupts & CheckUniqueInterruptDefinitions middleware?: ExactMiddlewareOption } & RuntimeContextOption // =========================== // Activity Options Type // =========================== /** * Options for the text activity. * Types are extracted directly from the adapter (which has pre-resolved generics). * * @template TAdapter - The text adapter type (created by a provider function) * @template TSchema - Optional Standard Schema for structured output * @template TStream - Whether to stream the output (default: true) * @template TContext - Runtime context value threaded to middleware hooks and server tools */ export interface TextActivityOptions< TAdapter extends AnyTextAdapter, TSchema extends SchemaInput | undefined, TStream extends boolean, TContext = unknown, TAgents extends ReadonlyArray = ReadonlyArray, > { /** The text adapter to use (created by a provider function like openaiText('gpt-5.5')) */ adapter: TAdapter /** * Conversation messages. Accepts: * - `ConstrainedModelMessage` — content types constrained by the adapter's input modalities. * - `ModelMessage` — unconstrained model message (e.g., forwarded from an AG-UI wire payload). * - `UIMessage` — parts-based UI representation; converted internally via `convertMessagesToModelMessages`. * * The three shapes can be mixed in a single array (e.g., when forwarding a wire payload that includes both anchor UIMessages and AG-UI fan-out ModelMessages). */ messages?: | Array< | UIMessage | ModelMessage | ConstrainedModelMessage<{ inputModalities: TAdapter['~types']['inputModalities'] messageMetadataByModality: TAdapter['~types']['messageMetadataByModality'] }> > | undefined /** * System prompts to prepend to the conversation. * * Accepts plain strings or `{ content, metadata }` objects. The `metadata` * field is typed by the adapter — Anthropic narrows it to * `AnthropicSystemPromptMetadata` (with `cache_control` for prompt * caching), providers without per-prompt metadata reject the field * entirely. */ systemPrompts?: | Array> | undefined /** * Tools for function calling (auto-executed when called). * * Accepts two shapes: * - User-defined tools via `toolDefinition()` — plain `Tool`, always assignable. * - Provider tools from `@tanstack/ai-/tools` (e.g. `webSearchTool`) * — branded and type-checked against the selected model's * `supports.tools` list. Passing an unsupported tool produces a * compile-time error on the array element. */ tools?: | ReadonlyArray< | (AnyRuntimeTool & { readonly '~toolKind'?: never }) | ProviderTool > | undefined /** * Hand MCP clients/pools to chat(): their tools are discovered at run start * and merged into the run; `connection` controls whether chat() closes them * when the run ends. See docs/tools/mcp.md "Managing MCP clients with chat()". */ mcp?: ChatMCPOptions /** Additional metadata to attach to the request. */ metadata?: TextOptions['metadata'] /** Model-specific provider options (type comes from adapter) */ modelOptions?: TAdapter['~types']['providerOptions'] /** * How hard the model thinks: a level (`'low'`, `'high'`, ...) or * `{ level, summary?, budgetTokens? }`. The types allow only the model's own * levels. Not set: the provider default applies. `'off'` turns thinking off. * A level the model does not support at runtime moves to the nearest one. */ reasoning?: ReasoningOptionFor> /** AbortController for cancellation */ abortController?: TextOptions['abortController'] /** * Strategy for controlling the agent loop. Default: * `combineStrategies([maxIterations(5), untilFinishReason(['length'])])`. * A strategy that goes on after a `length` answer makes the model send the * cut tool calls of that answer again. */ agentLoopStrategy?: TextOptions['agentLoopStrategy'] /** How the server tools of one model turn run. Default `'parallel'`. */ toolExecution?: TextOptions['toolExecution'] /** * How a tool input that fails the final check is repaired. Default: the * built-in repair. `false`: no repair. A function replaces it. */ repairToolInput?: TextOptions['repairToolInput'] /** * Retry a rate-limited model call after the wait the provider asks for. * * @example * ```ts * chat({ adapter, messages, threadId, retry: { maxRetries: 3 } }) * ``` */ retry?: TextOptions['retry'] /** * Optional configuration for lazy-tool discovery (tools marked `lazy: true`). * Tunes how much of each lazy tool's description appears in the discovery * catalog. Optional — defaults to `{ includeDescription: 'none' }`. */ lazyToolsConfig?: LazyToolsConfig /** * Thread/conversation id for the AG-UI protocol. Required. Use a stable id * for each conversation. */ threadId: TextOptions['threadId'] /** * How the model uses the tools: `'auto'`, `'none'`, `'required'`, or * `{ type: 'tool', name }`. It applies to every model call of this * `chat()`. A middleware `onConfig` can change it for one call. A call with * no tools sends no tool choice. A provider value in `modelOptions` wins. * * @example * ```ts * chat({ adapter, messages, threadId, tools, toolChoice: 'required' }) * ``` */ toolChoice?: ToolChoice /** * Automatic prompt caching. Default `'short'`. `'none'` turns it off. * The key defaults to the `threadId` that you give. * * @example * ```ts * chat({ adapter, messages, threadId, promptCache: 'long' }) * chat({ adapter, messages, threadId, promptCache: { retention: 'long', key: 'k-1' } }) * ``` */ promptCache?: PromptCacheOptions /** * Wraps the fetch of each model call. It can change the base URL, the * headers, the request, or the response. A middleware `onConfig` can add * a wrapper for one call. It chains inside this one. The adapter must * support it. * * @example * ```ts * chat({ adapter, messages, threadId, wrapFetch: (next) => (input, init) => next(input, init) }) * ``` */ wrapFetch?: FetchWrapper /** Run ID override for AG-UI protocol. Auto-generated by adapter if not provided. */ runId?: TextOptions['runId'] /** Parent run ID for AG-UI protocol nested run correlation. */ parentRunId?: TextOptions['parentRunId'] /** Subagent run id when this chat runs as a child. See `defineAgent`. */ subagentRunId?: TextOptions['subagentRunId'] /** The agent name when this chat runs as a subagent. Middleware reads `ctx.subagentName`. */ subagentName?: TextOptions['subagentName'] /** The subagentRunId of the child that started this one, for a nested child. */ parentSubagentRunId?: TextOptions['parentSubagentRunId'] /** Application state mirrored in a STATE_SNAPSHOT before an interrupt terminal. */ state?: TextOptions['state'] /** * AG-UI interrupt resume responses. Persistence middleware validates these * before accepting new input on a thread with pending interrupts. */ resume?: TextOptions['resume'] /** * Named child agents. When `router` is set, the library spawns that agent * directly. When `router` is omitted, the main model gets one synthetic * server tool per agent and picks the child. */ subagents?: SubagentsBag /** * Optional Standard Schema for structured output. * When provided, the activity will: * 1. Run the full agentic loop (executing tools as needed) * 2. Once complete, return a Promise with the parsed output matching the schema * * Supports any Standard Schema compliant library (Zod v4+, ArkType, Valibot, etc.) * * @example * ```ts * const result = await chat({ * adapter: openaiText('gpt-5.5'), * messages: [{ role: 'user', content: 'Generate a person' }], * threadId, * outputSchema: z.object({ name: z.string(), age: z.number() }) * }) * // result is { name: string, age: number } * ``` */ outputSchema?: TSchema /** * Whether to stream the text result. * When true (default), returns a ChatStream for streaming output. * When false, returns a Promise with the collected text and * every chunk the run produced. * * Note: If outputSchema is provided, this option is ignored and the result * is always a Promise>. * * @default true * * @example Non-streaming text * ```ts * const { text } = await chat({ * adapter: openaiText('gpt-5.5'), * messages: [{ role: 'user', content: 'Hello!' }], * threadId, * stream: false * }) * // text is a string with the full response * ``` */ stream?: TStream /** * Optional middleware array for observing/transforming chat behavior. * Middleware hooks are called in array order. See {@link ChatMiddleware} for available hooks. * * @example * ```ts * const stream = chat({ * adapter: openaiText('gpt-5.5'), * messages: [...], * threadId, * middleware: [loggingMiddleware, redactionMiddleware], * }) * ``` */ middleware?: Array> /** * First-party generic interrupt definitions for this chat call. * Register the same definitions on the client to type payloads and answers. */ interrupts?: ReadonlyArray> /** * Runtime context value passed to middleware hooks and server tools. */ context?: TContext /** * Enable debug logging. Pass `true` to enable all categories with the default * console logger, `false` to silence everything, or a `DebugConfig` object for * granular control and/or a custom `Logger`. Defaults to `undefined`, which * means only the `errors` category is active. */ debug?: DebugOption } // =========================== // Chat Options Helper // =========================== /** * Create typed options for the chat() function without executing. * This is useful for pre-defining configurations with full type inference. * `threadId` is optional here. `chat()` still needs it, so pass it on the * call. * * @example * ```ts * const chatOptions = createChatOptions({ * adapter: anthropicText('claude-sonnet-5-5'), * }) * * const stream = chat({ ...chatOptions, messages, threadId }) * ``` */ export function createChatOptions< TAdapter extends AnyTextAdapter, TSchema extends SchemaInput | undefined = undefined, TStream extends boolean = true, const TTools extends TextActivityOptions< TAdapter, TSchema, TStream, any >['tools'] = TextActivityOptions['tools'], const TInterrupts extends ReadonlyArray< InterruptDefinition > = [], TContext = unknown, const TMiddleware extends Array | undefined = undefined, >( options: BoundTextActivityOptions< TAdapter, TSchema, TStream, TTools, TInterrupts, TContext, TMiddleware >, ): WithOptionalThreadId< Omit< TextActivityOptions< TAdapter, TSchema, TStream, InferredContext >, 'tools' | 'middleware' | 'interrupts' | 'context' > > & { tools?: TTools interrupts?: TInterrupts middleware?: ExactMiddlewareOption } & RuntimeContextOption { return options } // =========================== // Activity Result Type // =========================== /** * Result type for the text activity. * - If outputSchema is provided AND stream is explicitly true: * StructuredOutputStream> — yields raw JSON deltas * via TEXT_MESSAGE_CONTENT plus a terminal StructuredOutputCompleteEvent * carrying the validated object. * - If outputSchema is provided without explicit stream:true: * Promise>. * - If stream is explicitly false (no schema): Promise. * - Otherwise (default): ChatStream. * * `[TStream] extends [true]` is used (not `TStream extends true`) so that the * default `boolean` value of `TStream` does *not* match the streaming branch. * Without this, plain `chat({ outputSchema })` would type as a stream while * the runtime returns a Promise — see issue #526. */ export type TextActivityResult< TSchema extends SchemaInput | undefined, TStream extends boolean = boolean, // Unconstrained so `chat()` can forward its inferred `options['tools']` type // (which may be `undefined` or the broad `AnyRuntimeTool | ProviderTool` // array) directly; non-tool-array inputs normalize to the default below. TTools = ReadonlyArray, > = TSchema extends SchemaInput ? [TStream] extends [true] ? StructuredOutputStream> : Promise> : [TStream] extends [false] ? Promise : TTools extends infer _TTools ? ChatStream : ChatStream // =========================== // ChatEngine Implementation // =========================== interface TextEngineConfig< TAdapter extends AnyTextAdapter, TContext = unknown, TParams extends TextOptions = TextOptions< any, any, TContext >, > { adapter: TAdapter systemPrompts?: Array params: TParams middleware?: Array context?: TContext /** * If set, after the agent loop finishes the engine runs a * structured-output finalization step through the same middleware * pipeline. See `runStructuredFinalization` for the flow. * * - jsonSchema: the JSON Schema to send to the provider * - yieldChunks: when true, finalization chunks are yielded to the caller * (used by runStreamingStructuredOutput). When false, chunks are * consumed internally for middleware visibility but not yielded * (used by runAgenticStructuredOutput). * - normalize: optional schema-aware transform applied to the captured * structured-output object the moment it enters the engine — BEFORE it is * stored, validated, or yielded. Used to undo strict-mode null-widening * (`undoNullWidening`): strict schemas widen optional fields to * `required` + nullable so the provider returns `null` for an absent * optional, and this strips exactly those synthesized nulls while keeping * the ones a `.nullable()` field genuinely allows. Applied here (not in * the adapter) because the engine is the only layer holding the original * schema's null-widening map, and applying it at capture fixes BOTH the * streaming chunk and the Promise result with one transform. * - validate: optional callback invoked AFTER `normalize` and AFTER the * structured-output result is captured, but BEFORE the terminal hook * fires. If it throws, the engine records a `finalizationError` and fires * `onError` instead of `onFinish` (per spec §7.3). On success, the * returned value is stored as the validated result and retrievable via * `getValidatedStructuredOutput()`. Both structured-output paths (Promise * and stream) pass it for a Standard Schema. * - nativeCombined: when true, the adapter declared * `supportsCombinedToolsAndSchema()` and the engine wires `jsonSchema` * into the regular `chatStream` call instead of running a separate * finalization round-trip. The `'structuredOutput'` middleware phase * does NOT fire on this path — middleware sees the run through * `beforeModel` / `modelStream` as usual. * - source: how to take the combined object. `'text'` (default) parses * accumulated assistant text. `'event'` reads an adapter-emitted * `structured-output.complete` and does not parse prose. */ finalStructuredOutput?: { jsonSchema: JSONSchema yieldChunks: boolean normalize?: (data: unknown) => unknown validate?: (data: unknown) => unknown nativeCombined?: boolean source?: 'text' | 'event' } } type ToolPhaseResult = 'continue' | 'stop' | 'wait' type CyclePhase = 'processText' | 'executeToolCalls' /** * Combine two optional AbortSignals into one that aborts when either does. * Returns the other signal directly when one is absent or already aborted. * (Manual implementation — `AbortSignal.any` requires Node >= 20.3.) */ function combineAbortSignals( a: AbortSignal | undefined, b: AbortSignal | undefined, ): AbortSignal | undefined { if (!a) return b if (!b) return a if (a.aborted) return a if (b.aborted) return b const controller = new AbortController() const onAbort = (source: AbortSignal) => () => { controller.abort(source.reason) } a.addEventListener('abort', onAbort(a), { once: true }) b.addEventListener('abort', onAbort(b), { once: true }) return controller.signal } /** Wait `ms`, or less when the signal aborts. It never rejects. */ function waitOrAbort(ms: number, signal: AbortSignal | undefined) { return new Promise((resolve) => { if (signal?.aborted) return resolve() const done = () => { clearTimeout(timer) signal?.removeEventListener('abort', done) resolve() } // A longer delay overflows `setTimeout` and fires at once. const timer = setTimeout(done, Math.min(ms, 2 ** 31 - 1)) signal?.addEventListener('abort', done, { once: true }) }) } class TextEngine< TAdapter extends AnyTextAdapter, TContext = unknown, TParams extends TextOptions = TextOptions< any, any, TContext >, > { private readonly adapter: TAdapter private readonly interruptDefinitions: ReadonlyMap< string, InterruptDefinition > private params: TParams /** * The tool choice of the next model call. `params.toolChoice` keeps the * `chat()` option, so a middleware value lasts for one call only. */ private callToolChoice: ToolChoice | undefined = undefined /** The composed fetch wrapper of the next model call. */ private callWrapFetch: FetchWrapper | undefined = undefined private systemPrompts: Array private tools: Array private readonly loopStrategy: AgentLoopStrategy private toolCallManager: ToolCallManager, TContext> private readonly lazyToolManager: LazyToolManager /** A public interruption terminal must always have this run's start event. */ private hasPublicRunStarted = false private readonly initialMessageCount: number private readonly requestId: string private readonly streamId: string private readonly effectiveRequest?: Request | RequestInit private readonly effectiveSignal?: AbortSignal /** The caller signal plus ctx.abort(), only when there is a caller signal. */ private readonly linkedSignal?: AbortSignal private messages: Array private activities: Array = [] private providerMessages: Array private iterationCount = 0 /** Cumulative tool calls counted in this run (emitted + pending resume). */ private toolCallCount = 0 /** Tool calls in the most recent budgeted batch (0 when none). */ private lastTurnToolCallCount = 0 /** Tool call IDs already counted toward `toolCallCount` (avoids double-count on resume). */ private readonly countedToolCallIds = new Set() private lastFinishReason: string | null = null /** The loop decision of a cut answer, from its tool phase (processToolCalls). */ private cutAnswerContinues: boolean | undefined private streamStartTime = 0 private totalChunkCount = 0 private currentMessageId: string | null = null private currentMessageCreatedAt: Date | null = null private streamIdentityCaptured = false private accumulatedContent = '' private accumulatedThinking: NonNullable = [] /** * Arrival order of this iteration's thinking steps, text and tool calls. * A ModelMessage keeps `thinking` apart from `content`/`toolCalls`, so a * provider turn that thinks between provider-executed tools would otherwise * be recorded as "all thinking, then text, then tools" and the provider * rejects the replay (signed thinking must keep its position). `null` once * the order could no longer be tracked (callers fall back to one message). */ private turnParts: Array | null = [] /** * The mid-conversation record of the current model call. The first * assistant message that the call produces takes it. A call that produces * none (an error, an abort) saves nothing, and the next call plans again. */ private pendingMidConversationChange: MidConversationChange | undefined = undefined private currentThinkingContent = '' private currentThinkingSignature = '' private currentThinkingRedacted = false private eventOptions?: Record | undefined private currentCallMetadata: TanStackMessageMetadata = {} /** An abort ended the wait of `retryRateLimited`. Its last chunks still go to the caller. */ private retryAbandoned = false /** `onModelError` is running, so `ctx.retry()` is allowed. */ private inModelErrorHook = false /** A middleware called `ctx.retry()` for the current model call. */ private retryModelCall = false /** `ctx.retry()` calls kept for the current model call. */ private modelErrorRetries = 0 private structuredCallMetadata: TanStackMessageMetadata = {} private eventToolNames?: Array private finishedEvent: RunFinishedEvent | null = null private readonly streamedToolErrorResults = new Map() private deferredToolCallRunFinishedChunks: Array = [] /** The model terminal is held until afterModel can choose an interrupt. */ private deferredModelRunFinishedChunks: Array = [] private earlyTermination = false /** * The strategy or `onShouldContinue` refused another model call while tool * results waited. A length cut sets this too. The synthetic RUN_FINISHED * is skipped when that cut already sent its own finish. */ private loopStopped = false private loopStoppedFinishSent = false private toolPhase: ToolPhaseResult = 'continue' private cyclePhase: CyclePhase = 'processText' // Client state extracted from initial messages (before conversion to ModelMessage) private readonly initialApprovals: Map private readonly initialClientToolResults: Map private readonly resumeApprovals = new Map() private readonly resumeClientToolResults = new Map() private readonly resumeClientToolErrors = new Map() private readonly resumeDeniedToolResults = new Map() private readonly resumeCancelledToolCallIds = new Set() private readonly resumeInputResponses = new Map() private readonly resumeGenericInterrupts = new Map< string, ChatResumeGenericResolution >() private readonly resumeGenericInterruptRequests = new Map< string, GenericInterruptRequest> >() // AG-UI protocol IDs private readonly threadId: string private readonly runIdOverride?: string private readonly parentRunIdOverride?: string private readonly subagentRunIdOverride?: string // Middleware support private readonly middlewareRunner: MiddlewareRunner< TContext, InterruptDefinition > private readonly middlewareCtx: ChatMiddlewareContext private readonly sandboxFileQueue: Array = [] private readonly middlewareCustomQueue: Array = [] private middlewareCustomWaiters: Array<() => void> = [] private drainingMiddlewareCustom = false private readonly deferredPromises: Array> = [] private abortReason?: string private readonly middlewareAbortController?: AbortController // Combines the caller's signal with middleware abort() so running tools // observe both cancellation sources via ctx.abortSignal. private readonly toolAbortSignal?: AbortSignal private terminalHookCalled = false /** * Latched the first time the delivery socket closes; see `notifyDisconnected`. * Also read by `subscribe` so a listener registered AFTER the disconnect (a * middleware whose `setup` was still running at the time — the common case) is * called immediately rather than never. */ private disconnected = false private readonly disconnectListeners: Array<() => void | Promise> = [] private readonly logger: InternalLogger // Structured-output finalization state (populated by runStructuredFinalization) private structuredOutputResult: { data: unknown rawText: string reasoning?: string } | null = null private structuredOutputMessageId: string | null = null private structuredOutputMessageCreatedAt: Date | null = null // Native combined mode: tracks whether we've already emitted the synthetic // `structured-output.start` event before the schema-constrained final-turn // text begins streaming. The event must precede the first // TEXT_MESSAGE_START so the client-side StreamProcessor routes the JSON // deltas into a StructuredOutputPart instead of a plain TextPart. private combinedStartEmitted = false // Native combined mode: messageId we want the synthetic // `structured-output.start` (and any error emitted before deltas arrive) // to carry, so the client matches it to the streaming text deltas. private combinedStructuredMessageId: string | null = null // Holds the validated value when `finalStructuredOutput.validate` is provided // and succeeds. Distinct from `structuredOutputResult.data` (the normalized // but unvalidated payload from the structured-output.complete chunk). private validatedStructuredOutput: unknown = undefined private hasValidatedStructuredOutput = false private finalizationError: { message: string code?: string cause?: unknown /** Full model text, when a structured-output parse failed (#1485). */ rawText?: string } | null = null private combinedCompleteEmitted = false private readonly finalStructuredOutput?: { jsonSchema: JSONSchema yieldChunks: boolean normalize?: (data: unknown) => unknown validate?: (data: unknown) => unknown nativeCombined?: boolean source?: 'text' | 'event' } constructor( config: TextEngineConfig, logger: InternalLogger, ) { this.logger = logger this.adapter = config.adapter this.interruptDefinitions = new Map( ( ( config.params as TParams & { interrupts?: ReadonlyArray> } ).interrupts ?? [] ).map((definition) => [definition.id, definition]), ) this.finalStructuredOutput = config.finalStructuredOutput this.params = { ...config.params, // `chat()` takes a level or an object. Adapters read one shape. reasoning: normalizeReasoning( config.params.reasoning as ReasoningOption | undefined, ), } this.systemPrompts = config.params.systemPrompts || [] this.loopStrategy = config.params.agentLoopStrategy || combineStrategies([ maxIterationsStrategy(5), untilFinishReason(['length']), ]) this.initialMessageCount = config.params.messages.length // Extract client state (approvals, client tool results) from original messages BEFORE conversion // This preserves UIMessage parts data that would be lost during conversion to ModelMessage const { approvals, clientToolResults } = this.extractClientStateFromOriginalMessages( config.params.messages as Array, ) this.initialApprovals = approvals this.initialClientToolResults = clientToolResults // Convert messages to ModelMessage format (handles both UIMessage and ModelMessage input) // This ensures consistent internal format regardless of what the client sends this.activities = peelInboundActivities(config.params.messages ?? []) this.messages = convertMessagesToModelMessages(config.params.messages) this.providerMessages = this.messages // Initialize lazy tool manager after messages are converted (needs message history for scanning) assertUniqueToolNames(config.params.tools || []) this.lazyToolManager = new LazyToolManager( config.params.tools || [], this.messages, config.params.lazyToolsConfig, ) this.tools = this.lazyToolManager.getActiveTools() this.toolCallManager = new ToolCallManager< ReadonlyArray, TContext >(this.tools) this.requestId = this.createId('chat') this.streamId = this.createId('stream') this.effectiveSignal = config.params.abortController?.signal this.threadId = config.params.threadId this.runIdOverride = config.params.runId this.parentRunIdOverride = config.params.parentRunId this.subagentRunIdOverride = config.params.subagentRunId // Initialize middleware — devtools first. Spec stripping for the AG-UI // wire happens in toServerSentEventsStream, so in-process chat() // consumers still see TokenUsage and tool aliases. const allMiddleware: Array< ChatMiddleware> > = [devtoolsMiddleware(), ...(config.middleware || [])] this.middlewareRunner = new MiddlewareRunner(allMiddleware, logger) this.middlewareAbortController = new AbortController() this.toolAbortSignal = combineAbortSignals( this.effectiveSignal, this.middlewareAbortController.signal, ) // With a caller signal, the provider request and ctx.signal follow // ctx.abort() too. Without one they get no signal, as before: some SDKs // drop their own timeout when a request has a signal. this.linkedSignal = this.effectiveSignal ? this.toolAbortSignal : undefined this.effectiveRequest = this.linkedSignal ? { signal: this.linkedSignal } : undefined this.middlewareCtx = { requestId: this.requestId, streamId: this.streamId, runId: this.runIdOverride ?? this.requestId, parentRunId: this.parentRunIdOverride, subagentRunId: this.subagentRunIdOverride, subagentName: config.params.subagentName, parentSubagentRunId: config.params.parentSubagentRunId, childResumeIds: ( config.params as { [CHILD_RESUME_IDS]?: ReadonlySet } )[CHILD_RESUME_IDS], threadId: this.threadId, phase: 'init', iteration: 0, chunkIndex: 0, callMetadata: this.currentCallMetadata, signal: this.linkedSignal, abort: (reason?: string) => { this.abortReason = reason this.middlewareAbortController?.abort(reason) }, retry: () => { if (!this.inModelErrorHook) { throw new Error('ctx.retry() works only in onModelError.') } this.retryModelCall = true }, emitCustomEvent: (name, value, options) => { this.middlewareCustomQueue.push( this.createCustomEventChunk(name, value, options), ) const waiters = this.middlewareCustomWaiters this.middlewareCustomWaiters = [] for (const waiter of waiters) waiter() }, context: config.context as TContext, defer: (promise: Promise) => { this.deferredPromises.push(promise) }, // Provider / adapter info activity: 'chat', provider: config.adapter.name, model: config.params.model, source: 'server', streaming: true, // Config-derived (updated in beforeRun and applyMiddlewareConfig) systemPrompts: this.systemPrompts, toolNames: undefined, options: undefined, modelOptions: config.params.modelOptions, // Computed messageCount: this.initialMessageCount, hasTools: this.tools.length > 0, // Mutable per-iteration currentMessageId: null, accumulatedContent: '', // References messages: this.messages, activities: this.activities, createId: (prefix: string) => this.createId(prefix), // Capability bookkeeping for this request (populated by middleware setup) capabilities: new CapabilityRegistry(), // Convenience accessors that delegate to a capability handle's own // tuple getter/provider, keyed by this context. `getX(ctx)` and // `ctx.get(X)` are interchangeable. get: (capability) => capability[0](this.middlewareCtx), getOptional: (capability) => capability[0](this.middlewareCtx, { optional: true }), provide: (capability, value) => capability[1](this.middlewareCtx, value), } // Provide the internal RunDisconnect capability BEFORE `setup` runs, so a // middleware can subscribe from inside its own `setup` — which is where the // subscription has to happen, because `setup` is the long await the common // disconnect lands in. // // `subscribe` calls back IMMEDIATELY when the socket has already closed. That // ordering is load-bearing rather than defensive: a middleware whose `setup` // was still running during the disconnect would otherwise register a listener // for an event that has already been and gone, and silently never detach. provideRunDisconnect(this.middlewareCtx, { subscribe: (listener) => { this.disconnectListeners.push(listener) if (this.disconnected) this.runDisconnectListener(listener) }, }) provideGenericInterruptDefinitionRegistry(this.middlewareCtx, { definitions: this.interruptDefinitions, }) // Provide the internal SandboxRuntime capability so harness adapters and // sandbox middleware can emit file events. The sink logs, fans the event // out through the middleware `onFile*` hooks (fire-and-forget), and queues // a `sandbox.file` custom chunk to be drained into the public stream. provideSandboxRuntime(this.middlewareCtx, { logger: this.logger, emit: (event: SandboxFileHookEvent) => { this.logger.sandbox(`file ${event.type} ${event.path}`, { event: { type: event.type, path: event.path, timestamp: event.timestamp, }, }) void this.middlewareRunner .runSandboxFile(this.middlewareCtx, event) .catch((err: unknown) => { this.logger.errors('sandbox file hook failed', { error: err }) }) this.sandboxFileQueue.push( this.createCustomEventChunk('sandbox.file', { type: event.type, path: event.path, timestamp: event.timestamp, }), ) }, emitFileDiff: (value: { path: string; diff: string }) => { this.sandboxFileQueue.push( this.createCustomEventChunk('sandbox.file.diff', value), ) }, }) } /** Get the accumulated content after the chat loop completes */ getAccumulatedContent(): string { return this.accumulatedContent } /** Get the final messages array after the chat loop completes */ getMessages(): Array { return this.messages } /** Returns the structured-output result if finalization ran successfully. */ getStructuredOutputResult(): { data: unknown; rawText: string } | null { return this.structuredOutputResult } /** * Returns the validated structured-output value (the result of running * `finalStructuredOutput.validate` against the raw structured-output data) * wrapped in a `{ value }` object so callers can distinguish "no validation * happened" from "validation produced undefined". Returns `null` when no * validator was configured or validation hasn't been performed yet. */ getValidatedStructuredOutput(): { value: unknown } | null { return this.hasValidatedStructuredOutput ? { value: this.validatedStructuredOutput } : null } /** Returns the recorded finalization error, if any. */ getFinalizationError(): { message: string code?: string cause?: unknown rawText?: string } | null { return this.finalizationError } /** * Check `data` with the `validate` of the structured output, once. A * failure sets `finalizationError` with the model text, so the run ends * with `onError` (and a RUN_ERROR on a stream). */ private validateStructuredOutput(data: unknown, rawText: string): void { const validate = this.finalStructuredOutput?.validate if (!validate || this.hasValidatedStructuredOutput) return try { this.validatedStructuredOutput = validate(data) this.hasValidatedStructuredOutput = true } catch (err: unknown) { this.finalizationError = { message: err instanceof Error ? err.message : String(err), code: 'structured-output-validation-failed', cause: err, rawText, } } } /** True when `data` passes the `validate` of the structured output, or there is none. */ private passesStructuredCheck(data: unknown): boolean { try { this.finalStructuredOutput?.validate?.(data) return true } catch { return false } } private async runTerminalHook(): Promise { if (this.terminalHookCalled || this.isCancelled()) return this.terminalHookCalled = true if (this.finalizationError) { const errForHook = new Error( this.finalizationError.message, this.finalizationError.cause !== undefined ? { cause: this.finalizationError.cause } : undefined, ) if (this.finalizationError.code !== undefined) { Object.defineProperty(errForHook, 'code', { value: this.finalizationError.code, enumerable: true, }) } if (this.finalizationError.rawText !== undefined) { Object.defineProperty(errForHook, 'rawText', { value: this.finalizationError.rawText, enumerable: true, }) } await this.middlewareRunner.runOnError(this.middlewareCtx, { error: errForHook, duration: Date.now() - this.streamStartTime, }) return } this.addTerminalAssistantMessages() await this.middlewareRunner.runOnFinish(this.middlewareCtx, { finishReason: this.lastFinishReason, duration: Date.now() - this.streamStartTime, content: this.accumulatedContent, usage: rebuildTokenUsage( this.finishedEvent?.usage, tanstackMetadata(this.finishedEvent ?? undefined)?.usage, ), }) } async *run(): AsyncGenerator { const steps = this.runSteps() for await (const chunk of steps) { let resumed = false try { yield chunk resumed = true } finally { // The consumer stopped iterating (`break` or `return()`). if (!resumed) { if ( chunk.type === EventType.RUN_ERROR || (chunk.type === EventType.RUN_FINISHED && chunk.outcome?.type === 'interrupt') ) { // A yielded error or a pause ends this invocation. Finish it // unseen so it reports `onError` or `onFinish`, as a drained run // does. A pause keeps its paused state. for await (const _chunk of steps) { // discard } } else { // Abort before the loop closes `runSteps`, so its `finally` // reports `onAbort`. this.middlewareAbortController?.abort() } } } } } private async *runSteps(): AsyncGenerator { this.beforeRun() this.logger.agentLoop('run started', { threadId: this.middlewareCtx.threadId, }) try { // Provision capabilities before any consumer (onConfig onward) can read them yield* this.runWhileYielding( this.middlewareRunner.runSetup(this.middlewareCtx), ) // Run initial onConfig (phase = init) this.middlewareCtx.phase = 'init' const initialConfig = this.buildMiddlewareConfig() const transformedConfig = yield* this.runWhileYielding( this.middlewareRunner.runOnConfig(this.middlewareCtx, initialConfig), ) this.applyMiddlewareConfig(transformedConfig) const durableResume = ( transformedConfig as { [DURABLE_RESUME]?: ( tools: ChatMiddlewareConfig['tools'], ) => Promise } )[DURABLE_RESUME] if (durableResume) { this.applyResumeToolState(await durableResume(this.tools)) } await this.applyEphemeralInterruptResume(transformedConfig) await this.applyDurableGenericInterruptResolution() // Run onStart (devtools middleware emits text:request:started and initial messages here) yield* this.runWhileYielding( this.middlewareRunner.runOnStart(this.middlewareCtx), ) if (this.earlyTermination) { yield* this.emitSuccessfulEarlyTermination() if (!this.terminalHookCalled) { this.terminalHookCalled = true await this.middlewareRunner.runOnFinish(this.middlewareCtx, { finishReason: this.lastFinishReason, duration: Date.now() - this.streamStartTime, content: this.accumulatedContent, usage: rebuildTokenUsage( this.finishedEvent?.usage, tanstackMetadata(this.finishedEvent ?? undefined)?.usage, ), }) } return } // A run stopped before it started runs no pending tools and raises no // interrupt. The `finally` below reports it through `onAbort`. if (this.isCancelled()) return const hasResumedTools = this.getPendingToolCallsFromMessages().length > 0 const pendingPhase = yield* this.checkForPendingToolCalls() if (pendingPhase === 'stop' || pendingPhase === 'wait') { await this.runTerminalHook() return } // The resumed tools are a tool phase too: middleware `onShouldContinue` // can end the run before the next model call. The loop strategy is not // asked here. const isStoppedAfterResume = hasResumedTools && !(yield* this.runWhileYielding( this.middlewareRunner.runOnShouldContinue( this.middlewareCtx, this.loopState(this.iterationCount), ), )) if (isStoppedAfterResume) { this.loopStopped = true this.markLoopStoppedMessage() if (!this.finalStructuredOutput) { this.loopStoppedFinishSent = true yield* this.emitSuccessfulEarlyTermination() } } // Skip the agent loop entirely when there are no tools AND a separate // structured-output finalization will run. Without tools the model has // nothing to do in the loop, so executing one iteration would burn an // extra provider call before the finalization request. // // Native combined mode does NOT skip — the agent loop itself produces // the schema-constrained final answer in one pass (model emits the // schema-constrained text on its natural final turn). Even with zero // tools, the single chatStream call IS the structured-output call. const skipAgentLoop = !!this.finalStructuredOutput && this.tools.length === 0 && this.finalStructuredOutput.nativeCombined !== true if (!skipAgentLoop && !isStoppedAfterResume) { do { if (this.earlyTermination) break if (this.isCancelled()) return this.logger.agentLoop(`iteration=${this.middlewareCtx.iteration}`, { iteration: this.middlewareCtx.iteration, }) yield* this.runWhileYielding(this.beginCycle()) if (this.cyclePhase === 'processText') { this.modelErrorRetries = 0 // A `ctx.retry()` in onModelError runs this again. do { this.retryModelCall = false // Run onConfig before each model call (phase = beforeModel) this.middlewareCtx.phase = 'beforeModel' this.middlewareCtx.iteration = this.iterationCount const iterConfig = this.buildMiddlewareConfig() const iterTransformedConfig = yield* this.runWhileYielding( this.middlewareRunner.runOnConfig( this.middlewareCtx, iterConfig, ), ) this.applyMiddlewareConfig(iterTransformedConfig) if ( yield* this.emitBoundaryInterrupts( 'beforeModel', this.createSyntheticFinishedEvent(), ) ) { this.setToolPhase('wait') return } yield* this.streamModelResponse() } while (this.retryModelCall && !this.isCancelled()) if (this.earlyTermination) break if ( yield* this.emitBoundaryInterrupts( 'afterModel', this.finishedEvent ?? this.createSyntheticFinishedEvent(), ) ) { this.setToolPhase('wait') return } if (this.shouldExecuteToolPhase()) { this.deferredToolCallRunFinishedChunks.push( ...this.deferredModelRunFinishedChunks, ) this.deferredModelRunFinishedChunks = [] } else if (!this.finalStructuredOutput?.nativeCombined) { yield* this.flushDeferredModelRunFinishedChunks() } } else { yield* this.processToolCalls() } this.endCycle() } while (yield* this.runWhileYielding(this.shouldContinue())) } this.logger.agentLoop('run finished', { finishReason: this.lastFinishReason, loopStopped: this.loopStopped, }) // The `tool_calls` RUN_FINISHED went out before the tool results. A // last one tells the client that the loop, not the model, ended the run. // A streamed finalization sends the outer RUN_FINISHED, so it carries // the flag instead. if ( this.loopStopped && !this.loopStoppedFinishSent && !this.isCancelled() ) { this.markLoopStoppedMessage() if (!this.finalizationOwnsLifecycle()) { yield* this.pipeThroughMiddleware( withTanstackMetadata(this.createSyntheticFinishedEvent(), { loopStopped: true, }), ) } } // After the agent loop ends, if a structured-output finalization was // requested AND the run hasn't already errored/aborted, run it through // the middleware pipeline. The terminal hook fires once at the very // end (after finalization), not after the agent loop. // Actionable waits already emitted a RUN_FINISHED interrupt terminal, so // do not run finalization after `processToolCalls()` pauses the stream. // // Native combined mode takes a different path: the agent loop's final- // turn text IS the schema-constrained JSON, so we harvest it from // `accumulatedContent` instead of issuing a second provider call. if ( this.finalStructuredOutput && this.toolPhase !== 'wait' && !this.isCancelled() && !this.finalizationError && !this.earlyTermination ) { if (this.finalStructuredOutput.nativeCombined === true) { yield* this.harvestCombinedStructuredOutput() if (!this.finalizationError && !this.isCancelled()) { yield* this.flushDeferredModelRunFinishedChunks() } } else { yield* this.runStructuredFinalization() } } // A client-tool or approval wait ends this server-side chat invocation. // Structured-output finalization stays paused until the caller submits // the result in a new invocation, but middleware must still observe one // terminal hook for the current invocation. await this.runTerminalHook() } catch (error: unknown) { if ( error instanceof Error && error.name === 'InterruptReplaySignal' && 'continuationRunId' in error && typeof error.continuationRunId === 'string' ) { this.terminalHookCalled = true yield* this.pipeThroughMiddleware({ type: EventType.RUN_FINISHED, timestamp: Date.now(), threadId: this.threadId, runId: this.runIdOverride ?? this.requestId, outcome: { type: 'success' }, result: { replayed: true, continuationRunId: error.continuationRunId, }, }) return } const interruptFailure = structuralInterruptFailure(error) if (interruptFailure) { this.terminalHookCalled = true this.logger.errors('chat interrupt resume failed', { error, threadId: this.middlewareCtx.threadId, }) await this.middlewareRunner.runOnError(this.middlewareCtx, { error: interruptFailure.error, duration: Date.now() - this.streamStartTime, }) yield this.buildInterruptRunErrorChunk(error) return } if (!this.terminalHookCalled) { this.terminalHookCalled = true if (error instanceof MiddlewareAbortError) { // Middleware abort decision — call onAbort, not onError this.abortReason = error.message await this.middlewareRunner.runOnAbort(this.middlewareCtx, { reason: error.message, duration: Date.now() - this.streamStartTime, cancelRequested: isCancelRequestedReason(error.message), }) } else { // Genuine error — call onError this.logger.errors('chat run failed', { error, threadId: this.middlewareCtx.threadId, }) await this.middlewareRunner.runOnError(this.middlewareCtx, { error, duration: Date.now() - this.streamStartTime, }) } } // Don't rethrow middleware abort errors — the run just stops gracefully if (!(error instanceof MiddlewareAbortError)) { throw error } } finally { // Check for abort terminal hook if (!this.terminalHookCalled && this.isCancelled()) { this.terminalHookCalled = true const reason = this.resolveAbortReason() await this.middlewareRunner.runOnAbort(this.middlewareCtx, { reason, duration: Date.now() - this.streamStartTime, cancelRequested: isCancelRequestedReason(reason), }) } // Await deferred promises (non-blocking side effects) if (this.deferredPromises.length > 0) { await Promise.allSettled(this.deferredPromises) } } } private beforeRun(): void { this.streamStartTime = Date.now() const { tools, metadata } = this.params // Gather flattened options into an object for context const options: Record = {} if (metadata !== undefined) options.metadata = metadata this.eventOptions = Object.keys(options).length > 0 ? options : undefined this.eventToolNames = tools?.map((t) => t.name) // Update middleware context with computed fields this.middlewareCtx.options = this.eventOptions this.middlewareCtx.toolNames = this.eventToolNames } private async beginCycle(): Promise { if (this.cyclePhase === 'processText') { await this.beginIteration() } } private endCycle(): void { if (this.cyclePhase === 'processText') { this.cyclePhase = 'executeToolCalls' return } this.cyclePhase = 'processText' this.iterationCount++ } private async beginIteration(): Promise { this.currentCallMetadata = { source: { provider: this.adapter.provider ?? this.adapter.name, api: this.adapter.api ?? this.adapter.kind, model: this.params.model, }, } this.middlewareCtx.callMetadata = this.currentCallMetadata this.currentMessageId = this.createId('msg') this.currentMessageCreatedAt = new Date() this.streamIdentityCaptured = false this.accumulatedContent = '' this.accumulatedThinking = [] this.turnParts = [] this.currentThinkingContent = '' this.currentThinkingSignature = '' this.currentThinkingRedacted = false this.finishedEvent = null this.streamedToolErrorResults.clear() // Update mutable context fields this.middlewareCtx.currentMessageId = this.currentMessageId this.middlewareCtx.accumulatedContent = '' // Notify middleware of new iteration (devtools emits assistant message:created here) await this.middlewareRunner.runOnIteration(this.middlewareCtx, { iteration: this.iterationCount, messageId: this.currentMessageId, }) } /** * Calls the model again after a rate-limit `RUN_ERROR`, as the `retry` * option allows. A call that yielded a chunk after `RUN_STARTED` is not * retried, so no output repeats. `RUN_STARTED` is held until the attempt is * kept, so the public start has the same `runId` as the `RUN_FINISHED` of * the kept attempt. When an abort ends the wait, the held error is yielded. * * Any other error before output goes to `onModelError`. When a middleware * calls `ctx.retry()`, this returns without the error, and the agent loop * runs `onConfig` and calls the model again. */ private async *retryRateLimited( call: () => AsyncIterable, ): AsyncGenerator { const retry = this.params.retry const hasModelErrorHook = this.middlewareRunner.hasModelErrorHook if (!retry && !hasModelErrorHook) { yield* call() return } const maxWaitMs = retry?.maxWaitMs ?? 60_000 if ( retry && (!Number.isInteger(retry.maxRetries) || retry.maxRetries < 0 || !(maxWaitMs >= 0)) ) { throw new TypeError( 'chat() retry: maxRetries must be an integer of 0 or more, and maxWaitMs must be 0 or more.', ) } let start: AdapterYieldChunk | undefined for (let attempt = 1; ; attempt++) { let streamed = false let waitMs: number | undefined let rateLimitError: AdapterYieldChunk | undefined for await (const chunk of call()) { if (chunk.type === EventType.RUN_ERROR && !streamed) { if ( retry && attempt <= retry.maxRetries && chunk.retryAfterMs !== undefined && chunk.retryAfterMs <= maxWaitMs ) { // Wait after the loop, so the adapter stream closes first. waitMs = chunk.retryAfterMs rateLimitError = chunk break } if (hasModelErrorHook && (await this.modelErrorRetried(chunk))) { // The dropped call can still be billed: report its usage. await this.runOnUsageFromChunk(chunk) return } } if (chunk.type === EventType.RUN_STARTED && !streamed) { start = chunk continue } if (start) yield start start = undefined streamed = true yield chunk } if (waitMs === undefined || !rateLimitError) break this.logger.warn( `activity=chat provider asked to wait, retry ${attempt} of ${retry?.maxRetries} in ${waitMs}ms`, { attempt, waitMs, model: this.params.model }, ) // Also wakes on a middleware `ctx.abort()`, not only the caller's. await waitOrAbort(waitMs, this.toolAbortSignal) if (this.isCancelled()) { this.retryAbandoned = true if (start) yield start yield rateLimitError return } // The dropped call can still be billed: report its usage. await this.runOnUsageFromChunk(rateLimitError) } if (start) yield start } /** * Runs `onModelError`. True when a middleware called `ctx.retry()` and the * model call has retries left. The hook also runs when none are left. */ private async modelErrorRetried(error: RunErrorEvent): Promise { if (this.isCancelled()) return false this.retryModelCall = false this.inModelErrorHook = true try { await this.middlewareRunner.runOnModelError(this.middlewareCtx, error) } finally { this.inModelErrorHook = false } this.retryModelCall &&= this.modelErrorRetries < MAX_MODEL_ERROR_RETRIES if (!this.retryModelCall) return false this.modelErrorRetries++ this.logger.warn( `activity=chat middleware asked to call the model again, retry ${this.modelErrorRetries} of ${MAX_MODEL_ERROR_RETRIES}`, { code: error.code, model: this.params.model }, ) return true } private async *streamModelResponse(): AsyncGenerator { const { metadata, modelOptions, reasoning } = this.params const tools = this.tools // Convert tool schemas to JSON Schema before passing to adapter const toolsWithJsonSchemas = tools.map((tool) => ({ ...tool, inputSchema: tool.inputSchema ? convertSchemaToJsonSchema(tool.inputSchema) : undefined, outputSchema: tool.outputSchema ? convertSchemaToJsonSchema(tool.outputSchema) : undefined, })) this.middlewareCtx.phase = 'modelStream' const providerName = (this.adapter as { provider?: string }).provider ?? this.adapter.name this.logger.request( `activity=chat provider=${providerName} model=${this.params.model} messages=${this.messages.length} tools=${this.tools.length} stream=true`, { provider: providerName, model: this.params.model, messageCount: this.messages.length, toolCount: this.tools.length, }, ) // When the adapter declared `supportsCombinedToolsAndSchema()`, the // activity layer set `nativeCombined: true` and we forward the // pre-converted JSON Schema into the regular chatStream call. The // adapter wires it into the upstream request (e.g. `response_format`, // `text.format`, `output_format`) so the model's final-turn text is // schema-constrained and the engine can harvest it from the agent loop // without a separate finalization round-trip. const combinedSchema = this.finalStructuredOutput?.nativeCombined === true ? this.finalStructuredOutput.jsonSchema : undefined const { approvals } = this.collectClientState() const adapterApprovals = new Map() for (const [approvalId, resolution] of approvals) { adapterApprovals.set( approvalId, typeof resolution === 'boolean' ? resolution : resolution.approved, ) } // Fail closed on `{ type: 'file' }` sources for adapters that haven't // declared support — an adapter written before the file arm existed would // otherwise fall through to its URL/data branch and silently mis-map the // reference. Checked per model call so tool results added mid-loop are // covered too. assertMessagesFileSourceSupport(this.adapter, this.messages) // Providers reject a tool choice on a request with no tools. const toolChoice = toolsWithJsonSchemas.length > 0 ? this.callToolChoice : undefined // Clean history for the request. The adapter knows its wire API, so it // does the source-sensitive part of replay. Plan on this same array: // a second replay must keep the length, so `before` indexes still match. const replayMessages = transformMessagesForReplay( this.providerMessages, ).messages // Mid-conversation changes, only for an adapter with a channel that is // on. Every other adapter gets today's request and no new field. const channels = this.adapter.midConversationChannels const midConversation = channels?.tools || channels?.systemPrompts ? planMidConversationChanges({ messages: replayMessages, toolNames: tools.map((tool) => tool.name), systemPrompts: normalizeSystemPrompts(this.systemPrompts).map( (prompt) => prompt.content, ), }) : undefined this.pendingMidConversationChange = midConversation?.record const streamOptions = { model: this.params.model, ...sanitizeProviderRequest(replayMessages, this.systemPrompts), tools: toolsWithJsonSchemas, metadata, request: this.effectiveRequest, modelOptions, ...(reasoning ? { reasoning } : {}), logger: this.logger, threadId: this.threadId, promptCache: this.params.promptCache, ...(midConversation ? { midConversationChanges: midConversation.changes } : {}), runId: this.runIdOverride, parentRunId: this.parentRunIdOverride, // Expose provided capabilities (e.g. sandbox) to harness adapters. capabilities: this.middlewareCtx, // Client approval decisions, for harness interactive-approval resolution. approvals: adapterApprovals, ...(toolChoice ? { toolChoice } : {}), ...(this.callWrapFetch ? { wrapFetch: this.callWrapFetch } : {}), ...(combinedSchema ? { outputSchema: combinedSchema } : {}), } for await (const adapterChunk of this.retryRateLimited(() => this.adapter.chatStream(streamOptions), )) { const raw = this.withCallMetadata(adapterChunk, this.currentCallMetadata) // An abandoned retry still sends its start and its rate-limit error. if (this.isCancelled() && !this.retryAbandoned) { break } this.totalChunkCount++ this.handleStreamChunk(raw) // Native combined mode: synthesize `structured-output.start` BEFORE // the first TEXT_MESSAGE_START so the client-side StreamProcessor // routes the schema-constrained JSON deltas into a // StructuredOutputPart. We delay synthesis until we actually see // text starting — intermediate tool-call iterations don't need it, // and emitting at run-start would wrap tool-call commentary into a // structured-output part too. if ( raw.type === EventType.CUSTOM && raw.name === 'structured-output.start' ) { this.combinedStartEmitted = true const startValue = raw.value if ( startValue && typeof startValue === 'object' && 'messageId' in startValue && typeof startValue.messageId === 'string' ) { this.combinedStructuredMessageId = startValue.messageId this.captureStructuredOutputMessageIdentity(startValue.messageId) } } let outboundChunk: AdapterYieldChunk = raw if ( this.finalStructuredOutput?.source === 'event' && raw.type === EventType.CUSTOM && raw.name === 'structured-output.complete' ) { const parsed = readStructuredOutputCompleteValue(raw.value) if (parsed) { const object = this.finalStructuredOutput.normalize ? this.finalStructuredOutput.normalize(parsed.object) : parsed.object this.structuredOutputResult = { data: object, rawText: parsed.raw } // A value that fails the schema is not sent. The harvest after the // loop checks it again and ends the run with RUN_ERROR. if (!this.passesStructuredCheck(object)) continue this.combinedCompleteEmitted = true const value = raw.value const completeMessageId = readCustomEventMessageId(value) if (completeMessageId) { this.combinedStructuredMessageId = completeMessageId this.captureStructuredOutputMessageIdentity(completeMessageId) } if (object !== parsed.object && value && typeof value === 'object') { outboundChunk = { ...raw, value: { ...value, object } } } } } if ( this.finalStructuredOutput?.nativeCombined === true && this.finalStructuredOutput.yieldChunks && this.finalStructuredOutput.source !== 'event' && !this.combinedStartEmitted && raw.type === EventType.TEXT_MESSAGE_START ) { this.combinedStartEmitted = true const messageId = typeof raw.messageId === 'string' && raw.messageId !== '' ? raw.messageId : generateMessageId() this.combinedStructuredMessageId = messageId const synthStart: StreamChunk = { type: EventType.CUSTOM, name: 'structured-output.start', value: { messageId }, timestamp: Date.now(), } const synthOutputs = await this.middlewareRunner.runOnChunk( this.middlewareCtx, synthStart, ) yield* this.emitPublicChunks(synthOutputs) } const outputChunks = await this.middlewareRunner.runOnChunk( this.middlewareCtx, outboundChunk, ) // A RUN_ERROR can carry the usage of a call the provider billed. Report // it before the yield: a consumer often stops reading at the error. if (raw.type === EventType.RUN_ERROR) { await this.runOnUsageFromChunk(raw) } // When a streaming structured-output finalization step will run after // the agent loop, suppress the agent-loop's RUN_STARTED/RUN_FINISHED // here — the finalization step emits the single outer lifecycle pair // that reaches the consumer. // // Native combined mode does NOT issue a second adapter stream — the // agent loop's lifecycle IS the outer pair the consumer sees. const suppressAgentLifecycle = this.finalizationOwnsLifecycle() for (const outputChunk of outputChunks) { this.recordPublicActivity(outputChunk, raw) for (const spec of normalizeStreamChunk( outputChunk as AdapterYieldChunk, )) { restorePublicUsage(spec) if ( suppressAgentLifecycle && (spec.type === EventType.RUN_STARTED || spec.type === EventType.RUN_FINISHED) ) { continue } if (spec.type === EventType.RUN_FINISHED) { this.deferredModelRunFinishedChunks.push(spec) continue } if (this.shouldDeferToolCallRunFinished(spec)) { this.deferredToolCallRunFinishedChunks.push(spec) continue } if (spec.type === EventType.RUN_STARTED) { if (this.hasPublicRunStarted) continue this.hasPublicRunStarted = true } // An adapter can fail before it sends `RUN_STARTED`. The public // stream still starts with one. if (spec.type === EventType.RUN_ERROR) { yield* this.emitSyntheticRunStarted( this.createSyntheticFinishedEvent(), ) } this.logger.output(`type=${spec.type}`, { chunk: spec }) yield spec this.middlewareCtx.chunkIndex++ } } if (raw.type === EventType.RUN_FINISHED) { await this.runOnUsageFromChunk(raw) } // Drain any sandbox.file events emitted while processing this chunk. yield* this.drainSandboxFileQueue() yield* this.drainMiddlewareCustomQueue() if (this.earlyTermination) { break } } // Drain any remaining sandbox.file events emitted after the stream ended. yield* this.drainSandboxFileQueue() yield* this.drainMiddlewareCustomQueue() } private handleStreamChunk(chunk: AdapterYieldChunk): void { // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check -- AG-UI EventType enum members vs string-literal case labels; default branch handles untraced events. switch (chunk.type) { // AG-UI Events case 'TEXT_MESSAGE_START': if (typeof chunk.messageId === 'string' && chunk.messageId !== '') { this.captureStreamMessageIdentity(chunk.messageId) } break case 'TEXT_MESSAGE_CONTENT': this.handleTextMessageContentEvent(chunk) break case 'TOOL_CALL_START': this.handleToolCallStartEvent(chunk) break case 'TOOL_CALL_ARGS': this.handleToolCallArgsEvent(chunk) break case 'TOOL_CALL_END': this.handleToolCallEndEvent(chunk) break case 'TOOL_CALL_RESULT': this.handleToolCallResultEvent(chunk) break case 'RUN_FINISHED': this.handleRunFinishedEvent(chunk) break case 'RUN_ERROR': this.handleRunErrorEvent(chunk) break case 'REASONING_MESSAGE_START': // A new reasoning message starts a new thinking step. this.finalizeCurrentThinkingStep() break case 'REASONING_MESSAGE_CONTENT': this.handleReasoningMessageContentEvent(chunk) break case 'REASONING_ENCRYPTED_VALUE': this.handleReasoningEncryptedValueEvent(chunk) break case 'REASONING_START': case 'REASONING_MESSAGE_END': case 'REASONING_END': // No special handling needed break case 'ACTIVITY_SNAPSHOT': this.setActivities( applyActivitySnapshotToRecords( this.activities, chunk as Extract, interleaveActivityRecords( modelMessagesToUIMessages(this.messages), this.activities, ).length, ), ) break case 'ACTIVITY_DELTA': this.setActivities( applyActivityDeltaToRecords( this.activities, chunk as Extract, ), ) break default: // RUN_STARTED, TEXT_MESSAGE_END, STATE_SNAPSHOT, STATE_DELTA, CUSTOM // - no special handling needed in chat activity break } } private setActivities(activities: Array): void { this.activities = activities this.middlewareCtx.activities = this.activities } /** * Apply an activity event that middleware put on the public stream. * `applied` is the adapter chunk `handleStreamChunk` already applied; a * pass-through or field-for-field copy of it is skipped so a delta lands * once. */ private recordPublicActivity( chunk: StreamChunk, applied?: AdapterYieldChunk, ): void { if ( chunk.type !== EventType.ACTIVITY_SNAPSHOT && chunk.type !== EventType.ACTIVITY_DELTA ) { return } if ( applied && (chunk === applied || JSON.stringify(chunk) === JSON.stringify(applied)) ) { return } this.handleStreamChunk(chunk as AdapterYieldChunk) } /** * Stamp the source, response identity, and stop reason of this model call * on the chunk, and remember them in `metadata` for the assistant messages * that the call produces. */ private withCallMetadata( chunk: AdapterYieldChunk, metadata: TanStackMessageMetadata, ) { if ('subagentRunId' in chunk && typeof chunk.subagentRunId === 'string') return chunk // Activity records keep their own metadata. The call metadata is for the // assistant message. if ( chunk.type === EventType.ACTIVITY_SNAPSHOT || chunk.type === EventType.ACTIVITY_DELTA ) return chunk const incoming = tanstackMetadata(chunk) if (incoming?.source !== undefined) metadata.source = incoming.source if (incoming?.stopReason !== undefined) metadata.stopReason = incoming.stopReason if (chunk.type === EventType.RUN_FINISHED) { const model = chunk.model ?? incoming?.model const responseId = chunk.responseId ?? incoming?.responseId const finishReason = chunk.finishReason ?? incoming?.finishReason if (model !== undefined) metadata.model = model if (responseId !== undefined) metadata.responseId = responseId if (finishReason) metadata.finishReason = finishReason if (incoming?.responseItems !== undefined) metadata.responseItems = incoming.responseItems if (incoming?.reasoningItem !== undefined) metadata.reasoningItem = incoming.reasoningItem } if (chunk.type === EventType.RUN_ERROR) { metadata.stopReason ??= 'error' } const merged = withTanstackMetadata(chunk, { ...metadata, ...(incoming ?? {}), ...(metadata.source !== undefined ? { source: metadata.source } : {}), ...(metadata.stopReason !== undefined ? { stopReason: metadata.stopReason } : {}), }) return { ...chunk, metadata: merged.metadata } } // =========================== // AG-UI Event Handlers // =========================== private handleTextMessageContentEvent(chunk: TextMessageContentEvent): void { const extra = chunk as AdapterYieldChunk // Adapters still emit leftover cumulative `content` on RAW yields. // Alignment suppresses already-delivered deltas, so this snapshot is // what a takeover saves as the full assistant text. const before = this.accumulatedContent let delta: string if (typeof extra.content === 'string' && extra.content !== '') { const next = extra.content this.accumulatedContent = next // `startsWith(before)` flattens the whole rope on every chunk, so a // long answer of small deltas is O(n²) and does not yield. A normal // snapshot is `before` plus this delta; the lengths say so without // reading the text. ponytail: length check. A same-length prefix // rewrite falls out later, when turn text disagrees with // `accumulatedContent` and block order is dropped. if (next.length === before.length + chunk.delta.length) { delta = chunk.delta } else if (!this.turnParts || !next.startsWith(before)) { // A cumulative `content` snapshot rewrote earlier text; order unknown. this.turnParts = null delta = '' } else { delta = next.slice(before.length) } } else { this.accumulatedContent += chunk.delta delta = chunk.delta } this.middlewareCtx.accumulatedContent = this.accumulatedContent if (!this.turnParts || delta === '') return const last = this.turnParts[this.turnParts.length - 1] if (last && last.type === 'text') { last.content += delta } else { this.turnParts.push({ type: 'text', content: delta }) } } private captureStreamMessageIdentity(messageId: string): void { this.currentMessageId = messageId this.middlewareCtx.currentMessageId = messageId if (!this.streamIdentityCaptured) { this.currentMessageCreatedAt = new Date() this.streamIdentityCaptured = true } } private captureStructuredOutputMessageIdentity(messageId: string): void { this.structuredOutputMessageId = messageId this.structuredOutputMessageCreatedAt ??= new Date() } private handleToolCallStartEvent(chunk: ToolCallStartEvent): void { if ( typeof chunk.parentMessageId === 'string' && chunk.parentMessageId !== '' ) { this.captureStreamMessageIdentity(chunk.parentMessageId) } this.toolCallManager.addToolCallStartEvent(chunk) if ( this.turnParts && !this.turnParts.some( (part) => part.type === 'call' && part.id === chunk.toolCallId, ) ) { this.turnParts.push({ type: 'call', id: chunk.toolCallId, providerExecuted: isProviderExecutedToolCall({ metadata: chunk.metadata, }), }) } const metadata = chunk.metadata const thoughtSignature = metadata != null && typeof metadata === 'object' && 'thoughtSignature' in metadata && typeof metadata.thoughtSignature === 'string' && metadata.thoughtSignature !== '' ? metadata.thoughtSignature : undefined if (thoughtSignature === undefined) return const call = this.toolCallManager .getToolCalls() .find((candidate) => candidate.id === chunk.toolCallId) if (!call) return call.metadata = { ...(call.metadata != null && typeof call.metadata === 'object' ? call.metadata : {}), thoughtSignature, } } private handleToolCallArgsEvent(chunk: ToolCallArgsEvent): void { this.toolCallManager.addToolCallArgsEvent(chunk) } private handleToolCallEndEvent(chunk: ToolCallEndEvent): void { const final = this.toolCallManager.completeToolCall(chunk) const end = chunk as AdapterYieldChunk if (final) { // The client stores the same argument string as the server history. // The wire carries only `args`; `input` is parsed back from it. end.args = final.args end.input = final.input const metadata = tanstackMetadata(end) if (metadata) { delete metadata.args delete metadata.input } } const state = end.state ?? tanstackMetadata(end)?.state if (state !== 'output-error' || end.result === undefined) return this.handleToolCallResultEvent({ type: EventType.TOOL_CALL_RESULT, toolCallId: chunk.toolCallId, content: Array.isArray(end.result) ? JSON.stringify(end.result) : end.result, messageId: chunk.toolCallId, metadata: { tanstack: { state: 'output-error' } }, }) } private handleToolCallResultEvent(chunk: ToolCallResultEvent): void { const isOutputError = tanstackMetadata(chunk)?.state === 'output-error' if (!isOutputError) return const toolCall = this.toolCallManager .getToolCalls() .find((candidate) => candidate.id === chunk.toolCallId) if (!toolCall) return // Adapter output-error content is a wire string. Parse { error: string } // JSON so it is not text-marked; live StreamProcessor then shows the // same error text as a reload. const recorded = typeof chunk.content === 'string' ? parseToolOutput(chunk.content, chunk.metadata) : chunk.content this.streamedToolErrorResults.set(chunk.toolCallId, { toolCallId: chunk.toolCallId, toolName: toolCall.function.name, result: typeof recorded === 'object' && recorded !== null && 'error' in recorded && typeof recorded.error === 'string' ? recorded : chunk.content, state: 'output-error', }) } private handleRunFinishedEvent(chunk: AdapterYieldChunk): void { this.finishedEvent = chunk as RunFinishedEvent const raw = chunk const top = raw.finishReason this.lastFinishReason = top === 'stop' || top === 'length' || top === 'content_filter' || top === 'tool_calls' || top === null ? top : (tanstackMetadata(chunk)?.finishReason ?? null) } /** * On a failed call, a throwing `onUsage` is logged, so the call's own error * still reaches the consumer. */ private async runOnUsageFromChunk( chunk: RunFinishedEvent | AdapterYieldChunk, failed = chunk.type === EventType.RUN_ERROR, ): Promise { const rebuilt = rebuildTokenUsage( chunk.usage, tanstackMetadata(chunk)?.usage, ) if (!rebuilt) return if (!failed) { await this.middlewareRunner.runOnUsage(this.middlewareCtx, rebuilt) return } try { await this.middlewareRunner.runOnUsage(this.middlewareCtx, rebuilt) } catch (error) { this.logger.errors('onUsage middleware threw for a failed call', { error, }) } } private handleRunErrorEvent( chunk: Extract, ): void { this.earlyTermination = true if (this.finalizationError === null) { const message = chunk.message || 'Run failed' this.finalizationError = { message, ...(chunk.code !== undefined ? { code: chunk.code } : {}), } } } private finalizeCurrentThinkingStep(): void { if (this.currentThinkingContent || this.currentThinkingSignature) { this.accumulatedThinking.push({ content: this.currentThinkingContent, ...(this.currentThinkingSignature && { signature: this.currentThinkingSignature, }), ...(this.currentThinkingRedacted && { redacted: true }), }) if (this.turnParts) { const placeholder = [...this.turnParts] .reverse() .find( (part): part is Extract => part.type === 'thinking' && part.index === -1, ) const index = this.accumulatedThinking.length - 1 if (placeholder) { placeholder.index = index } else { this.turnParts.push({ type: 'thinking', index }) } } this.currentThinkingContent = '' this.currentThinkingSignature = '' this.currentThinkingRedacted = false } } /** * Record where the current thinking step sits among this turn's parts. A * step is finalized only when the next step starts (or the turn ends), by * which time later tool calls have already arrived, so the position has to * be noted when the step's first content or signature shows up. */ private noteThinkingStepPosition(): void { if ( this.turnParts && this.currentThinkingContent === '' && this.currentThinkingSignature === '' ) { this.turnParts.push({ type: 'thinking', index: -1 }) } } private handleReasoningMessageContentEvent( chunk: Extract, ): void { this.noteThinkingStepPosition() this.currentThinkingContent += chunk.delta } private handleReasoningEncryptedValueEvent( chunk: ReasoningEncryptedValueEvent, ): void { if (chunk.subtype === 'tool-call') { const call = this.messages .flatMap((message) => message.toolCalls ?? []) .find((toolCall) => toolCall.id === chunk.entityId) if (call) { call.metadata = { ...(call.metadata != null && typeof call.metadata === 'object' ? call.metadata : {}), thoughtSignature: chunk.encryptedValue, } } return } this.noteThinkingStepPosition() this.currentThinkingSignature = chunk.encryptedValue this.currentThinkingRedacted = isRedactedThinkingId(chunk.entityId) } /** * Tools available for execution this turn. The discovery tool is dropped * from the advertised set (`this.tools`) once every lazy tool is discovered, * but a model may still re-request discovery; this widens execution lookup * to include it so such calls don't fail with "Unknown tool". Centralised so * both execution sites (`processToolCalls` and `checkForPendingToolCalls`) * stay in sync. */ private resolveExecutableTools( toolCalls: ReadonlyArray, ): ReadonlyArray { return this.lazyToolManager.getExecutableTools( this.tools, toolCalls.map((tc) => tc.function.name), ) } private async *checkForPendingToolCalls(): AsyncGenerator< StreamChunk, ToolPhaseResult, void > { const pendingToolCalls = this.getPendingToolCallsFromMessages() if (pendingToolCalls.length === 0) { return 'continue' } const finishEvent = this.createSyntheticFinishedEvent() // Count is deduped so wait→resume after a live turn does not double-count. // Per-turn execution caps are app middleware via onBeforeToolCall skip. this.recordToolCalls(pendingToolCalls) // Handle undiscovered lazy tool calls with self-correcting error messages const undiscoveredLazyResults: Array = [] const executablePendingCalls = pendingToolCalls.filter((tc) => { if (this.lazyToolManager.isUndiscoveredLazyTool(tc.function.name)) { undiscoveredLazyResults.push({ toolCallId: tc.id, toolName: tc.function.name, result: { error: this.lazyToolManager.getUndiscoveredToolError( tc.function.name, ), }, state: 'output-error', }) return false } return true }) // Non-executed outcomes (undiscovered lazy). Emitted after executed // results so the stream prefers real results first. Per-turn skips are // produced by middleware via onBeforeToolCall and appear in execution results. const deferredErrorResults = [...undiscoveredLazyResults] // Build args lookup so buildToolResultChunks can emit TOOL_CALL_START + // TOOL_CALL_ARGS before TOOL_CALL_END during continuation re-executions. const argsMap = new Map() for (const tc of pendingToolCalls) { argsMap.set(tc.id, tc.function.arguments) } if (executablePendingCalls.length === 0) { if (deferredErrorResults.length > 0) { for (const chunk of this.buildToolResultChunks( deferredErrorResults, finishEvent, argsMap, )) { yield* this.pipeThroughMiddleware(chunk) } } return 'continue' } this.middlewareCtx.phase = 'beforeTools' if ( yield* this.emitBoundaryInterrupts( 'beforeTools', finishEvent, executablePendingCalls, ) ) { this.setToolPhase('wait') return 'wait' } const { approvals, clientToolResults } = this.collectClientState() const generator = executeToolCalls( executablePendingCalls, this.resolveExecutableTools(executablePendingCalls), this.threadId, approvals, clientToolResults, (eventName, data, options) => this.createCustomEventChunk(eventName, data, options), this.toolMiddlewareHooks(), this.middlewareCtx.context, this.toolAbortSignal, this.toolResumeState(), this.params.toolExecution, this.params.repairToolInput, this.toolCapabilities(), ) // Consume the async generator, yielding custom events and collecting the return value const rawEdits = this.captureApprovedArgumentEdits(pendingToolCalls) const executionResult = yield* this.drainToolCallGenerator(generator) this.retainApprovedArgumentEdits(executionResult, rawEdits) // Check if middleware aborted during pending tool execution if (this.isMiddlewareAborted()) { this.setToolPhase('stop') return 'stop' } const allResults = [...executionResult.results, ...deferredErrorResults] // Notify middleware of tool phase completion (devtools emits aggregate events here) yield* this.runWhileYielding( this.middlewareRunner.runOnToolPhaseComplete(this.middlewareCtx, { toolCalls: pendingToolCalls, results: allResults, needsApproval: executionResult.needsApproval, needsClientExecution: executionResult.needsClientExecution, }), ) const pauseForDecision = executionResult.needsApproval.length > 0 || executionResult.needsClientExecution.length > 0 || executionResult.inputRequired.length > 0 || executionResult.subagentInterrupts.length > 0 if (pauseForDecision) { this.discardDeferredToolCallRunFinishedChunks() if (allResults.length > 0) { for (const chunk of this.buildToolResultChunks( allResults, finishEvent, )) { yield* this.pipeThroughMiddleware(chunk) } } const emitted = yield* this.emitActionableInterruptBoundary( finishEvent, executionResult.needsApproval, executionResult.needsClientExecution, [], executionResult.inputRequired, executionResult.subagentInterrupts, ) this.setToolPhase(emitted ? 'wait' : 'stop') return emitted ? 'wait' : 'stop' } const toolResultChunks = this.buildToolResultChunks(allResults, finishEvent) for (const chunk of toolResultChunks) { yield* this.pipeThroughMiddleware(chunk) } return 'continue' } private async *processToolCalls(): AsyncGenerator { if (!this.shouldExecuteToolPhase()) { // Text-only turn — clear per-turn count so strategies see 0 tools. this.lastTurnToolCallCount = 0 this.setToolPhase('stop') return } const toolCalls = this.toolCallManager.getToolCalls() const finishEvent = this.finishedEvent if (!finishEvent || toolCalls.length === 0) { this.lastTurnToolCallCount = 0 this.setToolPhase('stop') return } // Count every model-emitted tool call. Per-turn execution caps are app // middleware via onBeforeToolCall skip. this.recordToolCalls(toolCalls) this.addAssistantToolCallMessage(toolCalls) // The output limit cut this answer. Each call that the provider did not // run has its error result now (closeTruncatedToolCalls). No call runs. if (this.lastFinishReason === 'length') { const results: Array = [] for (const call of toolCalls) { const stored = this.messages.find( (message) => message.role === 'tool' && message.toolCallId === call.id, ) if (!stored) continue // onAfterToolCall can replace the text. The code tells this error // apart from a failed run. const decision = yield* this.runWhileYielding( this.middlewareRunner.runOnAfterToolCall(this.middlewareCtx, { toolCall: call, tool: this.tools.find((tool) => tool.name === call.function.name), toolName: call.function.name, toolCallId: call.id, ok: false, duration: 0, error: Object.assign(new Error(TRUNCATED_TOOL_RESULT), { code: 'max_tokens', }), }), ) results.push({ toolCallId: call.id, toolName: call.function.name, result: decision ? decision.result : stored.content, state: 'output-error', }) } // This also stores the results, so the loop decision reads them. const resultChunks = this.buildToolResultChunks( results, finishEvent, undefined, true, ) // Ask the strategy and middleware now, with the state that // shouldContinue() gives them after this cycle. shouldContinue() then // uses this answer. The RUN_FINISHED that the client sees depends on it. const continues = yield* this.runWhileYielding( this.loopContinues(this.iterationCount + 1), ) this.cutAnswerContinues = continues if (continues) { // A client reads it as a tool turn, so it waits for the next call. // The chunks are already public, so the finish reason is in the // metadata. this.deferredToolCallRunFinishedChunks = this.deferredToolCallRunFinishedChunks.map((chunk) => chunk.type === EventType.RUN_FINISHED ? withTanstackMetadata(chunk, { finishReason: 'tool_calls' }) : chunk, ) yield* this.flushDeferredToolCallRunFinishedChunks() } for (const chunk of resultChunks) { yield* this.pipeThroughMiddleware(chunk) } // A stopped run ends on the `length` RUN_FINISHED, after the results. // Native combined structured output sends it after its harvest, and // drops it when the harvest fails. if (!continues) { this.loopStopped = true this.markLoopStoppedMessage() this.deferredToolCallRunFinishedChunks = this.deferredToolCallRunFinishedChunks.map((chunk) => chunk.type === EventType.RUN_FINISHED ? withTanstackMetadata(chunk, { loopStopped: true }) : chunk, ) } if (!continues && this.finalStructuredOutput?.nativeCombined) { this.loopStoppedFinishSent = true this.deferredModelRunFinishedChunks.push( ...this.deferredToolCallRunFinishedChunks, ) this.deferredToolCallRunFinishedChunks = [] } else if (!continues) { this.loopStoppedFinishSent = true yield* this.flushDeferredToolCallRunFinishedChunks() } this.toolCallManager.clear() this.setToolPhase(continues ? 'continue' : 'stop') return } // Handle undiscovered lazy tool calls with self-correcting error messages const undiscoveredLazyResults: Array = [] const executableToolCalls = toolCalls.filter((tc) => { if (this.streamedToolErrorResults.has(tc.id)) { return false } if (this.lazyToolManager.isUndiscoveredLazyTool(tc.function.name)) { undiscoveredLazyResults.push({ toolCallId: tc.id, toolName: tc.function.name, result: { error: this.lazyToolManager.getUndiscoveredToolError( tc.function.name, ), }, state: 'output-error', }) return false } return true }) // Non-executed outcomes. Per-turn skips come from middleware and appear in // execution results. const deferredErrorResults = [ ...this.streamedToolErrorResults.values(), ...undiscoveredLazyResults, ] if (executableToolCalls.length === 0) { yield* this.flushDeferredToolCallRunFinishedChunks() // All tool calls already have error results — emit them, then continue // the loop (strategy / onShouldContinue may stop). if (deferredErrorResults.length > 0) { for (const chunk of this.buildToolResultChunks( deferredErrorResults, finishEvent, )) { yield* this.pipeThroughMiddleware(chunk) } } this.toolCallManager.clear() this.setToolPhase('continue') return } this.middlewareCtx.phase = 'beforeTools' if ( yield* this.emitBoundaryInterrupts( 'beforeTools', finishEvent, executableToolCalls, ) ) { this.setToolPhase('wait') return } const { approvals, clientToolResults } = this.collectClientState() const generator = executeToolCalls( executableToolCalls, this.resolveExecutableTools(executableToolCalls), this.threadId, approvals, clientToolResults, (eventName, data, options) => this.createCustomEventChunk(eventName, data, options), this.toolMiddlewareHooks(), this.middlewareCtx.context, this.toolAbortSignal, this.toolResumeState(), this.params.toolExecution, this.params.repairToolInput, this.toolCapabilities(), ) // Consume the async generator, yielding custom events and collecting the return value const rawEdits = this.captureApprovedArgumentEdits(toolCalls) const executionResult = yield* this.drainToolCallGenerator(generator) this.retainApprovedArgumentEdits(executionResult, rawEdits) this.middlewareCtx.phase = 'afterTools' // Check if middleware aborted during tool execution if (this.isMiddlewareAborted()) { this.setToolPhase('stop') return } // Executed results first, then deferred errors (fan-out skips / undiscovered) const allResults = [...executionResult.results, ...deferredErrorResults] // Notify middleware of tool phase completion (devtools emits aggregate events here) yield* this.runWhileYielding( this.middlewareRunner.runOnToolPhaseComplete(this.middlewareCtx, { toolCalls, results: allResults, needsApproval: executionResult.needsApproval, needsClientExecution: executionResult.needsClientExecution, }), ) const afterToolBoundaryChunks = this.buildToolResultChunks( allResults, finishEvent, ) const afterToolRequests = yield* this.runWhileYielding( this.middlewareRunner.runOnInterruptBoundary( this.middlewareCtx as ChatMiddlewareContext & { phase: 'afterTools' }, ), ) if (afterToolRequests.length > 0) { for (const chunk of afterToolBoundaryChunks) { yield* this.pipeThroughMiddleware(chunk) } yield* this.emitBoundaryInterrupts( 'afterTools', finishEvent, toolCalls, afterToolRequests, // Its results already went out with the chunks above. { ...executionResult, results: [] }, ) this.setToolPhase('wait') return } const pauseForDecision = executionResult.needsApproval.length > 0 || executionResult.needsClientExecution.length > 0 || executionResult.inputRequired.length > 0 || executionResult.subagentInterrupts.length > 0 if (pauseForDecision) { if (allResults.length > 0) { for (const chunk of afterToolBoundaryChunks) { yield* this.pipeThroughMiddleware(chunk) } } const emitted = yield* this.emitActionableInterruptBoundary( finishEvent, executionResult.needsApproval, executionResult.needsClientExecution, [], executionResult.inputRequired, executionResult.subagentInterrupts, ) this.setToolPhase(emitted ? 'wait' : 'stop') return } yield* this.flushDeferredToolCallRunFinishedChunks() const toolResultChunks = afterToolBoundaryChunks for (const chunk of toolResultChunks) { yield* this.pipeThroughMiddleware(chunk) } // Refresh tools if lazy tools were discovered in this batch if (this.lazyToolManager.hasNewlyDiscoveredTools()) { this.tools = this.lazyToolManager.getActiveTools() this.toolCallManager = new ToolCallManager< ReadonlyArray, TContext >(this.tools) this.setToolPhase('continue') return } this.toolCallManager.clear() this.setToolPhase('continue') } private shouldDeferToolCallRunFinished(chunk: StreamChunk): boolean { return ( chunk.type === EventType.RUN_FINISHED && this.lastFinishReason === 'tool_calls' && this.tools.length > 0 && this.toolCallManager.hasToolCalls() ) } private *flushDeferredToolCallRunFinishedChunks(): Generator { for (const chunk of this.deferredToolCallRunFinishedChunks) { this.logger.output(`type=${chunk.type}`, { chunk }) yield chunk this.middlewareCtx.chunkIndex++ } this.deferredToolCallRunFinishedChunks = [] } private *flushDeferredModelRunFinishedChunks(): Generator { for (const chunk of this.deferredModelRunFinishedChunks) { this.logger.output(`type=${chunk.type}`, { chunk }) yield chunk this.middlewareCtx.chunkIndex++ } this.deferredModelRunFinishedChunks = [] } private async *emitSyntheticRunStarted( finishEvent: RunFinishedEvent, ): AsyncGenerator { if (this.hasPublicRunStarted) return yield* this.pipeThroughMiddleware({ type: EventType.RUN_STARTED, runId: finishEvent.runId, threadId: finishEvent.threadId, ...(this.parentRunIdOverride !== undefined && { parentRunId: this.parentRunIdOverride, }), timestamp: Date.now(), }) } private async *emitSuccessfulEarlyTermination(): AsyncGenerator< StreamChunk, void, void > { // `stop` is a finished run, not another tool cycle. `tool_calls` here // makes the client auto-send after afterTools, so reject looks stuck. this.lastFinishReason = 'stop' const finishEvent = this.createSyntheticFinishedEvent('stop') yield* this.emitSyntheticRunStarted(finishEvent) const finished = { ...finishEvent, timestamp: Date.now(), outcome: { type: 'success' as const }, } yield* this.pipeThroughMiddleware( this.loopStopped ? withTanstackMetadata(finished, { loopStopped: true }) : finished, ) } private discardDeferredToolCallRunFinishedChunks(): void { this.deferredToolCallRunFinishedChunks = [] } private shouldExecuteToolPhase(): boolean { return ( (this.lastFinishReason === 'tool_calls' || (this.lastFinishReason === 'length' && // Provider-executed calls have their results. With no other call, // the cut answer ends the run like a text answer. this.toolCallManager .getToolCalls() .some((call) => !isProviderExecutedToolCall(call)))) && this.tools.length > 0 && this.toolCallManager.hasToolCalls() ) } /** * Split this iteration into assistant ModelMessages that keep the provider's * block order: a new segment starts at every thinking step that follows a * provider-executed tool call (the rule buildAssistantMessages applies to * UIMessages). Segments after the first get `${id}-segment-${n}` ids. A * segment whose own blocks leave the default order gets a `blockOrder` map. * Returns null when no split is needed or the order could not be tracked, * so callers fall back to the single-message shape. */ private buildOrderedAssistantSegments( toolCalls: ReadonlyArray, id: string | undefined, createdAt: Date | undefined, ): Array | null { const parts = this.turnParts if (!parts) return null const providerCallIds = new Set( parts.flatMap((part) => part.type === 'call' && part.providerExecuted ? [part.id] : [], ), ) type Segment = { thinking: NonNullable text: string callIds: Array parts: Array } let current: Segment = { thinking: [], text: '', callIds: [], parts: [] } const segments: Array = [current] let split = false for (const part of parts) { if (part.type === 'thinking') { const thinking = this.accumulatedThinking[part.index] if (!thinking) return null if (current.callIds.some((callId) => providerCallIds.has(callId))) { current = { thinking: [thinking], text: '', callIds: [], parts: [] } segments.push(current) split = true } else { current.thinking.push(thinking) } } else if (part.type === 'text') { current.text += part.content } else { current.callIds.push(part.id) } current.parts.push(part) } if (!split) return null if ( segments.map((segment) => segment.text).join('') !== this.accumulatedContent ) { return null } if ( segments.reduce((n, segment) => n + segment.thinking.length, 0) !== this.accumulatedThinking.length ) { return null } const placed = new Set(segments.flatMap((segment) => segment.callIds)) for (const toolCall of toolCalls) { if (!placed.has(toolCall.id)) current.callIds.push(toolCall.id) } return segments.map((segment, index) => { const segmentCalls = toolCalls.filter((toolCall) => segment.callIds.includes(toolCall.id), ) const blockOrder = turnBlockOrder(segment.parts, segmentCalls) return { role: 'assistant', content: segment.text || null, metadata: { tanstack: { ...this.currentCallMetadata } }, ...(segmentCalls.length > 0 && { toolCalls: segmentCalls }), id: id === undefined ? undefined : index === 0 ? id : `${id}-segment-${index}`, createdAt, ...(segment.thinking.length > 0 && { thinking: segment.thinking }), ...(blockOrder && { blockOrder }), } }) } /** * `{ blockOrder }` for this iteration kept as one assistant message that * carries `toolCalls`, or `{}` when the order is the default one or was not * tracked. This is the fallback when `buildOrderedAssistantSegments` does * not split, so it is the common client-tool case. */ private singleMessageBlockOrder(toolCalls: ReadonlyArray): { blockOrder?: Array } { const parts = this.turnParts if (!parts) return {} const thinking = parts.filter( (part): part is Extract => part.type === 'thinking', ) const text = parts .map((part) => (part.type === 'text' ? part.content : '')) .join('') if ( text !== this.accumulatedContent || thinking.length !== this.accumulatedThinking.length || thinking.some((part, index) => part.index !== index) ) { return {} } const blockOrder = turnBlockOrder(parts, toolCalls) return blockOrder ? { blockOrder } : {} } private addAssistantToolCallMessage(toolCalls: Array): void { this.finalizeCurrentThinkingStep() const from = this.messages.length const segments = this.buildOrderedAssistantSegments( toolCalls, this.currentMessageId ?? undefined, this.currentMessageCreatedAt ?? undefined, ) this.messages = [ ...this.messages, ...(segments ?? [ { role: 'assistant' as const, content: this.accumulatedContent || null, metadata: { tanstack: { ...this.currentCallMetadata } }, toolCalls, id: this.currentMessageId ?? undefined, createdAt: this.currentMessageCreatedAt ?? undefined, ...(this.accumulatedThinking.length > 0 && { thinking: this.accumulatedThinking, }), ...this.singleMessageBlockOrder(toolCalls), }, ]), ] this.closeTruncatedToolCalls(from) this.saveMidConversationChange(from) this.middlewareCtx.messages = this.messages } /** * Give each call of the assistant messages from index `from` an error result * when the output limit cut their answer. Such a call is not complete, so it * never runs and asks for nothing. A provider-executed call has its result. */ private closeTruncatedToolCalls(from: number): void { const cut = this.messages .slice(from) .flatMap((message) => tanstackMetadata(message)?.finishReason === 'length' ? (message.toolCalls ?? []).filter( (call) => !isProviderExecutedToolCall(call), ) : [], ) if (cut.length === 0) return this.messages = [ ...this.messages, ...cut.map( (call): ModelMessage => ({ role: 'tool', toolCallId: call.id, content: TRUNCATED_TOOL_RESULT, error: TRUNCATED_TOOL_RESULT, }), ), ] } private addTerminalAssistantMessages(): void { this.finalizeCurrentThinkingStep() const structuredResult = this.structuredOutputResult const raw = structuredResult ? structuredResult.rawText || safeJsonStringify(structuredResult.data) : '' const structuredOutput: StructuredOutputPart | undefined = structuredResult ? { type: 'structured-output', status: 'complete', data: structuredResult.data, partial: structuredResult.data, raw, ...(structuredResult.reasoning !== undefined ? { reasoning: structuredResult.reasoning } : {}), } : undefined const nativeCombined = this.finalStructuredOutput?.nativeCombined === true const eventSourced = this.finalStructuredOutput?.source === 'event' const structuredId = this.structuredOutputMessageId ?? this.combinedStructuredMessageId ?? this.currentMessageId ?? this.createId('msg') // Codex, OpenCode, ACP, and grok-build reuse the last text messageId // on structured-output.complete. Split only when the event uses a // different id (Claude Code). Same-id output stays on one message. const splitStructuredMessage = Boolean(structuredOutput) && (!nativeCombined || eventSourced) && this.currentMessageId != null && structuredId !== this.currentMessageId const messages = [...this.middlewareCtx.messages] const existingStructuredIndex = messages.findIndex( (message) => message.role === 'assistant' && message.id === structuredId, ) const currentTurnAlreadyRecorded = messages.some( (message) => message.role === 'assistant' && message.id === this.currentMessageId, ) const thinking = this.accumulatedThinking.length > 0 ? this.accumulatedThinking : undefined const startedLength = messages.length if (structuredOutput && existingStructuredIndex >= 0) { const existing = messages[existingStructuredIndex] if (existing) { messages[existingStructuredIndex] = { ...withTanstackMetadata( existing, nativeCombined ? this.currentCallMetadata : this.structuredCallMetadata, ), content: raw || existing.content, structuredOutput, } } } else if (structuredOutput && !splitStructuredMessage) { if (!currentTurnAlreadyRecorded) { messages.push({ role: 'assistant', content: this.accumulatedContent || raw || null, metadata: { tanstack: { ...(nativeCombined ? this.currentCallMetadata : this.structuredCallMetadata), }, }, id: structuredId, createdAt: this.currentMessageCreatedAt ?? this.structuredOutputMessageCreatedAt ?? new Date(), structuredOutput, ...(thinking ? { thinking } : {}), }) } } else { if ( !currentTurnAlreadyRecorded && (this.accumulatedContent !== '' || thinking) ) { const id = this.currentMessageId ?? this.createId('msg') const createdAt = this.currentMessageCreatedAt ?? new Date() messages.push( ...(this.buildOrderedAssistantSegments( this.toolCallManager.getToolCalls(), id, createdAt, ) ?? [ { role: 'assistant', content: this.accumulatedContent || null, metadata: { tanstack: { ...this.currentCallMetadata } }, id, createdAt, ...(thinking ? { thinking } : {}), // This message carries no tool calls, so its map has none. ...this.singleMessageBlockOrder([]), }, ]), ) } if (structuredOutput) { messages.push({ role: 'assistant', content: raw || null, metadata: { tanstack: { ...this.structuredCallMetadata } }, id: structuredId, createdAt: this.structuredOutputMessageCreatedAt ?? new Date(), structuredOutput, }) } } if (messages.length === startedLength && existingStructuredIndex < 0) { return } this.messages = messages this.closeTruncatedToolCalls(startedLength) // An in-place update does not grow the array. The assistant message is // already at existingStructuredIndex, so a search from the old length // misses it and leaves the record pending. this.saveMidConversationChange( messages.length === startedLength ? existingStructuredIndex : startedLength, ) if (this.loopStopped) this.markLoopStoppedMessage() this.middlewareCtx.messages = this.messages } /** * Save the pending mid-conversation record on the first assistant message * at index `from` or later. The record is a field of the message, so it * goes wherever the transcript goes: a message store, a restart. */ private saveMidConversationChange(from: number): void { const record = this.pendingMidConversationChange if (!record) return const index = this.messages.findIndex( (message, at) => at >= from && message.role === 'assistant', ) if (index < 0) return this.pendingMidConversationChange = undefined this.messages = this.messages.map((message, at) => at === index ? { ...message, midConversationChange: record } : message, ) } /** * Extract client state (approvals and client tool results) from original messages. * This is called in the constructor BEFORE converting to ModelMessage format, * because the parts array (which contains approval state) is lost during conversion. */ private extractClientStateFromOriginalMessages( originalMessages: Array, ): { approvals: Map clientToolResults: Map } { const approvals = new Map() const clientToolResults = new Map() for (const message of originalMessages) { // Check for UIMessage format (parts array) - extract client tool results and approvals if (message.role === 'assistant' && message.parts) { for (const part of message.parts) { if (part.type === 'tool-call') { // Extract client tool results (tools without approval that have output) if (part.output !== undefined && !part.approval) { clientToolResults.set(part.id, part.output) } // Extract approval responses from UIMessage format parts if ( part.approval?.id && part.approval?.approved !== undefined && part.state === 'approval-responded' ) { approvals.set(part.approval.id, part.approval.approved) } } } } } return { approvals, clientToolResults } } private collectClientState(): { approvals: Map clientToolResults: Map } { // Start with the initial client state extracted from original messages const approvals = new Map(this.initialApprovals) const clientToolResults = new Map(this.initialClientToolResults) for (const [approvalId, approved] of this.resumeApprovals) { approvals.set(approvalId, approved) } for (const [toolCallId, result] of this.resumeClientToolResults) { clientToolResults.set(toolCallId, result) } // Also check current messages for any additional tool results (from server tools) for (const message of this.messages) { // Check for ModelMessage format (role: 'tool' messages contain tool results) // This handles results sent back from the client after executing client-side tools if (message.role === 'tool' && message.toolCallId) { // Parse content back to original output (was stringified by // uiMessageToModelMessages). Multimodal results carry an // Array directly — pass it through without parsing. const output: unknown = Array.isArray(message.content) ? message.content : parseToolOutput(message.content as string, message.metadata) // Skip approval response messages (they have pendingExecution marker) // These are NOT real client tool results — they are synthetic tool messages // created by uiMessageToModelMessages for approved-but-not-yet-executed tools. // Treating them as results would prevent the server from requesting actual // client-side execution after approval (see GitHub issue #225). if ( output && typeof output === 'object' && (output as any).pendingExecution === true ) { continue } clientToolResults.set(message.toolCallId, output) } } return { approvals, clientToolResults } } private genericInterruptId(): string { return this.createId('interrupt') } private buildActionableInterrupts( approvals: Array, clientRequests: Array, genericRequests: ReadonlyArray< GenericInterruptRequest> > = [], genericInterruptIds: ReadonlyArray = [], inputRequired: ReadonlyArray = [], childInterrupts: ReadonlyArray = [], ): Array { const interrupts: Array = [] for (const approval of approvals) { const tool = this.tools.find( (candidate) => candidate.name === approval.toolName, ) as RuntimeToolWithApproval | undefined const normalized = normalizeApprovalSchema( tool?.approvalSchema, tool?.inputSchema, ) interrupts.push({ id: approval.approvalId, // Display hint only. `reason` is free-form AG-UI text that another // producer can also spell `tool_call`, so it never decides ownership — // the binding in `metadata` does. reason: 'tool_call', message: `Approval required to run ${approval.toolName}`, toolCallId: approval.toolCallId, responseSchema: normalized.responseSchema, metadata: { kind: 'approval', toolName: approval.toolName, input: approval.input, [interruptBindingMetadataKey]: { v: INTERRUPT_BINDING_VERSION, kind: 'tool-approval', interruptId: approval.approvalId, toolName: approval.toolName, toolCallId: approval.toolCallId, originalArgs: approval.input, inputSchemaHash: hashSchemaInput(tool?.inputSchema), approvalSchemaHash: normalized.approvalSchemaHash, responseSchemaHash: normalized.responseSchemaHash, }, }, }) } for (const clientTool of clientRequests) { const tool = this.tools.find( (candidate) => candidate.name === clientTool.toolName, ) const responseSchema = convertSchemaToJsonSchema(tool?.outputSchema) ?? {} interrupts.push({ id: `client_tool_${clientTool.toolCallId}`, reason: 'tanstack:client_tool_execution', message: `Client tool ${clientTool.toolName} is ready to run`, toolCallId: clientTool.toolCallId, responseSchema, metadata: { kind: 'client_tool', toolName: clientTool.toolName, input: clientTool.input, [interruptBindingMetadataKey]: { v: INTERRUPT_BINDING_VERSION, kind: 'client-tool-execution', interruptId: `client_tool_${clientTool.toolCallId}`, toolName: clientTool.toolName, toolCallId: clientTool.toolCallId, outputSchemaHash: hashSchemaInput(tool?.outputSchema), responseSchemaHash: digestInterruptJson( canonicalInterruptJson(responseSchema), ), }, }, }) } for (const [index, request] of genericRequests.entries()) { const batchIndex = interrupts.length const id = genericInterruptIds[index] if (!id) throw new Error('Generic interrupt id is unavailable.') const preEmission = createInterruptBinding(request, { batchIndex }) interrupts.push({ id, reason: request.reason, message: request.message, ...(preEmission.descriptor.responseSchemaCanonicalJson !== undefined ? { responseSchema: JSON.parse( preEmission.descriptor.responseSchemaCanonicalJson, ), } : {}), ...(request.expiresAt !== undefined ? { expiresAt: request.expiresAt } : {}), metadata: { [interruptBindingMetadataKey]: { v: INTERRUPT_BINDING_VERSION, kind: 'generic', interruptId: id, definitionId: preEmission.descriptor.definitionId, key: preEmission.descriptor.key, batchIndex, ...(request.expiresAt !== undefined ? { expiresAt: request.expiresAt } : {}), ...(preEmission.descriptor.payloadSchemaHash ? { payloadSchemaHash: preEmission.descriptor.payloadSchemaHash, } : {}), ...(preEmission.descriptor.responseSchemaHash !== undefined ? { responseSchemaHash: preEmission.descriptor.responseSchemaHash, } : {}), }, ...(preEmission.payload !== undefined ? { [INTERRUPT_PAYLOAD_METADATA_KEY]: preEmission.payload } : {}), }, }) } for (const pendingInput of inputRequired) { const id = `mcp_input_${pendingInput.toolCallId}` interrupts.push({ id, reason: pendingInput.reason ?? 'mcp_input', message: `Input required to run ${pendingInput.toolName}`, toolCallId: pendingInput.toolCallId, metadata: { toolName: pendingInput.toolName, // A generic binding with no definition id. `useChat` shows it as a // generic interrupt with `resolveInterrupt` and `cancel`. The answer // is not validated here. The MCP server checks it. [interruptBindingMetadataKey]: { v: INTERRUPT_BINDING_VERSION, kind: 'generic', interruptId: id, }, [INTERRUPT_PAYLOAD_METADATA_KEY]: { kind: pendingInput.kind, request: pendingInput.request, }, }, }) } // A subagent tool call raised these. They keep their `subagentRunId`. interrupts.push(...childInterrupts) const ids = new Set() for (const interrupt of interrupts) { if (ids.has(interrupt.id)) { throw new Error( `Duplicate interrupt id in final batch: ${interrupt.id}`, ) } ids.add(interrupt.id) } return interrupts } private buildInterruptFinishedChunk( finishEvent: RunFinishedEvent, approvals: Array, clientRequests: Array, genericRequests: ReadonlyArray< GenericInterruptRequest> > = [], genericInterruptIds?: ReadonlyArray, inputRequired: ReadonlyArray = [], childInterrupts?: ReadonlyArray, ): StreamChunk { return { ...finishEvent, timestamp: Date.now(), outcome: { type: 'interrupt', interrupts: this.buildActionableInterrupts( approvals, clientRequests, genericRequests, genericInterruptIds, inputRequired, childInterrupts, ), }, } } /** * Record a `ui-resource` CUSTOM chunk on the assistant ModelMessage owning * its `toolCallId` so the resource survives later MESSAGES_SNAPSHOT chunks * (e.g. the interrupt snapshot emitted when the run pauses on a client * tool). Mirrors the anchor-preserving approach used for * `toolCallMetadata` (#867). See #1397. */ private recordEmittedUiResource(value: unknown): void { const part = uiResourcePartFromCustomValue(value) if (!part) return const next = appendUiResourceToModelMessages(this.messages, part) if (next === this.messages) return this.messages = next this.middlewareCtx.messages = this.messages } private assignSnapshotMessageIds(): void { // Store the ids the snapshot gives, so a reload of the stored messages // names each message as the live chat does. Persistence saves on the // interrupt RUN_FINISHED and skips onFinish, so these ids must exist // before that terminal reaches onChunk. this.messages = this.messages.map((message, index) => ({ ...message, id: message.id || `snapshot_${this.runIdOverride ?? this.requestId}_${index}`, })) this.middlewareCtx.messages = this.messages } private buildMessagesSnapshotChunk(): StreamChunk { this.assignSnapshotMessageIds() return { type: EventType.MESSAGES_SNAPSHOT, timestamp: Date.now(), messages: uiMessagesToWire( interleaveActivityRecords( modelMessagesToUIMessages(this.messages), this.activities, ), { includeSnapshotStructuredOutput: true, includeActivity: true, }, ), } } private publicInterruptTerminal(chunk: StreamChunk): StreamChunk { if ( chunk.type !== EventType.RUN_FINISHED || chunk.outcome?.type !== 'interrupt' ) { return chunk } return { ...chunk, outcome: { ...chunk.outcome, interrupts: chunk.outcome.interrupts.map((interrupt) => { if ( !interrupt.metadata || typeof interrupt.metadata !== 'object' || Array.isArray(interrupt.metadata) ) { return interrupt } const metadata = { ...interrupt.metadata } const binding = normalizePublicInterruptBinding( metadata[interruptBindingMetadataKey], interrupt.id, ) if (binding) { metadata[interruptBindingMetadataKey] = binding } else { delete metadata[interruptBindingMetadataKey] } return { ...interrupt, metadata } }), }, } } private interruptFailure(error: unknown): { message: string code: string errors?: ReadonlyArray } { const structured = structuralInterruptFailure(error) if (structured) { return { message: structured.error.message, code: structured.errors[0]?.code ?? 'server', errors: structured.errors, } } if (error && typeof error === 'object' && 'errors' in error) { const errors = error.errors if (Array.isArray(errors)) { const first = errors[0] if (first && typeof first === 'object') { const message = 'message' in first && typeof first.message === 'string' ? first.message : 'Interrupt persistence failed.' const code = 'code' in first && typeof first.code === 'string' ? first.code : 'server' return { message, code } } } } return { message: error instanceof Error ? error.message : 'Interrupt persistence failed.', code: 'server', } } private buildInterruptRunErrorChunk(error: unknown): StreamChunk { const failure = this.interruptFailure(error) return withTanstackMetadata( { type: EventType.RUN_ERROR, timestamp: Date.now(), message: failure.message, code: failure.code, }, { runId: this.runIdOverride ?? this.requestId, threadId: this.threadId, ...(failure.errors !== undefined ? { interruptErrors: failure.errors } : {}), }, ) as StreamChunk } private async *emitInterruptRunError( error: unknown, ): AsyncGenerator { const failure = this.interruptFailure(error) this.finalizationError = { message: failure.message, code: failure.code, cause: error, } yield* this.pipeThroughMiddleware(this.buildInterruptRunErrorChunk(error)) } private async *emitActionableInterruptBoundary( finishEvent: RunFinishedEvent, approvals: Array, clientRequests: Array, genericRequests: ReadonlyArray< GenericInterruptRequest> > = [], inputRequired: ReadonlyArray = [], childInterrupts: ReadonlyArray = [], ): AsyncGenerator { yield* this.emitSyntheticRunStarted(finishEvent) const genericInterruptIds = genericRequests.map(() => this.genericInterruptId(), ) // Binding completion also binds child interrupts to this run. const terminal = this.completeEphemeralInterruptBindings( this.buildInterruptFinishedChunk( finishEvent, approvals, clientRequests, genericRequests, genericInterruptIds, inputRequired, childInterrupts, ), ) this.assignSnapshotMessageIds() let terminalOutputs: Array try { terminalOutputs = [ ...this.emitPublicChunks( await this.middlewareRunner.runOnChunk(this.middlewareCtx, terminal), ), ] } catch (error) { yield* this.emitInterruptRunError(error) return false } yield* this.pipeThroughMiddleware(this.buildMessagesSnapshotChunk()) if (this.params.state !== undefined) { yield* this.pipeThroughMiddleware({ type: EventType.STATE_SNAPSHOT, timestamp: Date.now(), snapshot: this.params.state, }) } for (const output of terminalOutputs) { yield this.publicInterruptTerminal(output) } return true } private async *emitBoundaryInterrupts( phase: 'beforeModel' | 'afterModel' | 'beforeTools' | 'afterTools', finishEvent: RunFinishedEvent, toolCalls: ReadonlyArray = [], requests?: ReadonlyArray< GenericInterruptRequest> >, // The tool phase result, so an afterTools boundary runs no hook twice. executed?: ExecuteToolCallsResult, ): AsyncGenerator { this.middlewareCtx.phase = phase const boundaryRequests = requests ?? (yield* this.runWhileYielding( this.middlewareRunner.runOnInterruptBoundary( this.middlewareCtx as ChatMiddlewareContext & { phase: typeof phase }, ), )) if (boundaryRequests.length === 0) return false for (const request of boundaryRequests) { if ( this.interruptDefinitions.get(request.definition.id) !== request.definition ) { throw new Error( `Generic interrupt definition ${request.definition.id} is not registered on this chat.`, ) } } if (phase === 'afterModel') { if (this.toolCallManager.hasToolCalls()) { this.addAssistantToolCallMessage(this.toolCallManager.getToolCalls()) } else { this.addTerminalAssistantMessages() } } const actionable = executed ?? (yield* this.drainBoundaryToolRequests(toolCalls)) for (const chunk of this.buildToolResultChunks( actionable.results, finishEvent, )) { yield* this.pipeThroughMiddleware(chunk) } yield* this.emitActionableInterruptBoundary( finishEvent, actionable.needsApproval, actionable.needsClientExecution, boundaryRequests, actionable.inputRequired, actionable.subagentInterrupts, ) return true } private async *drainBoundaryToolRequests( toolCalls: ReadonlyArray, ): AsyncGenerator { const rawEdits = this.captureApprovedArgumentEdits(toolCalls) const result = yield* this.drainToolCallGenerator( this.boundaryToolRequests(toolCalls), ) this.retainApprovedArgumentEdits(result, rawEdits) return result } /** * The approval previews and client requests a boundary pauses with. They get * the same middleware hook and final input check as the tool phase, and a * skip or an invalid input becomes a tool result. No server tool runs here: * a server tool is in the list only while it waits for approval. */ private boundaryToolRequests( toolCalls: ReadonlyArray, ): ReturnType { const { approvals, clientToolResults } = this.collectClientState() const tools = this.resolveExecutableTools(toolCalls) const pendingCalls = toolCalls.filter((toolCall) => { // Provider-executed calls are complete; never surface them as client work. if (isProviderExecutedToolCall(toolCall)) return false const tool = tools.find( (candidate) => candidate.name === toolCall.function.name, ) if (!tool) return false if ( tool.needsApproval && approvalResolution(approvals, toolCall.id) === undefined ) { return true } return ( !tool.execute && !clientToolResults.has(toolCall.id) && !this.resumeClientToolErrors.has(toolCall.id) && !this.resumeCancelledToolCallIds.has(toolCall.id) ) }) return executeToolCalls( pendingCalls, tools, this.threadId, approvals, clientToolResults, undefined, this.toolMiddlewareHooks(), this.middlewareCtx.context, this.toolAbortSignal, this.toolResumeState(), undefined, this.params.repairToolInput, this.toolCapabilities(), ) } /** The run's capability readers, for each server tool's context. */ private toolCapabilities(): Pick< ToolExecutionContext, 'get' | 'getOptional' > { const { get, getOptional } = this.middlewareCtx return { get, getOptional } } private toolMiddlewareHooks(): ToolExecutionMiddlewareHooks { return { onBeforeToolCall: async (toolCall, tool, args) => { this.logger.tools(`phase=before name=${toolCall.function.name}`, { name: toolCall.function.name, args, }) return this.middlewareRunner.runOnBeforeToolCall(this.middlewareCtx, { toolCall, tool, args, toolName: toolCall.function.name, toolCallId: toolCall.id, }) }, onGuardToolCall: async (toolCall, tool, args) => this.middlewareRunner.runOnGuardToolCall(this.middlewareCtx, { toolCall, tool, args, toolName: toolCall.function.name, toolCallId: toolCall.id, }), onAfterToolCall: async (info) => { this.logger.tools(`phase=after name=${info.toolName}`, { name: info.toolName, result: info.result, }) return this.middlewareRunner.runOnAfterToolCall( this.middlewareCtx, info, ) }, } } private toolResumeState(): ToolResumeExecutionState { return { clientToolErrors: this.resumeClientToolErrors, deniedToolResults: this.resumeDeniedToolResults, cancelledToolCallIds: this.resumeCancelledToolCallIds, inputResponses: this.resumeInputResponses, } } private completeEphemeralInterruptBindings(chunk: StreamChunk): StreamChunk { if ( chunk.type !== EventType.RUN_FINISHED || chunk.outcome?.type !== 'interrupt' ) { return chunk } const interruptedRunId = this.runIdOverride ?? this.requestId return { ...chunk, outcome: { ...chunk.outcome, interrupts: chunk.outcome.interrupts.map((interrupt) => { if ( !interrupt.metadata || typeof interrupt.metadata !== 'object' || Array.isArray(interrupt.metadata) ) { return interrupt } const metadata = { ...interrupt.metadata } const unopened = metadata[interruptBindingMetadataKey] if ( unopened === null || typeof unopened !== 'object' || Array.isArray(unopened) ) { return interrupt } metadata[interruptBindingMetadataKey] = { ...unopened, interruptedRunId, generation: 0, } return { ...interrupt, metadata } }), }, } } private buildToolResultChunks( results: Array, _finishEvent: RunFinishedEvent, argsMap?: Map, replaceExisting = false, ): Array { const chunks: Array = [] for (const result of results) { // `content` is the canonical value for the tool `ModelMessage` — it may // be an `Array` (multimodal) which the adapters convert to // structured provider output on the next iteration. `wireContent` is the // string form emitted on TOOL_CALL_RESULT.content (string-only per the // AG-UI spec); the multimodal array travels via the message itself. const content = normalizeToolResult(result.result) const wireContent = typeof content === 'string' ? content : JSON.stringify(content) // argsMap is set only on continuation re-executions, where the adapter // never streamed these calls. Otherwise it already emitted END, so a // second one here would be an orphan that fails verifyEvents (#519). if (argsMap) { chunks.push({ type: EventType.TOOL_CALL_START, timestamp: Date.now(), toolCallId: result.toolCallId, toolCallName: result.toolName, }) const args = argsMap.get(result.toolCallId) ?? '{}' chunks.push({ type: EventType.TOOL_CALL_ARGS, timestamp: Date.now(), toolCallId: result.toolCallId, delta: args, }) chunks.push({ type: EventType.TOOL_CALL_END, timestamp: Date.now(), toolCallId: result.toolCallId, }) } const parentMessageId = [...this.messages] .reverse() .find((message) => message.role === 'assistant')?.id const resultChunk = { type: EventType.TOOL_CALL_RESULT, timestamp: Date.now(), messageId: parentMessageId || result.toolCallId, toolCallId: result.toolCallId, content: wireContent, role: 'tool' as const, } // An outcome always comes with output-error. A string result says so, // or the client would parse '42' into 42. const textMark = textToolResultMark(result.result) const resultMetadata = { ...(result.state === 'output-error' && { state: result.state, ...(result.outcome !== undefined && { toolResultOutcome: result.outcome, }), }), ...textMark, } chunks.push( (Object.keys(resultMetadata).length > 0 ? withTanstackMetadata(resultChunk, resultMetadata) : resultChunk) as StreamChunk, ) // If a placeholder tool message exists for this toolCallId (created by // uiMessageToModelMessages for an approval-responded part with no // output yet), replace it with the real result. Otherwise the LLM sees // both messages — and since the Anthropic adapter dedupes tool_result // blocks by tool_use_id keeping the first match, the placeholder wins // and the real result is dropped (see issue #532). const placeholderIdx = this.messages.findIndex((m) => { if (m.role !== 'tool' || m.toolCallId !== result.toolCallId) { return false } if (typeof m.content !== 'string') return false const parsed = parseToolOutput(m.content, m.metadata) return ( typeof parsed === 'object' && parsed !== null && (parsed as { pendingExecution?: unknown }).pendingExecution === true ) }) const isDeniedResult = result.outcome === 'denied' const existingToolResultIdx = isDeniedResult || replaceExisting ? this.messages.findIndex( (message) => message.role === 'tool' && message.toolCallId === result.toolCallId, ) : -1 const resultMessageIdx = existingToolResultIdx >= 0 ? existingToolResultIdx : placeholderIdx // Only a denied result or `replaceExisting` (the cut calls of an answer // at the output limit) keeps the old message's fields. A replaced // pendingExecution placeholder must not leak into the real result. const existingToolMessage = existingToolResultIdx >= 0 ? this.messages[existingToolResultIdx] : undefined // Stored error uses the original result, so a text-marked JSON string // stays that string live and after reload. Adapter { error } JSON is // already an object when recorded, so this still extracts the message. const errorField = result.state === 'output-error' && { error: toolResultErrorText(result.result), } const replacementMessage: ModelMessage = existingToolMessage?.role === 'tool' ? { ...existingToolMessage, content, toolCallId: result.toolCallId, ...errorField, } : { role: 'tool', content, toolCallId: result.toolCallId, ...errorField, } const messageMetadata = { ...(result.outcome !== undefined && { toolResultOutcome: result.outcome, }), ...textMark, } const newToolMessage: ModelMessage = Object.keys(messageMetadata).length > 0 ? withTanstackMetadata(replacementMessage, messageMetadata) : replacementMessage if (resultMessageIdx >= 0) { const replacedMessages = [ ...this.messages.slice(0, resultMessageIdx), newToolMessage, ...this.messages.slice(resultMessageIdx + 1), ] this.messages = isDeniedResult ? replacedMessages.filter( (message, index) => index === resultMessageIdx || !( message.role === 'tool' && message.toolCallId === result.toolCallId ), ) : replacedMessages } else { this.messages = [...this.messages, newToolMessage] } this.middlewareCtx.messages = this.messages } return chunks } private getPendingToolCallsFromMessages(): Array { // Build a set of completed tool IDs, but exclude tools with pendingExecution marker // (these are approved tools that still need to execute) const completedToolIds = new Set() for (const message of this.messages) { if (message.role === 'tool' && message.toolCallId) { // Check if this is an approval response with pendingExecution marker let hasPendingExecution = false if (typeof message.content === 'string') { const parsed = parseToolOutput(message.content, message.metadata) if ( typeof parsed === 'object' && parsed !== null && (parsed as { pendingExecution?: unknown }).pendingExecution === true ) { hasPendingExecution = true } } // Only mark as complete if NOT pending execution if ( !hasPendingExecution && !this.resumeDeniedToolResults.has(message.toolCallId) ) { completedToolIds.add(message.toolCallId) } } } const pending: Array = [] // A later user or assistant closes the previous execution batch. // Old orphan calls remain in history for request-local replay cleanup. const activeCallIds = new Set() let assistantId: string | undefined for (const message of this.messages) { if (message.role === 'tool') continue const segmentSuffix = assistantId === undefined || message.id === undefined ? undefined : message.id.slice(assistantId.length) const sameAssistant = message.role === 'assistant' && assistantId !== undefined && message.id?.startsWith(assistantId) && /^-segment-[1-9]\d*$/.test(segmentSuffix ?? '') if (!sameAssistant) { activeCallIds.clear() assistantId = message.role === 'assistant' ? message.id : undefined } const stopReason = tanstackMetadata(message)?.stopReason if ( message.role === 'assistant' && stopReason !== 'error' && stopReason !== 'aborted' ) { for (const call of message.toolCalls ?? []) activeCallIds.add(call.id) } } const { approvals } = this.collectClientState() for (const message of this.messages) { if (message.role === 'assistant' && message.toolCalls) { const metadata = tanstackMetadata(message) // The calls of a failed answer, or of an answer that the output limit // cut, are not complete. They never run. if ( metadata?.stopReason === 'error' || metadata?.stopReason === 'aborted' || metadata?.finishReason === 'length' ) continue for (const toolCall of message.toolCalls) { // Provider-executed tool calls (e.g. Anthropic `web_search`) were // already run by the provider; they carry no client result, so they // would otherwise look "pending" forever and the loop would try (and // fail) to execute them client-side. Skip them. if (isProviderExecutedToolCall(toolCall)) { continue } const explicitlyResumed = approvals.has(toolCall.id) || approvals.has(`approval_${toolCall.id}`) || this.resumeClientToolResults.has(toolCall.id) || this.resumeClientToolErrors.has(toolCall.id) || this.resumeCancelledToolCallIds.has(toolCall.id) if ( !completedToolIds.has(toolCall.id) && (activeCallIds.has(toolCall.id) || explicitlyResumed) ) { pending.push(toolCall) } } } } return pending } /** * Find a tool call by id in message history (including already-completed ones). * Used when the client has already attached a tool result for UI before resume. */ private findToolCallInMessages(toolCallId: string): ToolCall | undefined { for (const message of this.messages) { if (message.role !== 'assistant' || !message.toolCalls) continue for (const toolCall of message.toolCalls) { if (toolCall.id === toolCallId) return toolCall } } return undefined } /** * Tool calls that must be reconstructed as interrupt pending for ephemeral * resume. Includes outstanding tools plus client tools that already have * results in history when the resume batch still carries `client_tool_*` * entries (the client writes local tool results before submitting resume). */ private getToolCallsForEphemeralResume( resume: ReadonlyArray<{ interruptId: string }> | undefined, ): Array { const pending = this.getPendingToolCallsFromMessages() const byId = new Map(pending.map((toolCall) => [toolCall.id, toolCall])) for (const entry of resume ?? []) { // Recover tool calls the client already finalized in history for two // resume-batch cases that no longer look "pending": // - `client_tool_*`: a client tool wrote its output before resuming. // - `approval_*`: a DENIED approval wrote its denial result, so the // call reads as completed. Without this it drops out of the // reconstructed batch and the resume entry fails as unknown-interrupt. let toolCallId: string | undefined if (entry.interruptId.startsWith('client_tool_')) { toolCallId = entry.interruptId.slice('client_tool_'.length) } else if (entry.interruptId.startsWith('approval_')) { toolCallId = entry.interruptId.slice('approval_'.length) } if (toolCallId === undefined || byId.has(toolCallId)) continue const toolCall = this.findToolCallInMessages(toolCallId) if (toolCall && !isProviderExecutedToolCall(toolCall)) { pending.push(toolCall) byId.set(toolCallId, toolCall) } } return pending } private createSyntheticFinishedEvent( finishReason: 'stop' | 'tool_calls' = 'tool_calls', ): RunFinishedEvent { return withTanstackMetadata( { type: EventType.RUN_FINISHED, runId: this.runIdOverride ?? this.requestId, threadId: this.threadId, timestamp: Date.now(), }, { finishReason, model: this.params.model }, ) as RunFinishedEvent } private async shouldContinue(): Promise { // Always enter the tool-execution half-cycle after a model turn. if (this.cyclePhase === 'executeToolCalls') { return true } // The tool phase of a cut answer asked already. const cutAnswerContinues = this.cutAnswerContinues this.cutAnswerContinues = undefined const continues = cutAnswerContinues ?? (await this.loopContinues(this.iterationCount)) // Tool results wait for the next model call, and the loop says no. if (!continues && this.toolPhase === 'continue') this.loopStopped = true return continues && this.toolPhase === 'continue' } /** * A streamed structured-output finalization sends the one outer * RUN_STARTED / RUN_FINISHED pair, not the agent loop. */ private finalizationOwnsLifecycle(): boolean { return ( !!this.finalStructuredOutput && this.finalStructuredOutput.yieldChunks && this.finalStructuredOutput.nativeCombined !== true ) } /** * Mark the last assistant message as stopped by the loop, so a stored * transcript keeps the signal of the `RUN_FINISHED`. */ private markLoopStoppedMessage(): void { const index = this.messages.findLastIndex((m) => m.role === 'assistant') if (index < 0) return this.messages = this.messages.map((message, at) => at === index ? withTanstackMetadata(message, { loopStopped: true }) : message, ) this.middlewareCtx.messages = this.messages } /** What the loop strategy and middleware `onShouldContinue` get. */ private loopState(iterationCount: number) { return { iterationCount, messages: this.messages, finishReason: this.lastFinishReason, toolCallCount: this.toolCallCount, lastTurnToolCallCount: this.lastTurnToolCallCount, } } /** Ask the loop strategy and middleware `onShouldContinue`. */ private async loopContinues(iterationCount: number): Promise { const state = this.loopState(iterationCount) // Evaluate strategy and middleware unconditionally (even when the // strategy already says stop) so every onShouldContinue observer still // sees the final counters. const strategyContinues = this.loopStrategy(state) const middlewareContinues = await this.middlewareRunner.runOnShouldContinue( this.middlewareCtx, state, ) return strategyContinues && middlewareContinues } /** * Record tool calls (deduped by id) toward `toolCallCount` / * `lastTurnToolCallCount` for strategies and middleware `onShouldContinue`. * * Used for both live model turns and pending/resume batches. IDs already * counted in this run (e.g. wait→resume after a live turn) are not * re-added to `toolCallCount`. Per-turn execution caps are app middleware * (`onBeforeToolCall` skip), not engine policy. */ private recordToolCalls(toolCalls: Array): void { this.lastTurnToolCallCount = toolCalls.length let newlyCounted = 0 for (const tc of toolCalls) { if (!this.countedToolCallIds.has(tc.id)) { this.countedToolCallIds.add(tc.id) newlyCounted++ } } this.toolCallCount += newlyCounted } private isAborted(): boolean { return !!this.effectiveSignal?.aborted } private isMiddlewareAborted(): boolean { return !!this.middlewareAbortController?.signal.aborted } private isCancelled(): boolean { return this.isAborted() || this.isMiddlewareAborted() } /** * The reason to report on `AbortInfo` for a cancelled run. * * `this.abortReason` only ever holds a *middleware*-initiated reason * (`ctx.abort(reason)` / `MiddlewareAbortError`). A caller that aborts its own * controller — `abortController.abort(RUN_CANCEL_REASON)`, the in-process * cancel channel — never touches that field, so the reason has to be read back * off the caller's signal, which is the signal `isCancelled()` consults via * `isAborted()`. A signal aborted with no reason carries a DOMException rather * than a string, so non-string reasons are reported as absent. */ private resolveAbortReason(): string | undefined { if (this.abortReason !== undefined) return this.abortReason const signalReason: unknown = this.effectiveSignal?.reason return typeof signalReason === 'string' ? signalReason : undefined } /** * Whether this run's teardown declared its abort a DETACH — see * {@link RunDetachedCapability}. Only `withSandbox`'s `onAbort` publishes it, * and only for a plain, intentless disconnect of a detachable run, so every * other exit path answers `false`. * * Surfaced on the engine (rather than the ctx being handed out) so the * capability read stays inside core, and so the delivery sink learns the * verdict through {@link publishRunDetachedSignal} instead of reaching into a * middleware context it has no business holding. * * @internal */ wasDetached(): boolean { return getRunDetached(this.middlewareCtx, { optional: true }) === true } /** * The delivery socket closed while this run was still going. * * Notifies every subscriber (see {@link RunDisconnectCapability}) and RETURNS * IMMEDIATELY. Synchronous on purpose: it is called from * `ReadableStream.cancel()`, which must not be made to wait on a run-store * write, and the caller ({@link notifyRunDisconnected}) has no consumer left to * report to anyway. * * Subscribers therefore run CONCURRENTLY with the still-executing run — which is * the entire point. The run is typically suspended inside a slow middleware * `setup` at this moment, so anything dispatched from the run's own unwinding * would be minutes late. Nothing on this path aborts the run: a durable run * outlives its viewer. * * Each subscriber's promise is parked on `deferredPromises`, which the run awaits * in its `finally`, so bookkeeping cannot be lost to a race with the run's own * completion even though nothing awaits it here. * * IDEMPOTENT. A second cancel, or one arriving after a terminal hook already ran, * is ignored: the terminal hooks own the run's outcome, and re-stamping * `detachedSince` on a run that has already finished would hand a completed run * to the reaper as reclaimable work. * * @internal */ notifyDisconnected(): void { if (this.disconnected || this.terminalHookCalled) return this.disconnected = true for (const listener of this.disconnectListeners) { this.runDisconnectListener(listener) } } /** * Invoke one disconnect listener, isolated and with its failure SWALLOWED after * logging. * * There is no caller left to report to — the socket this would report on is the * one that just closed — and a rejection parked on `deferredPromises` would * surface as the run's failure, replacing a healthy outcome with a bookkeeping * error. Isolation matters for the usual reason too: one subscriber's failing * write must not skip the next one's. */ private runDisconnectListener(listener: () => void | Promise): void { let result: void | Promise try { result = listener() } catch (error) { this.logger.errors('run disconnect listener failed', { error }) return } if (result === undefined) return this.deferredPromises.push( result.catch((error: unknown) => { this.logger.errors('run disconnect listener failed', { error }) }), ) } /** * Run the final structured-output adapter call through the middleware * pipeline. Yields chunks to the caller only when * `this.finalStructuredOutput.yieldChunks` is true; otherwise consumes * silently while still piping through middleware. * * On success, populates this.structuredOutputResult. * On failure, populates this.finalizationError. */ private async *runStructuredFinalization(): AsyncGenerator { if (!this.finalStructuredOutput) { throw new Error( 'runStructuredFinalization called without finalStructuredOutput config', ) } this.middlewareCtx.phase = 'structuredOutput' // Build the structured-output config view. `tools` and `toolChoice` are // intentionally excluded from the type because they aren't forwarded to // the structured-output adapter call — including them would be misleading. const baseConfig = this.buildMiddlewareConfig() const { tools: _omitTools, toolChoice: _omitToolChoice, ...baseWithoutTools } = baseConfig let structuredConfig: StructuredOutputMiddlewareConfig = { ...baseWithoutTools, outputSchema: this.finalStructuredOutput.jsonSchema, } // 1) onStructuredOutputConfig — middleware can transform messages, options, outputSchema structuredConfig = yield* this.runWhileYielding( this.middlewareRunner.runOnStructuredOutputConfig( this.middlewareCtx, structuredConfig, ), ) // 2) onConfig — phase-aware general-purpose middleware re-runs at the // boundary. Re-attach the engine's current tools so onConfig observers // see the live tool set (they still won't be forwarded to the structured // call — same constraint applies — but the view is consistent with the // ChatMiddlewareConfig shape). const { outputSchema: pinnedSchema, ...chatConfigSlice } = structuredConfig const postOnConfig = yield* this.runWhileYielding( this.middlewareRunner.runOnConfig(this.middlewareCtx, { ...chatConfigSlice, tools: baseConfig.tools, }), ) // Apply merged config back to engine state this.applyMiddlewareConfig(postOnConfig) // Schema-only structured output with no tools skips the agent loop, so // `streamModelResponse` never runs this check. Middleware can also // replace `this.messages` above. Fail closed here before the // structured-output adapter call. assertMessagesFileSourceSupport(this.adapter, this.messages) // Build the StructuredOutputOptions the adapter expects. // `this.adapter` is already `TAdapter extends AnyTextAdapter` per the // class generics — no cast needed. const structuredCallOptions = { chatOptions: { model: this.params.model, ...sanitizeProviderRequest( transformMessagesForReplay(this.providerMessages).messages, postOnConfig.systemPrompts, ), metadata: postOnConfig.metadata, modelOptions: postOnConfig.modelOptions, ...(postOnConfig.reasoning ? { reasoning: postOnConfig.reasoning } : {}), logger: this.logger, threadId: this.threadId, promptCache: this.params.promptCache, runId: this.runIdOverride, parentRunId: this.parentRunIdOverride, ...(this.effectiveRequest ? { request: this.effectiveRequest } : {}), ...(this.callWrapFetch ? { wrapFetch: this.callWrapFetch } : {}), }, outputSchema: pinnedSchema, } // Select the provider call: native streaming if available, else synthesized fallback. // The fallback path captures the original adapter error so the engine can // attach it as `finalizationError.cause` (the RUN_ERROR wire shape only // carries `message` and `code`, losing stack/cause/provider properties). let fallbackAdapterError: unknown = undefined this.structuredCallMetadata = { source: { provider: this.adapter.provider ?? this.adapter.name, api: this.adapter.api ?? this.adapter.kind, model: structuredCallOptions.chatOptions.model, }, } this.middlewareCtx.callMetadata = this.structuredCallMetadata const providerStream = this.adapter.structuredOutputStream ? this.adapter.structuredOutputStream(structuredCallOptions) : fallbackStructuredOutputStream( this.adapter, structuredCallOptions, (err) => { fallbackAdapterError = err }, ) // ============================================================ // structured-output.start synthesis // ============================================================ // The client-side StreamProcessor (PR #577) requires a CUSTOM // `structured-output.start` event BEFORE the JSON TEXT_MESSAGE_CONTENT // deltas — that's how it routes deltas into a `StructuredOutputPart` // rather than a plain `TextPart`. No adapter currently emits this, // so the engine synthesizes one (and tracks whether the adapter // emitted its own to avoid duplicating). // // Synthesis fires before the FIRST TEXT_MESSAGE_* event from the inner // stream, OR before a pre-delta RUN_ERROR (so the client can construct // an errored structured-output placeholder). let startEmitted = false let structuredMessageId: string | null = null const extractMessageId = (c: StreamChunk): string | null => { if ( c.type === EventType.TEXT_MESSAGE_START || c.type === EventType.TEXT_MESSAGE_CONTENT || c.type === EventType.TEXT_MESSAGE_END ) { return typeof c.messageId === 'string' && c.messageId !== '' ? c.messageId : null } return null } // The synthetic event is inserted before its trigger, so share that // trigger's timestamp rather than making the earlier event sort later. const buildSynthesizedStart = (timestamp = Date.now()): StreamChunk => { const idForStart = structuredMessageId ?? generateMessageId() structuredMessageId = idForStart this.captureStructuredOutputMessageIdentity(idForStart) return { type: EventType.CUSTOM, name: 'structured-output.start', value: { messageId: idForStart }, timestamp, } } const runChunkMiddleware = ( synthChunk: StreamChunk, ): Promise> => this.middlewareRunner.runOnChunk(this.middlewareCtx, synthChunk) // Track whether a RUN_ERROR has been yielded to streaming consumers so // we don't emit a duplicate synthetic one at the end. let runErrorYielded = false // The full model text. Adapter errors carry only a 200-character preview, // so a Promise caller could not recover the answer (#1485). let rawText = '' // Set when the value fails the schema. The provider still billed the // call, so the loop reads on to its terminal event for the usage. let validationFailed = false let validationUsage: TokenUsage | undefined // After a schema failure the loop only reads on for the billed usage. A // stream that fails then keeps the schema error, not its own. const guardedStream = (async function* () { try { yield* providerStream } catch (error) { if (!validationFailed) throw error } })() // Pipe chunks through middleware; yield to consumer only when yieldChunks=true for await (const raw of guardedStream) { // Honor cancellation between chunks (mirrors streamModelResponse). if (this.isCancelled()) { break } if (validationFailed) { if ( raw.type === EventType.RUN_FINISHED || raw.type === EventType.RUN_ERROR ) { validationUsage = rebuildTokenUsage( raw.usage, tanstackMetadata(raw)?.usage, ) await this.runOnUsageFromChunk(raw, true) break } continue } { const chunk = this.withCallMetadata(raw, this.structuredCallMetadata) // Detect adapter-emitted structured-output.start so we don't duplicate if ( !startEmitted && chunk.type === EventType.CUSTOM && chunk.name === 'structured-output.start' ) { startEmitted = true } // Capture the assistant messageId off any text-message event so the // synthesized start (when needed) uses the SAME id the deltas carry if (!structuredMessageId) { const extracted = extractMessageId(chunk) if (extracted) { structuredMessageId = extracted this.captureStructuredOutputMessageIdentity(extracted) } } // Synthesis only matters for the streaming client path — the agentic // Promise path consumes chunks internally and returns a Promise, so // there's no client-side StreamProcessor to route deltas for. if (this.finalStructuredOutput.yieldChunks) { // Synthesize start before the FIRST TEXT_MESSAGE_* event if ( !startEmitted && (chunk.type === EventType.TEXT_MESSAGE_START || chunk.type === EventType.TEXT_MESSAGE_CONTENT || chunk.type === EventType.TEXT_MESSAGE_END) ) { startEmitted = true const synthStart = buildSynthesizedStart(chunk.timestamp) yield* this.emitPublicChunks(await runChunkMiddleware(synthStart)) } // Synthesize start before a pre-delta RUN_ERROR so the client can // construct an errored placeholder structured-output part instead // of a silent UI. if (!startEmitted && chunk.type === EventType.RUN_ERROR) { startEmitted = true const synthStart = buildSynthesizedStart(chunk.timestamp) yield* this.emitPublicChunks(await runChunkMiddleware(synthStart)) } } // 7a. Targeted state updates only. // We deliberately do NOT call `handleStreamChunk(chunk)` here — that // would mutate agent-loop state with finalization data: // - TEXT_MESSAGE_CONTENT deltas would pollute `accumulatedContent` // (raw JSON would leak into `info.content` on onFinish) // - RUN_FINISHED would overwrite `finishedEvent` + `lastFinishReason` // (finalization's 'stop' would overwrite the agent-loop's real // finish reason) // - REASONING_* events would pollute `currentThinkingContent` // Finalization is a separate phase from the agent loop; its state must // not cross-contaminate. The explicit branches below capture the only // bits we actually need from this stream. // All narrowing below is via the discriminated-union `chunk.type` // — no `as` casts. // The chunk forwarded to middleware/consumers. Replaced below only for // the structured-output.complete event, whose `object` we normalize // (un-widen) so streaming consumers see the same cleaned payload the // Promise path validates and returns. let outboundChunk: StreamChunk = chunk if ( chunk.type === EventType.CUSTOM && chunk.name === 'structured-output.complete' ) { const parsed = readStructuredOutputCompleteValue(chunk.value) if (parsed) { const object = this.finalStructuredOutput.normalize ? this.finalStructuredOutput.normalize(parsed.object) : parsed.object this.structuredOutputResult = { data: object, rawText: parsed.raw, ...(parsed.reasoning !== undefined ? { reasoning: parsed.reasoning } : {}), } // Rewrite the outbound event so the yielded chunk carries the // normalized object (the original `chunk.value` still holds the // widened one). Preserve every other field — `raw`, `reasoning` — // by spreading the original value. const value = chunk.value if ( object !== parsed.object && value && typeof value === 'object' ) { outboundChunk = { ...chunk, value: { ...value, object } } } // Check the value before a consumer gets it. A value that fails // the schema is not sent: the run ends with RUN_ERROR instead. this.validateStructuredOutput(object, parsed.raw) if (this.finalizationError) { validationFailed = true continue } } } if ( chunk.type === EventType.RUN_FINISHED || chunk.type === EventType.RUN_ERROR ) { await this.runOnUsageFromChunk(chunk) } // This is the outer RUN_FINISHED, so it carries the loop stop. if (chunk.type === EventType.RUN_FINISHED && this.loopStopped) { outboundChunk = withTanstackMetadata(chunk, { loopStopped: true, }) } if (chunk.type === EventType.TEXT_MESSAGE_CONTENT) { rawText += chunk.delta } if (chunk.type === EventType.RUN_ERROR) { // RunErrorEvent already exposes `message` and `code` after narrowing. // A native stream has no adapter error to capture, but its RUN_ERROR // can carry the provider's error body as `rawEvent` (#1005). const cause = fallbackAdapterError ?? chunk.rawEvent this.finalizationError = { message: chunk.message, ...(chunk.code ? { code: chunk.code } : {}), ...(cause !== undefined ? { cause } : {}), ...(rawText ? { rawText } : {}), } } // 7b. Pipe through middleware const outputChunks = await this.middlewareRunner.runOnChunk( this.middlewareCtx, outboundChunk, ) // 7c. Decide consumer visibility — only yieldChunks=true callers get them. // We do NOT strip the finalization stream's RUN_STARTED/RUN_FINISHED: // they are the single outer lifecycle pair the consumer sees (the // agent-loop's pair was suppressed in streamModelResponse when // finalStructuredOutput.yieldChunks is true). if (this.finalStructuredOutput.yieldChunks) { for (const spec of this.emitPublicChunks(outputChunks)) { if (spec.type === EventType.RUN_ERROR) { runErrorYielded = true } yield spec } } // 7d. Terminate on error if (this.finalizationError) { break } } if (this.isCancelled() || this.finalizationError) { break } } // Mid-finalization abort: don't attribute a missing-result error. // Let the engine's `finally` block in `run()` route to `onAbort` instead // of mis-routing through `onError`. if (this.isCancelled()) { return } // Empty stream / missing complete event if (!this.structuredOutputResult && !this.finalizationError) { this.finalizationError = { message: 'missing structured result', code: 'structured-output-missing-result', } } // Run schema validation INSIDE the engine — before the terminal hook // chooser runs. Per spec §7.3, validation failures must route through // `onError`, not `onFinish`. We do this by writing to `finalizationError` // so the chooser in `run()` picks `onError`. if (this.structuredOutputResult && !this.finalizationError) { this.validateStructuredOutput( this.structuredOutputResult.data, this.structuredOutputResult.rawText, ) } // Streaming consumers must see a RUN_ERROR for finalization failures // (missing-result, validation-failed, or a finalizationError set after // a structured-output.complete already yielded). Without this synthetic // emission, the `for await` on the engine ends silently for the client. // // Skip when a RUN_ERROR was already yielded from the inner stream // (otherwise the consumer would see two error events for one failure). if ( this.finalizationError && this.finalStructuredOutput.yieldChunks && !runErrorYielded ) { // Empty-stream case: no in-loop synthesis fired because no chunks // arrived. Synthesize `structured-output.start` here so the client-side // StreamProcessor can route the upcoming RUN_ERROR to a // `StructuredOutputPart` instead of dropping it as an orphan error. if (!startEmitted) { const synthStart = buildSynthesizedStart() yield* this.emitPublicChunks(await runChunkMiddleware(synthStart)) startEmitted = true } const errChunk = finalizationErrorChunk({ ...this.finalizationError, ...(validationUsage ? { usage: validationUsage } : {}), }) yield* this.emitPublicChunks( await this.middlewareRunner.runOnChunk(this.middlewareCtx, errChunk), ) } } /** * Native combined mode: harvest the structured output from the agent * loop's accumulated final-turn text (no separate provider call). * * The adapter wired `outputSchema` into the regular `chatStream` request, * so the model's final-turn text is the schema-constrained JSON. We parse * `this.accumulatedContent`, populate `this.structuredOutputResult`, emit * a synthetic `structured-output.complete` (and a `structured-output.start` * if one wasn't emitted earlier — only happens on the streaming path when * the model returned no text at all), and run the validate callback when * present. Failures populate `this.finalizationError` so the engine's * terminal-hook chooser routes to `onError` (per spec §7.3). * * The `'structuredOutput'` middleware phase intentionally does NOT fire on * this path — middleware sees the run through `beforeModel` / `modelStream` * as usual. See PR #605 / issue #605 for the design rationale. */ private async *harvestCombinedStructuredOutput(): AsyncGenerator { if (!this.finalStructuredOutput) { throw new Error( 'harvestCombinedStructuredOutput called without finalStructuredOutput config', ) } const yieldChunks = this.finalStructuredOutput.yieldChunks const source = this.finalStructuredOutput.source ?? 'text' // A final turn cut off at the output cap holds truncated JSON, or none // for a reasoning model that spent the budget. Report the token limit // instead of a parse or missing-result error (#1426). if (this.lastFinishReason === 'length') { this.finalizationError = { message: 'The response was cut off because the maximum token limit was reached (finish_reason=length); raise the output token limit.', code: 'max_tokens', } } else if (source === 'event') { if (!this.structuredOutputResult) { this.finalizationError = { message: 'missing structured result', code: 'structured-output-missing-result', } } } else { const rawText = this.accumulatedContent // Empty final-turn text means the agent loop terminated without the // model emitting any assistant content (e.g. early termination after // tool calls). Mirror the fallback path's "missing structured result" // error rather than silently returning undefined. if (rawText.length === 0) { this.finalizationError = { message: 'missing structured result', code: 'structured-output-missing-result', } } else { try { const parsed: unknown = JSON.parse(rawText) // Normalize (un-widen) before storing so the synthesized // structured-output.complete chunk and the Promise result both // carry the cleaned payload. JSON.parse preserves provider nulls, so // this is where native-combined output gets its widening undone. const data = this.finalStructuredOutput.normalize ? this.finalStructuredOutput.normalize(parsed) : parsed this.structuredOutputResult = { data, rawText } } catch (err: unknown) { const detail = rawText.slice(0, 200) + (rawText.length > 200 ? '...' : '') this.finalizationError = { message: `Failed to parse structured output as JSON. Content: ${detail}`, code: 'structured-output-parse-failed', cause: err, rawText, } } } } // Validate against the Standard Schema (when supplied). Validation // failures route through onError just like the fallback path. if (this.structuredOutputResult && !this.finalizationError) { this.validateStructuredOutput( this.structuredOutputResult.data, this.structuredOutputResult.rawText, ) } if (!yieldChunks) { // Promise path: state is populated, nothing to yield. The // activity-layer caller pulls `structuredOutputResult` / // `validatedStructuredOutput` directly. return } // Streaming path: emit a synthetic `structured-output.start` if the // model produced no text at all (so the client snaps an errored // StructuredOutputPart rather than nothing). The normal path already // emitted start before the first TEXT_MESSAGE_START in // `streamModelResponse`. if (!this.combinedStartEmitted) { this.combinedStartEmitted = true const messageId = this.combinedStructuredMessageId ?? generateMessageId() this.combinedStructuredMessageId = messageId const synthStart: StreamChunk = { type: EventType.CUSTOM, name: 'structured-output.start', value: { messageId }, timestamp: Date.now(), } yield* this.emitPublicChunks( await this.middlewareRunner.runOnChunk(this.middlewareCtx, synthStart), ) } // On success, emit the synthetic `structured-output.complete` carrying // the parsed object + raw text before the deferred RUN_FINISHED. Pin // the messageId so the client targets the schema-constrained turn. if ( this.structuredOutputResult && !this.finalizationError && !this.combinedCompleteEmitted ) { const completeChunk: StreamChunk = { type: EventType.CUSTOM, name: 'structured-output.complete', value: { object: this.structuredOutputResult.data, raw: this.structuredOutputResult.rawText, ...(this.combinedStructuredMessageId ? { messageId: this.combinedStructuredMessageId } : {}), }, timestamp: Date.now(), } yield* this.emitPublicChunks( await this.middlewareRunner.runOnChunk( this.middlewareCtx, completeChunk, ), ) } // On failure, emit a synthetic RUN_ERROR so the streaming consumer's // `for await` doesn't end silently. Mirrors the fallback path. if (this.finalizationError) { const errChunk = finalizationErrorChunk(this.finalizationError) yield* this.emitPublicChunks( await this.middlewareRunner.runOnChunk(this.middlewareCtx, errChunk), ) } } private buildMiddlewareConfig(): ChatMiddlewareConfig { return { messages: this.messages, activities: this.activities, providerMessages: this.messages, systemPrompts: [...this.systemPrompts], tools: [...this.tools], resume: this.params.resume, resumeToolState: { approvals: this.resumeApprovals, clientToolResults: this.resumeClientToolResults, clientToolErrors: this.resumeClientToolErrors, deniedToolResults: this.resumeDeniedToolResults, cancelledToolCallIds: this.resumeCancelledToolCallIds, }, metadata: this.params.metadata, modelOptions: this.params.modelOptions, reasoning: this.params.reasoning, toolChoice: this.params.toolChoice, promptCache: this.params.promptCache, wrapFetch: this.params.wrapFetch, } } /** Resume entries this run answers itself. A subagent tool owns the rest. */ private ownResume( resume: ChatMiddlewareConfig['resume'], ): ChatMiddlewareConfig['resume'] { const childIds = ( this.params as { [CHILD_RESUME_IDS]?: ReadonlySet } )[CHILD_RESUME_IDS] return childIds ? resume?.filter((entry) => !childIds.has(entry.interruptId)) : resume } private async applyEphemeralInterruptResume( middlewareConfig: ChatMiddlewareConfig, ): Promise { const config = { ...middlewareConfig, resume: this.ownResume(middlewareConfig.resume), } if ((config.resume?.length ?? 0) === 0) { return } const interruptedRunId = this.parentRunIdOverride if (!interruptedRunId) { throw new InterruptResumeValidationError([ { scope: 'batch', threadId: this.threadId, interruptedRunId: this.runIdOverride ?? this.requestId, generation: 0, interruptIds: config.resume?.map((entry) => entry.interruptId) ?? [], code: 'stale', message: 'Interrupt continuation requires parentRunId to identify the interrupted run.', source: 'server', retryable: false, }, ]) } const approvalRequests: Array = [] const clientRequests: Array = [] // Prefer resume-aware reconstruction so client-tool outputs already written // into history for UI still validate against the resume batch. const pendingToolCalls = this.getToolCallsForEphemeralResume(config.resume) const resumeInterruptIds = new Set( config.resume?.map((entry) => entry.interruptId), ) const toolInputs = new Map() const toolsByCallId = new Map() const clientExecutionCallIds = new Set() for (const toolCall of pendingToolCalls) { const tool = this.tools.find( (candidate) => candidate.name === toolCall.function.name, ) if (!tool) continue toolsByCallId.set(toolCall.id, tool) let input: unknown = {} try { const parsed = JSON.parse(toolCall.function.arguments.trim() || '{}') input = parsed && typeof parsed === 'object' ? parsed : {} } catch { input = {} } toolInputs.set(toolCall.id, input) if ( !tool.execute && resumeInterruptIds.has(`client_tool_${toolCall.id}`) ) { clientExecutionCallIds.add(toolCall.id) } } // Mirror executeToolCalls' scheduling boundary. Server execution remains // gated while any approval is outstanding, but plain client tools are // represented in the same interrupt batch because requesting their output // does not execute a server-side effect. for (const toolCall of pendingToolCalls) { const tool = toolsByCallId.get(toolCall.id) if (tool?.needsApproval && !clientExecutionCallIds.has(toolCall.id)) { approvalRequests.push({ toolCallId: toolCall.id, toolName: toolCall.function.name, input: toolInputs.get(toolCall.id) ?? {}, approvalId: `approval_${toolCall.id}`, }) } } for (const toolCall of pendingToolCalls) { const tool = toolsByCallId.get(toolCall.id) if ( tool !== undefined && !tool.execute && (!tool.needsApproval || clientExecutionCallIds.has(toolCall.id)) ) { clientRequests.push({ toolCallId: toolCall.id, toolName: toolCall.function.name, input: toolInputs.get(toolCall.id) ?? {}, }) } } const genericPending = this.getGenericContinuationPending(interruptedRunId) const pending: Array<{ interruptId: string payload: unknown binding: InterruptBinding genericRequest?: GenericInterruptRequest< InterruptDefinition > }> = this.buildActionableInterrupts( approvalRequests, clientRequests, ).flatMap((descriptor) => { const unopened = readUnopenedInterruptBinding(descriptor) return unopened ? [ { interruptId: descriptor.id, payload: descriptor, binding: { ...unopened, interruptedRunId, generation: 0, } satisfies InterruptBinding, }, ] : [] }) pending.push(...genericPending) // An `mcp_input_*` answer is valid only for a server tool call that is // still pending in history. for (const toolCall of pendingToolCalls) { const interruptId = `mcp_input_${toolCall.id}` if (!resumeInterruptIds.has(interruptId)) continue if (!toolsByCallId.get(toolCall.id)?.execute) continue pending.push({ interruptId, payload: { id: interruptId }, binding: { v: INTERRUPT_BINDING_VERSION, kind: 'generic', interruptId, interruptedRunId, generation: 0, }, }) } const validated = await validateInterruptResumeBatch({ threadId: this.threadId, interruptedRunId, generation: 0, pending, resume: config.resume, tools: this.tools, }) if (validated.errors.length > 0 || !validated.resumeToolState) { throw new InterruptResumeValidationError(validated.errors) } // A client-tool execution interrupt can only be emitted after an // approval-required client tool was approved in the preceding ephemeral // run. Reconstruct that phase marker from the trusted `client_tool_*` // continuation so executeToolCalls consumes the validated client output // instead of asking for approval again. const approvals = new Map(validated.resumeToolState.approvals) for (const request of clientRequests) { if (toolsByCallId.get(request.toolCallId)?.needsApproval) { approvals.set(request.toolCallId, true) } } this.applyResumeToolState({ ...validated.resumeToolState, approvals, }) const genericResolutions = validated.resumeToolState.genericInterrupts if (genericPending.length > 0 && genericResolutions) { const resolutions = genericPending .sort((left, right) => { const leftIndex = left.binding.kind === 'generic' ? (left.binding.batchIndex ?? 0) : 0 const rightIndex = right.binding.kind === 'generic' ? (right.binding.batchIndex ?? 0) : 0 return leftIndex - rightIndex }) .flatMap((record) => { const resolution = genericResolutions.get(record.interruptId) if (!resolution || !record.genericRequest) return [] return [ resolution.status === 'resolved' ? { request: record.genericRequest, status: 'resolved' as const, response: resolution.payload, } : { request: record.genericRequest, status: 'cancelled' as const, }, ] }) const collection: InterruptResolutionCollection = { for: (definition) => resolutions.filter( (resolution) => resolution.request.definition === definition, ) as never, all: ( ...definitions: Array> ) => definitions.length === 0 ? resolutions : resolutions.filter((resolution) => definitions.includes(resolution.request.definition), ), } const policy = await this.middlewareRunner.runOnInterruptResolution( this.middlewareCtx, collection, ) if (policy.toolResume === 'stop') { this.earlyTermination = true } else if (policy.toolResume === 'cancel') { for (const request of pendingToolCalls) { if (this.resumeDeniedToolResults.has(request.id)) continue this.resumeCancelledToolCallIds.add(request.id) } } } } private getGenericContinuationPending(interruptedRunId: string): Array<{ interruptId: string payload: unknown binding: InterruptBinding genericRequest: GenericInterruptRequest< InterruptDefinition > }> { const fail = (message: string): never => { throw new InterruptResumeValidationError([ { scope: 'batch', threadId: this.threadId, interruptedRunId, generation: 0, interruptIds: [], code: 'stale', message, source: 'server', retryable: false, }, ]) } const pending: Array<{ interruptId: string payload: unknown binding: InterruptBinding genericRequest: GenericInterruptRequest< InterruptDefinition > }> = [] const ids = new Set() const batchIndexes = new Set() for (const resumeItem of this.ownResume(this.params.resume) ?? []) { const parsed = readGenericInterruptContinuation(resumeItem.metadata) if (parsed.status === 'absent') continue if (parsed.status === 'invalid') { return fail(parsed.message) } const entry = parsed.value const id = resumeItem.interruptId const definition = this.interruptDefinitions.get(entry.definitionId) if (!definition) { return fail( `Generic interrupt definition ${entry.definitionId} is unavailable.`, ) } if (ids.has(id) || batchIndexes.has(entry.batchIndex)) { return fail( 'Generic interrupt continuation contains duplicate entries.', ) } ids.add(id) batchIndexes.add(entry.batchIndex) let request: GenericInterruptRequest< InterruptDefinition > try { request = rehydrateInterruptRequest(definition, { key: entry.key, reason: entry.reason, message: entry.message, ...(typeof entry.expiresAt === 'string' ? { expiresAt: entry.expiresAt } : {}), ...(Object.prototype.hasOwnProperty.call(entry, 'payload') ? { payload: entry.payload } : {}), }) } catch (error) { return fail( `Generic interrupt continuation ${id} is invalid: ${ error instanceof Error ? error.message : String(error) }`, ) } const emitted = createInterruptBinding(request, { batchIndex: entry.batchIndex, }) if ( entry.responseSchemaHash !== emitted.descriptor.responseSchemaHash || entry.payloadSchemaHash !== emitted.descriptor.payloadSchemaHash ) { return fail( `Generic interrupt continuation ${id} does not match its definition.`, ) } pending.push({ interruptId: id, payload: { id, ...(emitted.descriptor.responseSchemaCanonicalJson !== undefined ? { responseSchema: JSON.parse( emitted.descriptor.responseSchemaCanonicalJson, ), } : {}), }, binding: { v: INTERRUPT_BINDING_VERSION, kind: 'generic', interruptId: id, interruptedRunId, generation: 0, definitionId: entry.definitionId, key: entry.key, batchIndex: entry.batchIndex, ...(typeof entry.expiresAt === 'string' ? { expiresAt: entry.expiresAt } : {}), ...(emitted.descriptor.payloadSchemaHash ? { payloadSchemaHash: emitted.descriptor.payloadSchemaHash } : {}), ...(entry.responseSchemaHash !== undefined ? { responseSchemaHash: entry.responseSchemaHash } : {}), }, genericRequest: request, }) } return pending } private applyResumeToolState(state: ChatResumeToolState | undefined): void { if (state?.approvals) { for (const [approvalId, resolution] of state.approvals) { this.resumeApprovals.set(approvalId, resolution) } } if (state?.clientToolResults) { for (const [toolCallId, result] of state.clientToolResults) { this.resumeClientToolResults.set(toolCallId, result) } } if (state?.clientToolErrors) { for (const [toolCallId, errorText] of state.clientToolErrors) { this.resumeClientToolErrors.set(toolCallId, errorText) } } if (state?.deniedToolResults) { for (const [toolCallId, result] of state.deniedToolResults) { this.resumeDeniedToolResults.set(toolCallId, result) } } if (state?.cancelledToolCallIds) { for (const toolCallId of state.cancelledToolCallIds) { this.resumeCancelledToolCallIds.add(toolCallId) } } if (state?.genericInterrupts) { for (const [interruptId, resolution] of state.genericInterrupts) { this.resumeGenericInterrupts.set(interruptId, resolution) } for (const toolCall of this.getPendingToolCallsFromMessages()) { if ( !this.tools.some( (tool) => tool.name === toolCall.function.name && tool.execute, ) ) continue const resolution = state.genericInterrupts.get( `mcp_input_${toolCall.id}`, ) if (!resolution) continue this.resumeInputResponses.set( toolCall.id, resolution.status === 'resolved' ? { status: 'resolved', payload: resolution.payload } : { status: 'cancelled' }, ) } } if (state?.genericInterruptRequests) { for (const [interruptId, request] of state.genericInterruptRequests) { this.resumeGenericInterruptRequests.set(interruptId, request) } } } private async applyDurableGenericInterruptResolution(): Promise { if (this.resumeGenericInterruptRequests.size === 0) return const resolutions = [ ...this.resumeGenericInterruptRequests.entries(), ].flatMap(([interruptId, request]) => { const resolution = this.resumeGenericInterrupts.get(interruptId) if (!resolution) return [] return [ resolution.status === 'resolved' ? { request, status: 'resolved' as const, response: resolution.payload, } : { request, status: 'cancelled' as const }, ] }) const collection: InterruptResolutionCollection = { for: (definition) => resolutions.filter( (resolution) => resolution.request.definition === definition, ) as never, all: (...definitions: Array>) => definitions.length === 0 ? resolutions : resolutions.filter((resolution) => definitions.includes(resolution.request.definition), ), } const policy = await this.middlewareRunner.runOnInterruptResolution( this.middlewareCtx, collection, ) if (policy.toolResume === 'stop') { this.earlyTermination = true } else if (policy.toolResume === 'cancel') { for (const toolCall of this.getPendingToolCallsFromMessages()) { if (this.resumeDeniedToolResults.has(toolCall.id)) continue this.resumeCancelledToolCallIds.add(toolCall.id) } } } private applyMiddlewareConfig(config: ChatMiddlewareConfig): void { this.applyResumeToolState(config.resumeToolState) this.messages = config.messages if (config.activities !== undefined) { this.setActivities(config.activities) } this.providerMessages = config.providerMessages ?? config.messages this.systemPrompts = config.systemPrompts assertUniqueToolNames(config.tools) this.tools = config.tools this.params = { ...this.params, metadata: config.metadata, modelOptions: config.modelOptions, reasoning: config.reasoning, promptCache: config.promptCache ?? this.params.promptCache, } // Not stored in params: the next call starts from the chat() option. this.callToolChoice = config.toolChoice ?? this.params.toolChoice // Not stored in params: the next call starts from the chat() option, // which the config already holds. this.callWrapFetch = config.wrapFetch // Sync context fields that depend on config this.middlewareCtx.messages = this.messages this.middlewareCtx.systemPrompts = this.systemPrompts this.middlewareCtx.hasTools = this.tools.length > 0 this.middlewareCtx.toolNames = this.tools.map((t) => t.name) this.middlewareCtx.modelOptions = config.modelOptions } /** Copy only lossless JSON raw edits. Opaque execution inputs stay untouched. */ private captureApprovedArgumentEdits( calls: ReadonlyArray, ): Map { const unsupported = Symbol('unsupported') const copy = (value: unknown, ancestors = new Set()): unknown => { if ( value === null || typeof value === 'string' || typeof value === 'boolean' ) return value if (typeof value === 'number') return Number.isFinite(value) && !Object.is(value, -0) ? value : unsupported if (typeof value !== 'object' || ancestors.has(value)) return unsupported const array = Array.isArray(value) const prototype = Object.getPrototypeOf(value) if ( array ? prototype !== Array.prototype : prototype !== Object.prototype && prototype !== null ) return unsupported const properties = Object.getOwnPropertyDescriptors(value) const keys = Reflect.ownKeys(properties) if (array && keys.length !== properties.length?.value + 1) return unsupported ancestors.add(value) const result: Record | Array = array ? [] : Object.create(null) for (const key of keys) { if (array && key === 'length') continue const property = typeof key === 'string' ? properties[key] : undefined if ( !property || !property.enumerable || !('value' in property) || (array && !/^(0|[1-9]\d*)$/.test(String(key))) ) return unsupported const copied = copy(property.value, ancestors) if (copied === unsupported) return unsupported Object.defineProperty(result, key, { value: copied, enumerable: true, configurable: true, writable: true, }) } ancestors.delete(value) return result } const snapshots = new Map() for (const call of calls) { const resolution = this.resumeApprovals.get(call.id) ?? this.resumeApprovals.get(`approval_${call.id}`) ?? this.initialApprovals.get(call.id) ?? this.initialApprovals.get(`approval_${call.id}`) if ( typeof resolution !== 'object' || !resolution.approved || // ponytail: `== null` matches `editedArgs ?? input` in executeToolCalls. resolution.editedArgs == null ) continue try { const snapshot = copy(resolution.editedArgs) if (snapshot !== unsupported) { const historyCalls = this.messages.flatMap((message) => message.role === 'assistant' ? (message.toolCalls ?? []) : [], ) const selected = historyCalls.includes(call) ? call : historyCalls .slice() .reverse() .find( (candidate) => candidate.id === call.id && candidate.function.name === call.function.name && candidate.function.arguments === call.function.arguments, ) if (selected) snapshots.set(selected, snapshot) } } catch { // An opaque value can execute without changing its JSON history. } } return snapshots } /** * Keep checked raw edits in the selected history occurrence. A call passed * the check when it waits for the client or ran with its input. A middleware * skip has no input, and a failed check is an output error. */ private retainApprovedArgumentEdits( executed: ExecuteToolCallsResult, snapshots: Map, ): void { if (snapshots.size === 0) return const selectedIds = new Set([ ...executed.results .filter( (entry) => entry.input !== undefined && entry.state !== 'output-error', ) .map((entry) => entry.toolCallId), ...executed.needsClientExecution.map((entry) => entry.toolCallId), ]) const historyCalls = this.messages.flatMap((message) => message.role === 'assistant' ? (message.toolCalls ?? []) : [], ) const update = (messages: Array): Array => { const selected = new Map() const calls = messages.flatMap((message) => message.role === 'assistant' ? (message.toolCalls ?? []) : [], ) for (const [call, snapshot] of snapshots) { if (!selectedIds.has(call.id)) continue if (calls.includes(call)) { selected.set(call, snapshot) continue } const sameCall = (candidate: ToolCall) => candidate.id === call.id && candidate.function.name === call.function.name && candidate.function.arguments === call.function.arguments const occurrence = historyCalls.filter(sameCall).indexOf(call) const equivalent = calls.filter(sameCall)[occurrence] if (equivalent) selected.set(equivalent, snapshot) } return messages.map((message) => { if (message.role !== 'assistant' || !message.toolCalls) return message let changed = false const toolCalls = message.toolCalls.map((call) => { if (!selected.has(call)) return call const argumentsJson = JSON.stringify(selected.get(call)) if (argumentsJson === undefined) return call if (argumentsJson === call.function.arguments) return call changed = true return { ...call, function: { ...call.function, arguments: argumentsJson }, } }) return changed ? { ...message, toolCalls } : message }) } this.messages = update(this.messages) this.providerMessages = update(this.providerMessages) this.middlewareCtx.messages = this.messages } private setToolPhase(phase: ToolPhaseResult): void { this.toolPhase = phase } /** * Spec-normalize middleware output, then yield to the public iterable. * Engine state and `onChunk` already saw the raw chunk, except activity * events: no caller applies those first, so they are applied here. */ private *emitPublicChunks( outputs: Array, ): Generator { for (const output of outputs) { this.recordPublicActivity(output) for (const spec of normalizeStreamChunk(output as AdapterYieldChunk)) { restorePublicUsage(spec) if (spec.type === EventType.RUN_STARTED) { if (this.hasPublicRunStarted) continue this.hasPublicRunStarted = true } // Persist MCP Apps ui-resource emissions onto the tool-call anchor // message so interrupt MESSAGES_SNAPSHOT chunks keep them (#1397). if (spec.type === EventType.CUSTOM && spec.name === 'ui-resource') { this.recordEmittedUiResource((spec as CustomEvent).value) } yield spec this.middlewareCtx.chunkIndex++ } } } /** * Pipe a single internal chunk through middleware, then spec-normalize * before the public `for await` stream. */ private async *pipeThroughMiddleware( chunk: AdapterYieldChunk, ): AsyncGenerator { const afterMw = await this.middlewareRunner.runOnChunk( this.middlewareCtx, chunk, ) yield* this.emitPublicChunks(afterMw) if (!this.drainingMiddlewareCustom) { yield* this.drainMiddlewareCustomQueue() } } /** * Drain CUSTOM chunks pushed by `ctx.emitCustomEvent` through middleware * and into the public stream. If the run has not yet sent `RUN_STARTED`, * emit that first so CUSTOM events are not the first wire event. */ private async *drainMiddlewareCustomQueue(): AsyncGenerator { if (this.drainingMiddlewareCustom) return if (this.middlewareCustomQueue.length === 0) return this.drainingMiddlewareCustom = true try { yield* this.emitSyntheticRunStarted(this.createSyntheticFinishedEvent()) while (this.middlewareCustomQueue.length > 0) { const chunk = this.middlewareCustomQueue.shift() if (chunk) yield* this.pipeThroughMiddleware(chunk) } } finally { this.drainingMiddlewareCustom = false } } /** * Await `work` while yielding any `emitCustomEvent` chunks as they arrive. */ private async *runWhileYielding( work: Promise, ): AsyncGenerator { let settled = false let result: T | undefined let error: unknown const done = work.then( (value) => { settled = true result = value }, (err: unknown) => { settled = true error = err }, ) let finished = false try { while (!settled) { yield* this.drainMiddlewareCustomQueue() if (settled) break await Promise.race([ done, new Promise((resolve) => { if (this.middlewareCustomQueue.length > 0) { resolve() return } this.middlewareCustomWaiters.push(resolve) }), ]) } yield* this.drainMiddlewareCustomQueue() finished = true } finally { // A consumer that stops at a custom event closes this generator while // the work runs. Wait for it, so no hook work outlives `onAbort`. await done // The throw below is skipped on that path, so log the error instead. if (!finished && error !== undefined) { this.logger.errors( 'middleware hook failed after the consumer stopped', { error, }, ) } } if (error !== undefined) throw error return result as T } /** * Drain queued `sandbox.file` chunks (emitted via the SandboxRuntime sink) * through the middleware pipeline and into the public stream. */ private async *drainSandboxFileQueue(): AsyncGenerator { while (this.sandboxFileQueue.length > 0) { const chunk = this.sandboxFileQueue.shift() if (chunk) yield* this.pipeThroughMiddleware(chunk) } } /** * Drain an executeToolCalls async generator, yielding any CustomEvent chunks * through the middleware pipeline and returning the final ExecuteToolCallsResult. */ private async *drainToolCallGenerator( generator: AsyncGenerator< CustomEvent | StreamChunk, { results: Array needsApproval: Array needsClientExecution: Array inputRequired: Array subagentInterrupts: Array }, void >, ): AsyncGenerator< StreamChunk, { results: Array needsApproval: Array needsClientExecution: Array inputRequired: Array subagentInterrupts: Array }, void > { let pending = generator.next() while (true) { const next = yield* this.runWhileYielding(pending) if (next.done) return next.value yield* this.pipeThroughMiddleware(next.value) pending = generator.next() } } private createCustomEventChunk( eventName: string, value: Record, options?: EmitCustomEventOptions, ): CustomEvent { const chunk: CustomEvent = { type: EventType.CUSTOM, timestamp: Date.now(), name: eventName, value, } return options?.batch ? withDurabilityBatchHint(chunk) : chunk } private createId(prefix: string): string { return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}` } } // =========================== // Activity Implementation // =========================== /** * Text activity - handles agentic text generation, one-shot text generation, and agentic structured output. * * This activity supports four modes: * 1. **Streaming agentic text**: Stream responses with automatic tool execution * 2. **Streaming one-shot text**: Simple streaming request/response without tools * 3. **Non-streaming text**: Returns a ChatResult with the text and every chunk (stream: false) * 4. **Agentic structured output**: Run tools, then return structured data * * @example Full agentic text (streaming with tools) * ```ts * import { chat } from '@tanstack/ai' * import { openaiText } from '@tanstack/ai-openai' * * for await (const chunk of chat({ * adapter: openaiText('gpt-5.5'), * messages: [{ role: 'user', content: 'What is the weather?' }], * threadId, * tools: [weatherTool] * })) { * if (chunk.type === 'TEXT_MESSAGE_CONTENT') { * console.log(chunk.delta) * } * } * ``` * * @example One-shot text (streaming without tools) * ```ts * for await (const chunk of chat({ * adapter: openaiText('gpt-5.5'), * messages: [{ role: 'user', content: 'Hello!' }], * threadId, * })) { * console.log(chunk) * } * ``` * * @example Non-streaming text (stream: false) * ```ts * const { text, chunks } = await chat({ * adapter: openaiText('gpt-5.5'), * messages: [{ role: 'user', content: 'Hello!' }], * threadId, * stream: false * }) * // text is a string with the full response * // chunks is every chunk the run produced, in order * ``` * * @example Agentic structured output (tools + structured response) * ```ts * import { z } from 'zod' * * const result = await chat({ * adapter: openaiText('gpt-5.5'), * messages: [{ role: 'user', content: 'Research and summarize the topic' }], * threadId, * tools: [researchTool, analyzeTool], * outputSchema: z.object({ * summary: z.string(), * keyPoints: z.array(z.string()) * }) * }) * // result is { summary: string, keyPoints: string[] } * ``` */ export function chat< TAdapter extends AnyTextAdapter, TSchema extends SchemaInput | undefined = undefined, TStream extends boolean = boolean, const TTools extends TextActivityOptions< TAdapter, TSchema, TStream, any >['tools'] = TextActivityOptions['tools'], const TInterrupts extends ReadonlyArray< InterruptDefinition > = [], TContext = unknown, const TMiddleware extends Array | undefined = undefined, const TAgents extends ReadonlyArray = ReadonlyArray, >( options: TextActivityOptionsWithContext< TAdapter, TSchema, TStream, TTools, TInterrupts, TContext, TMiddleware, TAgents >, ): TextActivityResult { // The type requires it, but JS callers and spreads of optional fields can // still pass nothing. Persistence and resume key on it. if (typeof options.threadId !== 'string' || options.threadId === '') { throw new Error( 'chat() needs a threadId. Pass a non-empty string, for example the id of the conversation.', ) } validateInterruptDefinitions(options.interrupts) validateCapabilities( readRuntimeMiddleware(options.middleware) ?? [], options.adapter, ) if (options.tools) { assertUniqueToolNames(options.tools) } if (options.subagents) { assertNoReservedFields( options.subagents, continuesChildren(readRuntimeMiddleware(options.middleware)), ) } const { outputSchema, stream } = options if (outputSchema && (options.subagents?.agents.length ?? 0) > 0) { throw new Error( 'chat() does not support subagents together with outputSchema. Put outputSchema on a child chat() instead.', ) } if (outputSchema && stream === true) { return runStreamingStructuredOutput( toRuntimeTextActivityOptions(options, { outputSchema, stream: true, }), ) as TextActivityResult } if (outputSchema) { return runAgenticStructuredOutput( toRuntimeTextActivityOptions(options, { outputSchema, stream: false, }), ) as TextActivityResult } if (stream === false) { return runNonStreamingText( toRuntimeTextActivityOptions(options, { outputSchema: undefined, stream: false, }), ) as TextActivityResult } return runStreamingText( toRuntimeTextActivityOptions(options, { outputSchema: undefined, stream: true, }), ) as TextActivityResult } type RuntimeTextActivityOptions< TAdapter extends AnyTextAdapter, TSchema extends SchemaInput | undefined, TStream extends boolean, > = Omit< TextActivityOptions, 'middleware' | 'promptCache' > & { middleware?: Array promptCache: ResolvedPromptCache } /** * Resolve the `promptCache` option once. The key is the option key, else the * caller's threadId. */ function resolvePromptCache(options: { promptCache?: PromptCacheOptions threadId: string }): ResolvedPromptCache { const option: Exclude | undefined = typeof options.promptCache === 'string' ? { retention: options.promptCache } : options.promptCache // `||` on purpose: an empty string is no key. const key = option?.key || options.threadId return { retention: option?.retention ?? 'short', ...(key ? { key } : {}), } } function readRuntimeMiddleware( middleware: unknown, ): Array | undefined { if (middleware === undefined) return undefined if (!Array.isArray(middleware)) { throw new TypeError('Chat middleware must be an array.') } return middleware } function toRuntimeTextActivityOptions< TAdapter extends AnyTextAdapter, TInputSchema extends SchemaInput | undefined, TInputStream extends boolean, TOutputSchema extends SchemaInput | undefined, TOutputStream extends boolean, TTools extends TextActivityOptions< TAdapter, TInputSchema, TInputStream, any >['tools'], TInterrupts extends ReadonlyArray>, TContext, TMiddleware extends Array | undefined, TAgents extends ReadonlyArray = ReadonlyArray, >( options: TextActivityOptionsWithContext< TAdapter, TInputSchema, TInputStream, TTools, TInterrupts, TContext, TMiddleware, TAgents >, overrides: { outputSchema: TOutputSchema; stream: TOutputStream }, ): RuntimeTextActivityOptions { const { middleware, ...rest } = options return { ...rest, ...overrides, promptCache: resolvePromptCache(rest), ...(middleware === undefined ? {} : { middleware: readRuntimeMiddleware(middleware) }), } } function validateInterruptDefinitions( definitions: | ReadonlyArray> | undefined, ): void { if (!definitions) return const seen = new Set() for (const definition of definitions) { if (seen.has(definition.id)) { throw new Error(`Duplicate interrupt definition id: ${definition.id}`) } seen.add(definition.id) } } /** * The slice of the engine that the durable delivery sink reaches back into, in * BOTH directions: it reads the detach verdict (`wasDetached`) and pushes the * socket-closed fact in (`notifyDisconnected`). Filled by the generator body as * soon as its engine exists. */ interface DeliveryEngineRef { current?: { wasDetached: () => boolean notifyDisconnected: () => void } } /** * Publish both delivery-side seams for `stream`. * * Shared by the two streaming paths so they cannot drift apart — the * structured-output path having been wired for one seam and not the other is * exactly the bug `publishRunDetachedSignal` picked up last time (a durable * `chat({ outputSchema, stream: true })` could never detach). */ function publishDeliverySeams( stream: object, engineRef: DeliveryEngineRef, ): void { // A thunk, evaluated on the sink's teardown path: the engine does not exist // yet, and the verdict it will report is only written during `onAbort`. publishRunDetachedSignal( stream, () => engineRef.current?.wasDetached() === true, ) // The inbound direction. Dropped if the socket closes before the body has run // far enough to have an engine, which is correct: there is no run state to // record yet, and `setup` has not begun, so nothing is leaked by not knowing. publishRunDisconnectHandler(stream, () => { engineRef.current?.notifyDisconnected() }) } /** * Run streaming text (agentic or one-shot depending on tools). * * A thin, NON-generator wrapper, because the stream object is also the key the * durable delivery sink looks the run's detach verdict up under (see * `../../delivery-detach`) and delivers its disconnect notification through (see * `../../delivery-disconnect`). A generator function cannot reach the generator it * returns, so the identity has to be minted out here and the engine reached back * through `engineRef`, which the body fills as soon as its engine exists. */ function runStreamingText( options: RuntimeTextActivityOptions, ): AsyncIterable { const engineRef: DeliveryEngineRef = {} const stream = streamTextChunks(options, engineRef) publishDeliverySeams(stream, engineRef) return stream } /** * MCP tools for one run. When the run is stopped during discovery, it returns * no tools: the engine then ends the run through its abort path, so middleware * gets `onAbort`. Other discovery errors still throw. */ async function discoverMcpTools( mcpManager: MCPManager, signal: AbortSignal | undefined, ) { try { return await mcpManager.discover(signal) } catch (error) { if (signal?.aborted) return [] throw error } } async function* runChatEngine( options: RuntimeTextActivityOptions, engineRef: DeliveryEngineRef, ): AsyncIterable { const { adapter, middleware, context, debug, mcp, subagents: _subagents, ...textOptions } = options const model = adapter.model const logger = resolveDebugOption(debug) const mcpManager = MCPManager.from(mcp) const mcpTools = await discoverMcpTools( mcpManager, options.abortController?.signal, ) if (mcpTools.length > 0) { textOptions.tools = [...(textOptions.tools ?? []), ...mcpTools] } const engine = new TextEngine( { adapter, params: { ...textOptions, model, logger } as TextOptions< Record, Record, any >, middleware, context, }, logger, ) engineRef.current = engine try { for await (const chunk of engine.run()) { yield chunk } } finally { await mcpManager.dispose() } } async function* streamTextChunks( options: RuntimeTextActivityOptions, engineRef: DeliveryEngineRef, ): AsyncIterable { // Children inherit the retention of this call. Their key is their own // threadId. The keys of this call win over the keys of a parent agent, // one provider at a time. const bag = options.subagents && { ...options.subagents, binding: { ...options.subagents.binding, ...(options.subagents.keys ? { keys: providerKeys( options.subagents.keys, options.subagents.binding?.keys, ), } : {}), promptCache: options.subagents.binding?.promptCache ?? options.promptCache.retention, }, } const agents = bag?.agents ?? [] if (bag && agents.length > 0 && bag.router) { yield* runRoutedSubagents({ ...options, subagents: bag }, engineRef) return } if (bag && agents.length > 0) { const threadId = options.threadId const runId = options.runId ?? `run-${Date.now()}` const messages = options.messages ?? [] // A resume can answer a child's interrupts. Those entries go to the child // tool call. The parent run validates only its own entries. const turn = readSubagentTurn(messages, options.resume) const sink = createSubagentSink() const calls = subagentCallMessages( new Set(bag.agents.map((agent: DefinedAgent) => agent.name)), ) const synthetic = createSyntheticSubagentTools(bag, { messages: turn?.before ?? messages, messagesFor: calls.messagesFor, childLoader: calls.childLoader, canContinue: continuesChildren(options.middleware), threadId, runId, ...(options.parentRunId !== undefined && { interruptedRunId: options.parentRunId, }), ...(options.subagentRunId !== undefined && { parentSubagentRunId: options.subagentRunId, }), ...(options.abortController && { abortSignal: options.abortController.signal, }), ...(turn && { turn }), sink, }) yield* streamWithChildUsage( runChatEngine( { ...options, threadId, runId, ...(turn && { [CHILD_RESUME_IDS]: new Set( turn.children.flatMap((child) => child.resume.map((entry) => entry.interruptId), ), ), }), tools: [...(options.tools ?? []), ...synthetic], middleware: [...(options.middleware ?? []), calls.middleware], }, engineRef, ), sink, ) return } yield* runChatEngine(options, engineRef) } /** Add child usage to the next RUN_FINISHED of the parent. */ async function* streamWithChildUsage( stream: AsyncIterable, sink: SubagentSink, ): AsyncIterable { for await (const chunk of stream) { yield chunk.type === EventType.RUN_FINISHED ? withChildUsage(chunk, sink) : chunk } } async function* runRoutedSubagents( options: RuntimeTextActivityOptions, engineRef: DeliveryEngineRef, ): AsyncIterable { const bag = options.subagents if (!bag?.router) { yield* runChatEngine(options, engineRef) return } const threadId = options.threadId const runId = options.runId ?? `run-${Date.now()}` const messages = options.messages ?? [] const turn = readSubagentTurn(messages, options.resume) if (!turn && (options.resume?.length ?? 0) > 0) { // No child owns these answers. Main raised them, after a main pick or a // handoff. Run main alone. yield* runChatEngine( { ...options, threadId, runId, subagents: undefined }, engineRef, ) return } const abortSignal = options.abortController?.signal const turnMessages = turn?.before ?? messages const subagentPersistence = readRoutedSubagentPersistence(options.middleware) await subagentPersistence?.start({ threadId, runId, messages, ...(options.resume && { resume: options.resume }), }) try { // A resume reuses the plan that the first run put on each child's // SUBAGENT_STARTED metadata. Children that finished keep their result. // Suspended children continue. const plan = (turn && savedPlan(turn.plan, bag.agents, { threadId, interruptedRunId: options.parentRunId ?? runId, interruptIds: options.resume?.map((entry) => entry.interruptId) ?? [], })) ?? normalizeRouterPick( await bag.router({ messages: turnMessages, agents: bag.agents, ...(abortSignal && { abortSignal }), }), bag.agents, ) // The run was stopped while the router decided. Start nothing. No // RUN_STARTED went out, so the stream ends without a terminal, but the // record start() opened still has to settle. Otherwise it stays `running` // and reconstructChat hands the client a run to tail that never emits. if (abortSignal?.aborted) { const error = new Error('Aborted') error.name = 'AbortError' await subagentPersistence?.abort({ threadId, runId, error }) return } // Check every input before a child starts, so a bad input in a later // step fails the turn like a bad pick. const checked = await checkRoutedInputs(plan, bag.agents) const onlyStep = plan.steps.length === 1 ? plan.steps[0] : undefined if (onlyStep?.names.length === 1 && onlyStep.names[0] === 'main') { // Earlier children own answers in this resume. Commit them first. if (turn) await subagentPersistence?.finish({ threadId, runId }) yield* runChatEngine( { ...options, threadId, runId, subagents: undefined, ...(turn && { resume: turn.rest }), }, engineRef, ) return } yield { type: EventType.RUN_STARTED, threadId, runId, timestamp: Date.now(), } const earlier = [...(turn?.children ?? [])] const takeEarlier = (name: string) => { const index = earlier.findIndex((child) => child.name === name) return index === -1 ? undefined : earlier.splice(index, 1)[0] } const sink = createSubagentSink() const stepTexts: Array = [] let stepMessages = turnMessages let failure: | Extract | undefined for (const step of checked.steps) { const entries: Array = [] const textByName = new Map() for (const name of step.names) { const prior = takeEarlier(name) if (prior?.status === 'finished') { textByName.set(name, prior.text) continue } const input = stepInput(step, name) entries.push({ name, ...(input !== undefined && { input }), ...(prior?.status === 'suspended' && { resume: { subagentRunId: prior.subagentRunId, messages: prior.messages, entries: prior.resume, text: prior.text, }, }), }) } const stepChunks: Array = [] if (entries.length > 0) { for await (const chunk of spawnNamedAgents( entries, { ...bag, order: step.order ?? bag.order }, { messages: stepMessages, ...(abortSignal && { abortSignal }), threadId, parentRunId: runId, ...(options.parentRunId !== undefined && { interruptedRunId: options.parentRunId, }), ...(options.subagentRunId !== undefined && { parentSubagentRunId: options.subagentRunId, }), }, sink, )) { const tagged = withPlan(chunk, plan) stepChunks.push(tagged) await subagentPersistence?.chunk({ threadId, runId, chunk: tagged }) yield tagged } } failure = stepChunks.find( (chunk) => chunk.type === EventType.SUBAGENT_ERROR, ) if (failure) break if (sink.interrupts.length > 0) break for (const entry of entries) { const text = collectNamedText(stepChunks, [entry.name]) textByName.set( entry.name, [entry.resume?.text, text].filter(Boolean).join('\n\n'), ) } const text = step.names .map((name) => textByName.get(name)?.trim() ?? '') .filter((block) => block !== '') .join('\n\n') if (text) { stepTexts.push(text) stepMessages = [...stepMessages, { role: 'assistant', content: text }] } } if (abortSignal?.aborted) { const error = new Error('Aborted') error.name = 'AbortError' await subagentPersistence?.abort({ threadId, runId, error }) yield withChildUsage( { type: EventType.RUN_FINISHED, threadId, runId, outcome: { type: 'cancelled' }, timestamp: Date.now(), }, sink, ) return } if (failure) { // Carry the child's own cause, not a generic label, and keep the usage // the children already spent: the run failed, but the tokens were real. const message = failure.message || 'A subagent failed' await subagentPersistence?.abort({ threadId, runId, error: new Error(message), }) yield withChildUsage( { type: EventType.RUN_ERROR, threadId, runId, message, ...(failure.code !== undefined ? { code: failure.code } : {}), timestamp: Date.now(), }, sink, ) return } if (sink.interrupts.length > 0) { const interrupts = rebindInterrupts(sink.interrupts, runId) await subagentPersistence?.suspend?.({ threadId, runId, interrupts }) yield withChildUsage( { type: EventType.RUN_FINISHED, threadId, runId, outcome: { type: 'interrupt', interrupts }, timestamp: Date.now(), }, sink, ) return } const strategy = bag.strategy ?? 'exclusive' if (strategy === 'handoff') { const childText = stepTexts.join('\n\n') // The children are done. Commit their answers and settle their records // before main runs. Main's own persistence takes over from here. await subagentPersistence?.finish({ threadId, runId }) yield* streamWithChildUsage( runChatEngine( { ...options, threadId, runId, subagents: undefined, ...(turn && { resume: turn.rest }), messages: [ ...turnMessages, { // Same id as the recorder's parent row, so the stored thread // keeps one host message for the cards. id: subagentHostMessageId(runId), role: 'assistant', content: childText || 'Subagent finished.', metadata: { tanstack: { runId } }, }, ], }, engineRef, ), sink, ) return } await subagentPersistence?.finish({ threadId, runId }) yield withChildUsage( { type: EventType.RUN_FINISHED, threadId, runId, timestamp: Date.now(), }, sink, ) } catch (error) { await subagentPersistence?.abort({ threadId, runId, error }) throw error } } /** * The plan from a resumed turn. The plan comes back from the client, so this * reads its names and order only and checks them like a router pick. A plan * that is absent, or that does not match the agents of this chat, is stale: * a new route would strand the suspended child that owns the answers, so fail * the resume instead. A plan that names an agent with `inputSchema` is stale * too: the input stays on the server, and nothing here keeps it for a resume. */ function savedPlan( plan: unknown, agents: ReadonlyArray, run: { threadId: string interruptedRunId: string interruptIds: ReadonlyArray }, ): RoutedPlan { try { if (typeof plan !== 'object' || plan === null || !('steps' in plan)) { throw new Error('The plan is absent.') } // The cast names the shape only. normalizeRouterPick checks it. const saved = plan as RoutedPlan const raw = normalizeRouterPick( { steps: saved.steps.map(({ names, order }) => ({ names, order })) }, agents, ) for (const name of raw.steps.flatMap((step) => step.names)) { if (agents.some((agent) => agent.name === name && agent.inputSchema)) { throw new Error( `Agent "${name}" got its input from the router. A turn with router inputs cannot resume.`, ) } } return raw } catch (error) { throw new InterruptResumeValidationError([ { scope: 'batch', threadId: run.threadId, interruptedRunId: run.interruptedRunId, generation: 0, interruptIds: run.interruptIds, code: 'stale', message: `The saved subagent plan does not match the agents of this chat. ${ error instanceof Error ? error.message : String(error) }`, source: 'server', retryable: false, }, ]) } } /** * Check the input of each picked agent that has `inputSchema`, and return the * plan with the checked inputs. Throws when an agent with a schema has no * input, or when an input does not match. Throws for a plain JSON Schema * too: this code cannot check an input against one. */ async function checkRoutedInputs( plan: RoutedPlan, agents: ReadonlyArray, ): Promise { const steps: Array = [] for (const step of plan.steps) { const inputs: Record = {} for (const name of step.names) { const schema = agents.find((agent) => agent.name === name)?.inputSchema if (schema === undefined) continue if (!isStandardSchema(schema)) { throw new Error( `Agent "${name}" has a plain JSON Schema as inputSchema. A router can start it only when inputSchema is a Standard Schema, such as a zod schema.`, ) } const input = stepInput(step, name) if (input === undefined) { throw new Error( `Agent "${name}" needs input. Return { name: '${name}', input } from the router.`, ) } const result = await validateWithStandardSchema(schema, input) if (!result.success) { const issues = result.issues .map((issue) => [issue.path?.join('.'), issue.message]) .map(([path, message]) => (path ? `${path}: ${message}` : message)) .join(', ') throw new Error(`Input validation failed for agent ${name}: ${issues}`) } inputs[name] = result.data } steps.push({ ...step, inputs }) } return { steps } } /** * Put the router plan on a direct child's SUBAGENT_STARTED metadata: names * and order only. The plan goes to the client, and an input stays here. */ function withPlan(chunk: StreamChunk, plan: RoutedPlan): StreamChunk { if ( chunk.type !== EventType.SUBAGENT_STARTED || chunk.parentSubagentRunId !== undefined ) { return chunk } const steps = plan.steps.map(({ names, order }) => ({ names, ...(order !== undefined && { order }), })) return withTanstackMetadata(chunk, { [SUBAGENT_PLAN_KEY]: { steps } }) } /** A middleware provides `loadChild`, so agent tools take `sessionId`. */ function continuesChildren( middleware: ReadonlyArray<{ provides?: ReadonlyArray }> | undefined, ) { return (middleware ?? []).some((item) => item.provides?.includes(LoadChildCapability), ) } function readRoutedSubagentPersistence( middleware: | ReadonlyArray<{ routedSubagentPersistence?: ChatMiddleware['routedSubagentPersistence'] }> | undefined, ) { for (const item of middleware ?? []) { if (item.routedSubagentPersistence) return item.routedSubagentPersistence } return undefined } /** * Run non-streaming text - reads the whole run and returns a ChatResult. * Runs the full agentic loop (if tools are provided) but returns the joined * text plus every chunk the run produced. */ function runNonStreamingText( options: RuntimeTextActivityOptions, ) { const stream = runStreamingText({ ...options, stream: true, }) return streamToText(stream) } /** * Run agentic structured output: * 1. Execute the full agentic loop (with tools) * 2. Once complete, call adapter.structuredOutput with the conversation context * 3. Validate and return the structured result */ async function runAgenticStructuredOutput( options: RuntimeTextActivityOptions, ): Promise> { const { adapter, outputSchema, middleware, context, debug, mcp, ...textOptions } = options const model = adapter.model const logger = resolveDebugOption(debug) if (!outputSchema) { throw new Error('outputSchema is required for structured output') } // Same strict-conversion as the streaming path (`forStructuredOutput: true`) // so the same Zod schema produces the same JSON Schema regardless of // stream mode — Promise and stream:true must not diverge here. The same // pass also records a `nullWideningMap`: optional fields are widened to // `required` + nullable for the provider, which then returns `null` for an // absent optional — a `null` the original `.optional()` (`T | undefined`) // schema would otherwise reject. The map pinpoints exactly those synthesized // nulls so `undoNullWidening` can drop them while preserving the ones a // `.nullable()` field genuinely allows. const { jsonSchema, nullWideningMap } = convertSchemaForStructuredOutput(outputSchema) if (!jsonSchema) { throw new Error('Failed to convert output schema to JSON Schema') } // Un-widening runs in the engine the moment the structured output is // captured (`finalStructuredOutput.normalize`), so it applies uniformly to // every adapter and to both stream modes — the engine is the only layer // holding the schema's `nullWideningMap`. Validation then runs on the // already-normalized data, so `validate` is a plain Standard Schema parse. const normalize = (data: unknown): unknown => undoNullWidening(data, nullWideningMap) // Validation runs INSIDE the engine (per spec §7.3) so validation failures // route through the engine's terminal-hook chooser as `onError`. We pass a // `validate` callback when the schema is a Standard Schema; otherwise we // pass through the (normalized) data and the engine returns it unchanged. const validate = isStandardSchema(outputSchema) ? (data: unknown): unknown => parseWithStandardSchema>(outputSchema, data) : undefined // Per issue #605: same capability check as the streaming path. When the // adapter handles tools + schema natively, the engine skips the separate // structured-output finalization call and harvests the JSON from the // agent loop's accumulated final-turn text. const nativeCombined = adapter.supportsCombinedToolsAndSchema?.(options.modelOptions) === true const source = adapter.combinedStructuredOutputSource?.(options.modelOptions) ?? 'text' const mcpManager = MCPManager.from(mcp) const mcpTools = await discoverMcpTools( mcpManager, options.abortController?.signal, ) if (mcpTools.length > 0) { textOptions.tools = [...(textOptions.tools ?? []), ...mcpTools] } const engine = new TextEngine( { adapter, params: { ...textOptions, model, logger } as TextOptions< Record, Record, any >, middleware, context, finalStructuredOutput: { jsonSchema, yieldChunks: false, normalize, ...(validate ? { validate } : {}), ...(nativeCombined ? { nativeCombined: true } : {}), source, }, }, logger, ) try { // Consume the stream — chunks pipe through middleware but are not yielded externally for await (const _chunk of engine.run()) { // intentionally empty } } finally { await mcpManager.dispose() } const finalizationError = engine.getFinalizationError() if (finalizationError) { const err = new Error( finalizationError.message, finalizationError.cause !== undefined ? { cause: finalizationError.cause } : undefined, ) if (finalizationError.code !== undefined) { Object.defineProperty(err, 'code', { value: finalizationError.code, enumerable: true, }) } if (finalizationError.rawText !== undefined) { Object.defineProperty(err, 'rawText', { value: finalizationError.rawText, enumerable: true, }) } throw err } // If a validator ran, return the validated value (typed by InferSchemaType // via the callback closure). Otherwise return the raw data. const validated = engine.getValidatedStructuredOutput() if (validated) { return validated.value as InferSchemaType } const result = engine.getStructuredOutputResult() if (!result) { throw new Error('structured output finalization produced no result') } return result.data as InferSchemaType } /** * Parse the `value` payload of a `structured-output.complete` CUSTOM event * into a typed shape, returning `null` if the runtime payload doesn't match. * * Uses an `unknown`-input runtime check rather than `as` casts so the engine * stays cast-free in its hot path. */ function readCustomEventMessageId(value: unknown): string | undefined { if (typeof value !== 'object' || value === null) return undefined if (!('messageId' in value)) return undefined const messageId = value.messageId return typeof messageId === 'string' && messageId !== '' ? messageId : undefined } function readStructuredOutputCompleteValue( value: unknown, ): { object: unknown; raw: string; reasoning?: string } | null { if (typeof value !== 'object' || value === null) return null if (!('object' in value) || !('raw' in value)) return null const raw = (value as { raw: unknown }).raw if (typeof raw !== 'string') return null const reasoningField = (value as { reasoning?: unknown }).reasoning const reasoning = typeof reasoningField === 'string' ? reasoningField : undefined return { object: (value as { object: unknown }).object, raw, ...(reasoning !== undefined ? { reasoning } : {}), } } /** * Synthesize a streaming structured-output stream by wrapping a non-streaming * `structuredOutput` call. Used when an adapter doesn't implement * `structuredOutputStream` natively. * * `onAdapterError`, when provided, is invoked with the raw error from * `adapter.structuredOutput` before the synthesized RUN_ERROR is yielded. * The engine uses this to preserve the original error (stack, cause, custom * properties like provider `status`/`code`) as `finalizationError.cause`, * because the RUN_ERROR wire shape only carries `message` and `code`. */ async function* fallbackStructuredOutputStream( adapter: AnyTextAdapter, options: StructuredOutputOptions>, onAdapterError?: (err: unknown) => void, ): AsyncIterable { const { chatOptions } = options // Synthesize run/message IDs. The run id only when the caller didn't supply one. // Prefix `fallback-` (not `mock-`) because this is production fallback code // used by adapters without native `structuredOutputStream`, not test fixtures. const fallbackRand = Math.random().toString(36).slice(2) const runId = chatOptions.runId ?? `fallback-${Date.now()}-${fallbackRand}` const threadId = chatOptions.threadId const messageId = `fallback-${Date.now()}-${fallbackRand}` const model = chatOptions.model const startedAt = Date.now() yield { type: EventType.RUN_STARTED, runId, threadId, model, timestamp: startedAt, } let result: StructuredOutputResult try { result = await adapter.structuredOutput(options) } catch (error) { onAdapterError?.(error) const message = error instanceof Error ? error.message : String(error) // An answer that is not JSON gets the same code as on the engine's own // parse path. ponytail: only a SyntaxError (or one as `cause`) is known // as a parse failure; an adapter that throws a plain Error keeps no code. const parseFailed = error instanceof SyntaxError || (error instanceof Error && error.cause instanceof SyntaxError) const code = parseFailed ? 'structured-output-parse-failed' : undefined const usage = readErrorUsage(error) yield { type: EventType.RUN_ERROR, runId, threadId, model, timestamp: Date.now(), message, ...(code ? { code } : {}), ...(usage ? { usage } : {}), error: { message, ...(code ? { code } : {}) }, } return } yield { type: EventType.TEXT_MESSAGE_START, messageId, role: 'assistant', model, timestamp: Date.now(), } yield { type: EventType.TEXT_MESSAGE_CONTENT, messageId, delta: result.rawText, model, timestamp: Date.now(), } yield { type: EventType.TEXT_MESSAGE_END, messageId, model, timestamp: Date.now(), } yield { type: EventType.CUSTOM, name: 'structured-output.complete', value: { object: result.data, raw: result.rawText }, model, timestamp: Date.now(), } yield { type: EventType.RUN_FINISHED, runId, threadId, model: result.model ?? model, ...(result.responseId !== undefined ? { responseId: result.responseId } : {}), timestamp: Date.now(), finishReason: 'stop', // Forward adapter-reported token usage so consumers reading // `RUN_FINISHED.usage` (and the engine's `runOnUsage` middleware hook) see // it on the fallback path, mirroring the native streaming path. The // conditional spread avoids emitting `usage: undefined` for adapters that // don't report it. See #758. ...(result.usage ? { usage: result.usage } : {}), } } /** * Run streaming structured output via the TextEngine, with the engine's * `finalStructuredOutput.yieldChunks: true` mode. The agent loop's * RUN_STARTED/RUN_FINISHED are suppressed; the structured-output finalization * step's pair brackets the run for the consumer. * * A Standard Schema checks the assembled value, as on the Promise path * (`runAgenticStructuredOutput`). Partial JSON deltas are not checked. A * value that fails the check ends the stream with RUN_ERROR * `structured-output-validation-failed`, with the model text as * `metadata.tanstack.rawText`, and routes through `onError`. A plain JSON Schema is not * checked. See `docs/structured-outputs/overview.md`. * * Null-widening normalization also runs on both paths: the * `structured-output.complete` CUSTOM event is forwarded with its `value.object` * already un-widened (synthesized strict-mode nulls dropped, genuine * `.nullable()` nulls kept), so a consumer validating the assembled object * against the original schema doesn't choke on a `null` for an `.optional()` * field. Same `convertSchemaForStructuredOutput` pass and same * `undoNullWidening` map as the Promise path — the two must not diverge. * * Pre-flight validation (missing schema, unconvertible schema) throws * synchronously at call time rather than as a yielded RUN_ERROR mid-stream — * those are programmer errors, not runtime conditions. */ function runStreamingStructuredOutput( options: RuntimeTextActivityOptions, ): StructuredOutputStream> { const { outputSchema } = options if (!outputSchema) { throw new Error('outputSchema is required for streaming structured output') } // forStructuredOutput strict-converts the schema once at the activity // boundary, capturing the null-widening map so the engine can un-widen the // provider's response before it reaches the consumer. Adapters can re-convert // if their wire format diverges, but the default flow hands them a // strict-ready schema. const { jsonSchema, nullWideningMap } = convertSchemaForStructuredOutput(outputSchema) if (!jsonSchema) { throw new Error('Failed to convert output schema to JSON Schema') } const normalize = (data: unknown): unknown => undoNullWidening(data, nullWideningMap) // The implementation generator yields the broader internal type // (`StreamChunk | StructuredOutputCompleteEvent`) so middleware and // tool-emitted CustomEvents can flow through. Core approval/client-tool // waits are represented by RUN_FINISHED interrupt outcomes, not by direct // CUSTOM wait events. // The contained cast keeps the public stream type focused on // structured-output completion. // // Same seam as `runStreamingText`: this wrapper is NOT a generator, so the // stream identity can be minted here and the engine reached back through // `engineRef` once the impl body has its engine. Without this a durable // structured-output stream could never detach — the sink would find no verdict // and terminalize a healthy detached run's log — nor survive a disconnect. const engineRef: DeliveryEngineRef = {} const stream = runStreamingStructuredOutputImpl( options, jsonSchema, normalize, engineRef, ) publishDeliverySeams(stream, engineRef) return stream as StructuredOutputStream> } /** * The RUN_ERROR of a failed structured-output finalization. A parse or * schema failure keeps the model text as `rawText` (public chunks have it as * `metadata.tanstack.rawText`), as the Promise path keeps it on the thrown * error. */ function finalizationErrorChunk(failure: { message: string code?: string rawText?: string usage?: TokenUsage }): StreamChunk { const { message, code, rawText, usage } = failure return { type: EventType.RUN_ERROR, timestamp: Date.now(), message, ...(code ? { code } : {}), ...(rawText !== undefined ? { rawText } : {}), ...(usage ? { usage } : {}), } } /** * Internal generator return type — broader than the public * `StructuredOutputStream`. The structured-output completion event remains * the pinned public CUSTOM event for this stream; approval and client-tool * waits now surface as RUN_FINISHED interrupt outcomes. At runtime, tools can * still emit arbitrary user-defined `CustomEvent`s through the * `emitCustomEvent` context API; those flow * through this generator with `name: string` and are widened out at the * public boundary because keeping them would collapse the typed narrow back * to `any`. The cast inside `runStreamingStructuredOutput` is where that * widening happens. */ type StructuredOutputStreamInternal = AsyncIterable< StreamChunk | StructuredOutputCompleteEvent > async function* runStreamingStructuredOutputImpl( options: RuntimeTextActivityOptions, jsonSchema: NonNullable>, normalize: (data: unknown) => unknown, engineRef: DeliveryEngineRef, ): StructuredOutputStreamInternal> { const { adapter, outputSchema, middleware, context, debug, mcp, ...textOptions } = options const model = adapter.model const logger = resolveDebugOption(debug) // Per issue #605: adapters that natively combine tools + schema-constrained // output in one streaming call (modern OpenAI, Anthropic 4.5+, Gemini 3+, // Grok 4+) opt in via `supportsCombinedToolsAndSchema()`. The engine then // forwards the schema into the regular `chatStream` call and harvests the // structured result from the agent loop's accumulated text — no separate // finalization round-trip, and the `'structuredOutput'` middleware phase // does not fire. const nativeCombined = adapter.supportsCombinedToolsAndSchema?.(options.modelOptions) === true const source = adapter.combinedStructuredOutputSource?.(options.modelOptions) ?? 'text' // The same check as the Promise path. A value that fails a Standard Schema // ends the stream with RUN_ERROR `structured-output-validation-failed`. const validate = isStandardSchema(outputSchema) ? (data: unknown): unknown => parseWithStandardSchema(outputSchema, data) : undefined const mcpManager = MCPManager.from(mcp) const mcpTools = await discoverMcpTools( mcpManager, options.abortController?.signal, ) if (mcpTools.length > 0) { textOptions.tools = [...(textOptions.tools ?? []), ...mcpTools] } // Inputs may be UIMessages (from useChat) or ModelMessages (from server-side // callers). TextEngine handles the conversion uniformly. const engine = new TextEngine( { adapter, params: { ...textOptions, model, logger } as TextOptions< Record, Record, any >, middleware, context, finalStructuredOutput: { jsonSchema, yieldChunks: true, normalize, ...(validate ? { validate } : {}), ...(nativeCombined ? { nativeCombined: true } : {}), source, }, }, logger, ) engineRef.current = engine try { for await (const chunk of engine.run()) { yield chunk } } finally { await mcpManager.dispose() } } // Re-export adapter types export type { TextAdapter, TextAdapterConfig, StructuredOutputOptions, StructuredOutputResult, } from './adapter' export { BaseTextAdapter } from './adapter'