@tanstack/ai 0.46.0 → 0.47.1

package/src/activities/chat/index.ts

@@ -14,10 +14,21 @@ 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,
@@ -47,6 +58,7 @@ import {
   convertMessagesToModelMessages,
   generateMessageId,
   modelMessageToUIMessage,
+  safeJsonStringify,
 } from './messages'
 import { MiddlewareRunner } from './middleware/compose'
 import { getRunDetached } from './middleware/run-store'
@@ -89,6 +101,7 @@ import type {
   SchemaInput,
   StreamChunk,
   StructuredOutputCompleteEvent,
+  StructuredOutputPart,
   StructuredOutputStream,
   TextMessageContentEvent,
   TextOptions,
@@ -104,10 +117,13 @@ import type {
   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'
@@ -204,74 +220,11 @@ function normalizePublicInterruptBinding(
   value: unknown,
   expectedInterruptId: string,
 ): InterruptBinding | undefined {
-  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-    return undefined
-  }
-  const binding: Record<string, unknown> = Object.fromEntries(
-    Object.entries(value),
-  )
-  if (
-    binding.interruptId !== expectedInterruptId ||
-    // A binding version we don't recognise belongs to another producer. Drop
-    // it rather than reading our fields out of it.
-    (binding.v !== undefined && binding.v !== INTERRUPT_BINDING_VERSION) ||
-    typeof binding.interruptedRunId !== 'string' ||
-    typeof binding.generation !== 'number' ||
-    !Number.isInteger(binding.generation) ||
-    binding.generation < 0 ||
-    typeof binding.responseSchemaHash !== 'string' ||
-    (binding.expiresAt !== undefined && typeof binding.expiresAt !== 'string')
-  ) {
-    return undefined
-  }
-  const base = {
-    v: INTERRUPT_BINDING_VERSION,
-    interruptId: binding.interruptId,
-    interruptedRunId: binding.interruptedRunId,
-    generation: binding.generation,
-    responseSchemaHash: binding.responseSchemaHash,
-    ...(typeof binding.expiresAt === 'string'
-      ? { expiresAt: binding.expiresAt }
-      : {}),
-  }
-  if (binding.kind === 'generic') {
-    return { kind: binding.kind, ...base }
-  }
-  if (
-    typeof binding.toolName !== 'string' ||
-    typeof binding.toolCallId !== 'string'
-  ) {
-    return undefined
-  }
-  if (
-    binding.kind === 'client-tool-execution' &&
-    typeof binding.outputSchemaHash === 'string'
-  ) {
-    return {
-      kind: binding.kind,
-      ...base,
-      toolName: binding.toolName,
-      toolCallId: binding.toolCallId,
-      outputSchemaHash: binding.outputSchemaHash,
-    }
-  }
-  if (
-    binding.kind === 'tool-approval' &&
-    Object.prototype.hasOwnProperty.call(binding, 'originalArgs') &&
-    typeof binding.inputSchemaHash === 'string' &&
-    typeof binding.approvalSchemaHash === 'string'
-  ) {
-    return {
-      kind: binding.kind,
-      ...base,
-      toolName: binding.toolName,
-      toolCallId: binding.toolCallId,
-      originalArgs: binding.originalArgs,
-      inputSchemaHash: binding.inputSchemaHash,
-      approvalSchemaHash: binding.approvalSchemaHash,
-    }
-  }
-  return undefined
+  return readInterruptBinding({
+    id: expectedInterruptId,
+    reason: '',
+    metadata: { [INTERRUPT_BINDING_METADATA_KEY]: value },
+  })
 }
 
 // The leaf context-inference primitives (KnownContext, MergeContext,
@@ -310,33 +263,133 @@ type InferredContext<TTools, TMiddleware> = [
   ? unknown
   : ContextFromInputs<TTools, TMiddleware>
 
-type RequiredContextFromInputs<TTools, TMiddleware> = [
-  ContextFromInputs<TTools, TMiddleware>,
+type RegistryInterrupt<
+  TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>>,
+> = [TInterrupts[number]] extends [never] ? never : TInterrupts[number]
+
+type DuplicateInterruptDefinitionId<
+  TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>>,
+  TSeenIds extends string = never,
+> = TInterrupts extends readonly [infer THead, ...infer TTail]
+  ? THead extends InterruptDefinition<infer TId, any, any, any>
+    ? string extends TId
+      ? TTail extends ReadonlyArray<InterruptDefinition<any, any, any, any>>
+        ? DuplicateInterruptDefinitionId<TTail, TSeenIds>
+        : never
+      : TId extends TSeenIds
+        ? TId
+        : TTail extends ReadonlyArray<InterruptDefinition<any, any, any, any>>
+          ? DuplicateInterruptDefinitionId<TTail, TSeenIds | TId>
+          : never
+    : never
+  : never
+
+type CheckUniqueInterruptDefinitions<
+  TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>>,
+> = [DuplicateInterruptDefinitionId<TInterrupts>] extends [never]
+  ? unknown
+  : {
+      readonly '✖ Duplicate interrupt definition id in chat({ interrupts }).': never
+    }
+
+type InlineChatContext<TTools, TContext> = MergeContext<
+  ContextFromArray<NonNullable<TTools>>,
+  TContext
+>
+
+type RegistryChatMiddleware<
+  TContext,
+  TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>>,
+> = ChatMiddleware<TContext, RegistryInterrupt<TInterrupts>>
+
+type MiddlewareInterruptDefinitions<TMiddleware> =
+  TMiddleware extends ReadonlyArray<infer TMiddlewareItem>
+    ? TMiddlewareItem extends ChatMiddleware<any, infer TDefinitions>
+      ? TDefinitions
+      : never
+    : never
+
+type IsAny<TValue> = 0 extends 1 & TValue ? true : false
+
+type CheckInterruptRegistry<
+  TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>>,
+  TMiddleware,
+> =
+  IsAny<MiddlewareInterruptDefinitions<TMiddleware>> extends true
+    ? unknown
+    : [MiddlewareInterruptDefinitions<TMiddleware>] extends [never]
+      ? unknown
+      : [
+            Exclude<
+              MiddlewareInterruptDefinitions<TMiddleware>,
+              RegistryInterrupt<TInterrupts>
+            >,
+          ] extends [never]
+        ? unknown
+        : {
+            readonly '✖ Middleware emits an interrupt definition that is not registered in chat({ interrupts }).': never
+          }
+
+type RuntimeContextOption<TTools, TMiddleware, TContext> = [
+  MergeContext<ContextFromInputs<TTools, TMiddleware>, TContext>,
 ] extends [never]
-  ? { context?: unknown }
-  : undefined extends ContextFromInputs<TTools, TMiddleware>
-    ? { context?: ContextFromInputs<TTools, TMiddleware> }
-    : { context: ContextFromInputs<TTools, TMiddleware> }
+  ? { context?: TContext }
+  : undefined extends MergeContext<
+        ContextFromInputs<TTools, TMiddleware>,
+        TContext
+      >
+    ? {
+        context?: MergeContext<ContextFromInputs<TTools, TMiddleware>, TContext>
+      }
+    : {
+        context: MergeContext<ContextFromInputs<TTools, TMiddleware>, TContext>
+      }
+
+type ExactMiddlewareOption<
+  TTools,
+  TContext,
+  TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>>,
+  TMiddleware extends Array<unknown> | undefined,
+> = [TMiddleware] extends [undefined]
+  ? Array<
+      RegistryChatMiddleware<
+        InlineChatContext<TTools, TContext>,
+        NoInfer<TInterrupts>
+      >
+    >
+  : TMiddleware &
+      (TMiddleware extends Array<
+        RegistryChatMiddleware<
+          InlineChatContext<TTools, NoInfer<TContext>>,
+          NoInfer<TInterrupts>
+        >
+      >
+        ? Array<
+            RegistryChatMiddleware<
+              InlineChatContext<TTools, TContext>,
+              NoInfer<TInterrupts>
+            >
+          >
+        : CheckInterruptRegistry<TInterrupts, TMiddleware>) &
+      CheckCoverage<Extract<TMiddleware, ReadonlyArray<AnyChatMiddleware>>>
 
 type TextActivityOptionsWithContext<
   TAdapter extends AnyTextAdapter,
   TSchema extends SchemaInput | undefined,
   TStream extends boolean,
   TTools extends TextActivityOptions<TAdapter, TSchema, TStream, any>['tools'],
-  TMiddleware extends TextActivityOptions<
-    TAdapter,
-    TSchema,
-    TStream,
-    any
-  >['middleware'],
+  TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> =
+    [],
+  TContext = unknown,
+  TMiddleware extends Array<unknown> | undefined = undefined,
 > = Omit<
   TextActivityOptions<TAdapter, TSchema, TStream, any>,
-  'tools' | 'middleware' | 'context'
+  'tools' | 'middleware' | 'context' | 'interrupts'
 > & {
   tools?: TTools
-  middleware?: TMiddleware &
-    CheckCoverage<Extract<TMiddleware, ReadonlyArray<AnyChatMiddleware>>>
-} & RequiredContextFromInputs<TTools, TMiddleware>
+  interrupts?: TInterrupts & CheckUniqueInterruptDefinitions<TInterrupts>
+  middleware?: ExactMiddlewareOption<TTools, TContext, TInterrupts, TMiddleware>
+} & RuntimeContextOption<TTools, TMiddleware, TContext>
 
 // ===========================
 // Activity Options Type
@@ -494,6 +547,11 @@ export interface TextActivityOptions<
    * ```
    */
   middleware?: Array<ChatMiddleware<TContext>>
+  /**
+   * First-party generic interrupt definitions for this chat call.
+   * Register the same definitions on the client to type payloads and answers.
+   */
+  interrupts?: ReadonlyArray<InterruptDefinition<any, any, any, any>>
   /**
    * Runtime context value passed to middleware hooks and server tools.
    */
@@ -534,28 +592,21 @@ export function createChatOptions<
     TStream,
     any
   >['tools'] = TextActivityOptions<TAdapter, TSchema, TStream, any>['tools'],
-  const TMiddleware extends TextActivityOptions<
-    TAdapter,
-    TSchema,
-    TStream,
-    any
-  >['middleware'] = TextActivityOptions<
-    TAdapter,
-    TSchema,
-    TStream,
-    any
-  >['middleware'],
+  const TInterrupts extends ReadonlyArray<
+    InterruptDefinition<any, any, any, any>
+  > = [],
+  TContext = unknown,
+  const TMiddleware extends Array<unknown> | undefined = undefined,
 >(
   options: TextActivityOptionsWithContext<
     TAdapter,
     TSchema,
     TStream,
     TTools,
+    TInterrupts,
+    TContext,
     TMiddleware
   >,
-  // Preserve the concrete `tools` tuple on the returned options (so a later
-  // `chat({ ...opts })` still narrows tool-call events to the tool names)
-  // while threading the inferred runtime context like the bare options type.
 ): Omit<
   TextActivityOptions<
     TAdapter,
@@ -563,8 +614,12 @@ export function createChatOptions<
     TStream,
     InferredContext<TTools, TMiddleware>
   >,
-  'tools'
-> & { tools?: TTools } {
+  'tools' | 'middleware' | 'interrupts'
+> & {
+  tools?: TTools
+  interrupts?: TInterrupts
+  middleware?: ExactMiddlewareOption<TTools, TContext, TInterrupts, TMiddleware>
+} {
   return options
 }
 
@@ -628,7 +683,7 @@ interface TextEngineConfig<
   adapter: TAdapter
   systemPrompts?: Array<SystemPrompt>
   params: TParams
-  middleware?: Array<ChatMiddleware<TContext>>
+  middleware?: Array<AnyChatMiddleware>
   context?: TContext
   /**
    * If set, after the agent loop finishes the engine runs a
@@ -712,12 +767,18 @@ class TextEngine<
   >,
 > {
   private readonly adapter: TAdapter
+  private readonly interruptDefinitions: ReadonlyMap<
+    string,
+    InterruptDefinition<any, any, any, any>
+  >
   private params: TParams
   private systemPrompts: Array<SystemPrompt>
   private tools: Array<AnyRuntimeTool>
   private readonly loopStrategy: AgentLoopStrategy
   private toolCallManager: ToolCallManager<ReadonlyArray<AnyTool>, 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
@@ -749,6 +810,9 @@ class TextEngine<
   private finishedEvent: RunFinishedEvent | null = null
   private readonly streamedToolErrorResults = new Map<string, ToolResult>()
   private deferredToolCallRunFinishedChunks: Array<StreamChunk> = []
+  /** The model terminal is held until afterModel can choose an interrupt. */
+  private deferredModelRunFinishedChunks: Array<StreamChunk> = []
+
   private earlyTermination = false
   private toolPhase: ToolPhaseResult = 'continue'
   private cyclePhase: CyclePhase = 'processText'
@@ -759,6 +823,14 @@ class TextEngine<
   private readonly resumeClientToolResults = new Map<string, any>()
   private readonly resumeDeniedToolResults = new Map<string, unknown>()
   private readonly resumeCancelledToolCallIds = new Set<string>()
+  private readonly resumeGenericInterrupts = new Map<
+    string,
+    ChatResumeGenericResolution
+  >()
+  private readonly resumeGenericInterruptRequests = new Map<
+    string,
+    GenericInterruptRequest<InterruptDefinition<any, any, any, any>>
+  >()
 
   // AG-UI protocol IDs
   private readonly threadId: string
@@ -766,7 +838,10 @@ class TextEngine<
   private readonly parentRunIdOverride?: string
 
   // Middleware support
-  private readonly middlewareRunner: MiddlewareRunner<TContext>
+  private readonly middlewareRunner: MiddlewareRunner<
+    TContext,
+    InterruptDefinition<any, any, any, any>
+  >
   private readonly middlewareCtx: ChatMiddlewareContext<TContext>
   private readonly sandboxFileQueue: Array<StreamChunk> = []
   private readonly deferredPromises: Array<Promise<unknown>> = []
@@ -788,8 +863,13 @@ class TextEngine<
   private readonly logger: InternalLogger
 
   // Structured-output finalization state (populated by runStructuredFinalization)
-  private structuredOutputResult: { data: unknown; rawText: string } | null =
-    null
+  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
@@ -826,6 +906,15 @@ class TextEngine<
   ) {
     this.logger = logger
     this.adapter = config.adapter
+    this.interruptDefinitions = new Map(
+      (
+        (
+          config.params as TParams & {
+            interrupts?: ReadonlyArray<InterruptDefinition<any, any, any, any>>
+          }
+        ).interrupts ?? []
+      ).map((definition) => [definition.id, definition]),
+    )
     this.finalStructuredOutput = config.finalStructuredOutput
     this.params = config.params
     this.systemPrompts = config.params.systemPrompts || []
@@ -878,7 +967,9 @@ class TextEngine<
     // handleStreamChunk processes raw chunks BEFORE middleware, so internal
     // state management sees extended fields (finishReason, delta, toolCallName, etc.).
     // The strip middleware ensures the yielded public stream is AG-UI spec-compliant.
-    const allMiddleware: Array<ChatMiddleware<TContext>> = [
+    const allMiddleware: Array<
+      ChatMiddleware<TContext, InterruptDefinition<any, any, any, any>>
+    > = [
       devtoolsMiddleware(),
       ...(config.middleware || []),
       stripToSpecMiddleware(),
@@ -957,6 +1048,10 @@ class TextEngine<
       },
     })
 
+    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
@@ -1048,10 +1143,25 @@ class TextEngine<
       )
       this.applyMiddlewareConfig(transformedConfig)
       await this.applyEphemeralInterruptResume(transformedConfig)
+      await this.applyDurableGenericInterruptResolution()
 
       // Run onStart (devtools middleware emits text:request:started and initial messages here)
       await 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: this.finishedEvent?.usage,
+          })
+        }
+        return
+      }
+
       const pendingPhase = yield* this.checkForPendingToolCalls()
       if (pendingPhase === 'wait') {
         return
@@ -1095,7 +1205,35 @@ class TextEngine<
               )
             this.applyMiddlewareConfig(iterTransformedConfig)
 
+            if (
+              yield* this.emitBoundaryInterrupts(
+                'beforeModel',
+                this.createSyntheticFinishedEvent(),
+              )
+            ) {
+              this.setToolPhase('wait')
+              return
+            }
+
             yield* this.streamModelResponse()
+
+            if (
+              yield* this.emitBoundaryInterrupts(
+                'afterModel',
+                this.finishedEvent ?? this.createSyntheticFinishedEvent(),
+              )
+            ) {
+              this.setToolPhase('wait')
+              return
+            }
+            if (this.shouldExecuteToolPhase()) {
+              this.deferredToolCallRunFinishedChunks.push(
+                ...this.deferredModelRunFinishedChunks,
+              )
+              this.deferredModelRunFinishedChunks = []
+            } else {
+              yield* this.flushDeferredModelRunFinishedChunks()
+            }
           } else {
             yield* this.processToolCalls()
           }
@@ -1159,7 +1297,7 @@ class TextEngine<
             duration: Date.now() - this.streamStartTime,
           })
         } else {
-          this.addTerminalReasoningMessage()
+          this.addTerminalAssistantMessages()
           this.terminalHookCalled = true
           await this.middlewareRunner.runOnFinish(this.middlewareCtx, {
             finishReason: this.lastFinishReason,
@@ -1403,6 +1541,7 @@ class TextEngine<
           typeof startValue.messageId === 'string'
         ) {
           this.combinedStructuredMessageId = startValue.messageId
+          this.captureStructuredOutputMessageIdentity(startValue.messageId)
         }
       }
 
@@ -1420,6 +1559,11 @@ class TextEngine<
           this.structuredOutputResult = { data: object, rawText: parsed.raw }
           this.combinedCompleteEmitted = true
           const value = chunk.value
+          const completeMessageId = readCustomEventMessageId(value)
+          if (completeMessageId) {
+            this.combinedStructuredMessageId = completeMessageId
+            this.captureStructuredOutputMessageIdentity(completeMessageId)
+          }
           if (object !== parsed.object && value && typeof value === 'object') {
             outboundChunk = { ...chunk, value: { ...value, object } }
           }
@@ -1482,10 +1626,17 @@ class TextEngine<
         ) {
           continue
         }
+        if (outputChunk.type === EventType.RUN_FINISHED) {
+          this.deferredModelRunFinishedChunks.push(outputChunk)
+          continue
+        }
         if (this.shouldDeferToolCallRunFinished(outputChunk)) {
           this.deferredToolCallRunFinishedChunks.push(outputChunk)
           continue
         }
+        if (outputChunk.type === EventType.RUN_STARTED) {
+          this.hasPublicRunStarted = true
+        }
         this.logger.output(`type=${outputChunk.type}`, { chunk: outputChunk })
         yield outputChunk
         this.middlewareCtx.chunkIndex++
@@ -1586,6 +1737,11 @@ class TextEngine<
     }
   }
 
+  private captureStructuredOutputMessageIdentity(messageId: string): void {
+    this.structuredOutputMessageId = messageId
+    this.structuredOutputMessageCreatedAt ??= new Date()
+  }
+
   private handleToolCallStartEvent(chunk: ToolCallStartEvent): void {
     if (
       typeof chunk.parentMessageId === 'string' &&
@@ -1763,6 +1919,18 @@ class TextEngine<
       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(
@@ -1930,6 +2098,17 @@ class TextEngine<
     }
     this.middlewareCtx.phase = 'beforeTools'
 
+    if (
+      yield* this.emitBoundaryInterrupts(
+        'beforeTools',
+        finishEvent,
+        executableToolCalls,
+      )
+    ) {
+      this.setToolPhase('wait')
+      return
+    }
+
     const { approvals, clientToolResults } = this.collectClientState()
 
     const generator = executeToolCalls(
@@ -1997,15 +2176,36 @@ class TextEngine<
       needsClientExecution: executionResult.needsClientExecution,
     })
 
+    const afterToolBoundaryChunks = this.buildToolResultChunks(
+      allResults,
+      finishEvent,
+    )
+    const afterToolRequests =
+      await this.middlewareRunner.runOnInterruptBoundary(
+        this.middlewareCtx as ChatMiddlewareContext<TContext> & {
+          phase: 'afterTools'
+        },
+      )
+    if (afterToolRequests.length > 0) {
+      for (const chunk of afterToolBoundaryChunks) {
+        yield* this.pipeThroughMiddleware(chunk)
+      }
+      yield* this.emitBoundaryInterrupts(
+        'afterTools',
+        finishEvent,
+        toolCalls,
+        afterToolRequests,
+      )
+      this.setToolPhase('wait')
+      return
+    }
+
     if (
       executionResult.needsApproval.length > 0 ||
       executionResult.needsClientExecution.length > 0
     ) {
       if (allResults.length > 0) {
-        for (const chunk of this.buildToolResultChunks(
-          allResults,
-          finishEvent,
-        )) {
+        for (const chunk of afterToolBoundaryChunks) {
           yield* this.pipeThroughMiddleware(chunk)
         }
       }
@@ -2021,7 +2221,7 @@ class TextEngine<
 
     yield* this.flushDeferredToolCallRunFinishedChunks()
 
-    const toolResultChunks = this.buildToolResultChunks(allResults, finishEvent)
+    const toolResultChunks = afterToolBoundaryChunks
 
     for (const chunk of toolResultChunks) {
       yield* this.pipeThroughMiddleware(chunk)
@@ -2061,6 +2261,48 @@ class TextEngine<
     this.deferredToolCallRunFinishedChunks = []
   }
 
+  private *flushDeferredModelRunFinishedChunks(): Generator<StreamChunk> {
+    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<StreamChunk, void, void> {
+    if (this.hasPublicRunStarted) return
+    yield* this.pipeThroughMiddleware({
+      type: EventType.RUN_STARTED,
+      runId: finishEvent.runId,
+      threadId: finishEvent.threadId,
+      model: finishEvent.model,
+      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(),
+      finishReason: 'stop' as const,
+    }
+    yield* this.emitSyntheticRunStarted(finishEvent)
+    yield* this.pipeThroughMiddleware({
+      ...finishEvent,
+      timestamp: Date.now(),
+      outcome: { type: 'success' },
+    })
+  }
+
   private discardDeferredToolCallRunFinishedChunks(): void {
     this.deferredToolCallRunFinishedChunks = []
   }
@@ -2092,27 +2334,104 @@ class TextEngine<
     this.middlewareCtx.messages = this.messages
   }
 
-  private addTerminalReasoningMessage(): void {
+  private addTerminalAssistantMessages(): void {
     this.finalizeCurrentThinkingStep()
-    if (this.accumulatedThinking.length === 0) return
 
-    const messages = this.middlewareCtx.messages
-    const alreadyPresent = messages.some(
+    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,
     )
-    if (alreadyPresent) return
+    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] = {
+          ...existing,
+          content: raw || existing.content,
+          structuredOutput,
+        }
+      }
+    } else if (structuredOutput && !splitStructuredMessage) {
+      if (!currentTurnAlreadyRecorded) {
+        messages.push({
+          role: 'assistant',
+          content: this.accumulatedContent || raw || null,
+          id: structuredId,
+          createdAt:
+            this.currentMessageCreatedAt ??
+            this.structuredOutputMessageCreatedAt ??
+            new Date(),
+          structuredOutput,
+          ...(thinking ? { thinking } : {}),
+        })
+      }
+    } else {
+      if (
+        !currentTurnAlreadyRecorded &&
+        (this.accumulatedContent !== '' || thinking)
+      ) {
+        messages.push({
+          role: 'assistant',
+          content: this.accumulatedContent || null,
+          id: this.currentMessageId ?? this.createId('msg'),
+          createdAt: this.currentMessageCreatedAt ?? new Date(),
+          ...(thinking ? { thinking } : {}),
+        })
+      }
+      if (structuredOutput) {
+        messages.push({
+          role: 'assistant',
+          content: raw || null,
+          id: structuredId,
+          createdAt: this.structuredOutputMessageCreatedAt ?? new Date(),
+          structuredOutput,
+        })
+      }
+    }
 
-    this.messages = [
-      ...messages,
-      {
-        role: 'assistant',
-        content: this.accumulatedContent || null,
-        id: this.currentMessageId ?? undefined,
-        createdAt: this.currentMessageCreatedAt ?? undefined,
-        thinking: this.accumulatedThinking,
-      },
-    ]
+    if (messages.length === startedLength && existingStructuredIndex < 0) {
+      return
+    }
+
+    this.messages = messages
     this.middlewareCtx.messages = this.messages
   }
 
@@ -2206,9 +2525,17 @@ class TextEngine<
     return { approvals, clientToolResults }
   }
 
+  private genericInterruptId(): string {
+    return this.createId('interrupt')
+  }
+
   private buildActionableInterrupts(
     approvals: Array<ApprovalRequest>,
     clientRequests: Array<ClientToolRequest>,
+    genericRequests: ReadonlyArray<
+      GenericInterruptRequest<InterruptDefinition<any, any, any, any>>
+    > = [],
+    genericInterruptIds: ReadonlyArray<string> = [],
   ): Array<Interrupt> {
     const interrupts: Array<Interrupt> = []
 
@@ -2278,6 +2605,64 @@ class TextEngine<
       })
     }
 
+    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 }
+            : {}),
+        },
+      })
+    }
+
+    const ids = new Set<string>()
+    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
   }
 
@@ -2285,13 +2670,22 @@ class TextEngine<
     finishEvent: RunFinishedEvent,
     approvals: Array<ApprovalRequest>,
     clientRequests: Array<ClientToolRequest>,
+    genericRequests: ReadonlyArray<
+      GenericInterruptRequest<InterruptDefinition<any, any, any, any>>
+    > = [],
+    genericInterruptIds?: ReadonlyArray<string>,
   ): StreamChunk {
     return {
       ...finishEvent,
       timestamp: Date.now(),
       outcome: {
         type: 'interrupt',
-        interrupts: this.buildActionableInterrupts(approvals, clientRequests),
+        interrupts: this.buildActionableInterrupts(
+          approvals,
+          clientRequests,
+          genericRequests,
+          genericInterruptIds,
+        ),
       },
     }
   }
@@ -2309,7 +2703,8 @@ class TextEngine<
           message.id ||
           `snapshot_${this.runIdOverride ?? this.requestId}_${index}`
         const parts =
-          message.role === 'assistant' && message.thinking?.length
+          message.role === 'assistant' &&
+          (message.thinking?.length || message.structuredOutput)
             ? modelMessageToUIMessage(message, id).parts
             : undefined
         return {
@@ -2440,9 +2835,22 @@ class TextEngine<
     finishEvent: RunFinishedEvent,
     approvals: Array<ApprovalRequest>,
     clientRequests: Array<ClientToolRequest>,
+    genericRequests: ReadonlyArray<
+      GenericInterruptRequest<InterruptDefinition<any, any, any, any>>
+    > = [],
   ): AsyncGenerator<StreamChunk, boolean, void> {
+    yield* this.emitSyntheticRunStarted(finishEvent)
+    const genericInterruptIds = genericRequests.map(() =>
+      this.genericInterruptId(),
+    )
     const terminal = this.completeEphemeralInterruptBindings(
-      this.buildInterruptFinishedChunk(finishEvent, approvals, clientRequests),
+      this.buildInterruptFinishedChunk(
+        finishEvent,
+        approvals,
+        clientRequests,
+        genericRequests,
+        genericInterruptIds,
+      ),
     )
     let terminalOutputs: Array<StreamChunk>
     try {
@@ -2471,6 +2879,103 @@ class TextEngine<
     return true
   }
 
+  private async *emitBoundaryInterrupts(
+    phase: 'beforeModel' | 'afterModel' | 'beforeTools' | 'afterTools',
+    finishEvent: RunFinishedEvent,
+    toolCalls: ReadonlyArray<ToolCall> = [],
+    requests?: ReadonlyArray<
+      GenericInterruptRequest<InterruptDefinition<any, any, any, any>>
+    >,
+  ): AsyncGenerator<StreamChunk, boolean, void> {
+    this.middlewareCtx.phase = phase
+    const boundaryRequests =
+      requests ??
+      (await this.middlewareRunner.runOnInterruptBoundary(
+        this.middlewareCtx as ChatMiddlewareContext<TContext> & {
+          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.addAssistantTextMessageForInterrupt()
+      }
+    }
+    const actionable = this.getBoundaryActionableToolRequests(toolCalls)
+    yield* this.emitActionableInterruptBoundary(
+      finishEvent,
+      actionable.approvals,
+      actionable.clientRequests,
+      boundaryRequests,
+    )
+    return true
+  }
+
+  private addAssistantTextMessageForInterrupt(): void {
+    if (this.accumulatedContent.length === 0) return
+    this.messages = [
+      ...this.messages,
+      { role: 'assistant', content: this.accumulatedContent },
+    ]
+    this.middlewareCtx.messages = this.messages
+  }
+
+  private getBoundaryActionableToolRequests(
+    toolCalls: ReadonlyArray<ToolCall>,
+  ): {
+    approvals: Array<ApprovalRequest>
+    clientRequests: Array<ClientToolRequest>
+  } {
+    const { approvals, clientToolResults } = this.collectClientState()
+    const approvalRequests: Array<ApprovalRequest> = []
+    const clientRequests: Array<ClientToolRequest> = []
+    for (const toolCall of toolCalls) {
+      const tool = this.resolveExecutableTools([toolCall]).find(
+        (candidate) => candidate.name === toolCall.function.name,
+      ) as RuntimeToolWithApproval | undefined
+      if (!tool) continue
+      let input: unknown = {}
+      try {
+        const parsed = JSON.parse(toolCall.function.arguments.trim() || '{}')
+        input = parsed && typeof parsed === 'object' ? parsed : {}
+      } catch {
+        input = {}
+      }
+      const approvalId = `approval_${toolCall.id}`
+      if (tool.needsApproval && !approvals.has(approvalId)) {
+        approvalRequests.push({
+          toolCallId: toolCall.id,
+          toolName: toolCall.function.name,
+          input,
+          approvalId,
+        })
+      } else if (
+        !tool.execute &&
+        !clientToolResults.has(toolCall.id) &&
+        !this.resumeCancelledToolCallIds.has(toolCall.id)
+      ) {
+        clientRequests.push({
+          toolCallId: toolCall.id,
+          toolName: toolCall.function.name,
+          input,
+        })
+      }
+    }
+    return { approvals: approvalRequests, clientRequests }
+  }
+
   private completeEphemeralInterruptBindings(chunk: StreamChunk): StreamChunk {
     if (
       chunk.type !== EventType.RUN_FINISHED ||
@@ -2718,7 +3223,7 @@ class TextEngine<
   private createSyntheticFinishedEvent(): RunFinishedEvent {
     return {
       type: 'RUN_FINISHED',
-      runId: this.createId('pending'),
+      runId: this.runIdOverride ?? this.requestId,
       threadId: this.threadId,
       model: this.params.model,
       timestamp: Date.now(),
@@ -2997,6 +3502,7 @@ class TextEngine<
     const buildSynthesizedStart = (timestamp = Date.now()): StreamChunk => {
       const idForStart = structuredMessageId ?? generateMessageId()
       structuredMessageId = idForStart
+      this.captureStructuredOutputMessageIdentity(idForStart)
       return {
         type: EventType.CUSTOM,
         name: 'structured-output.start',
@@ -3037,7 +3543,10 @@ class TextEngine<
       // synthesized start (when needed) uses the SAME id the deltas carry
       if (!structuredMessageId) {
         const extracted = extractMessageId(chunk)
-        if (extracted) structuredMessageId = extracted
+        if (extracted) {
+          structuredMessageId = extracted
+          this.captureStructuredOutputMessageIdentity(extracted)
+        }
       }
 
       // Synthesis only matters for the streaming client path — the agentic
@@ -3104,7 +3613,13 @@ class TextEngine<
           const object = this.finalStructuredOutput.normalize
             ? this.finalStructuredOutput.normalize(parsed.object)
             : parsed.object
-          this.structuredOutputResult = { data: object, rawText: parsed.raw }
+          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` —
@@ -3555,7 +4070,15 @@ class TextEngine<
       }
     }
 
-    const pending = this.buildActionableInterrupts(
+    const genericPending = this.getGenericContinuationPending(interruptedRunId)
+    const pending: Array<{
+      interruptId: string
+      payload: unknown
+      binding: InterruptBinding
+      genericRequest?: GenericInterruptRequest<
+        InterruptDefinition<any, any, any, any>
+      >
+    }> = this.buildActionableInterrupts(
       approvalRequests,
       clientRequests,
     ).flatMap((descriptor) => {
@@ -3574,6 +4097,7 @@ class TextEngine<
           ]
         : []
     })
+    pending.push(...genericPending)
     const validated = await validateInterruptResumeBatch({
       threadId: this.threadId,
       interruptedRunId,
@@ -3601,6 +4125,185 @@ class TextEngine<
       ...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<InterruptDefinition<any, any, any, any>>
+        ) =>
+          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) {
+          this.resumeCancelledToolCallIds.add(request.id)
+        }
+      }
+    }
+  }
+
+  private getGenericContinuationPending(interruptedRunId: string): Array<{
+    interruptId: string
+    payload: unknown
+    binding: InterruptBinding
+    genericRequest: GenericInterruptRequest<
+      InterruptDefinition<any, any, any, any>
+    >
+  }> {
+    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<any, any, any, any>
+      >
+    }> = []
+    const ids = new Set<string>()
+    const batchIndexes = new Set<number>()
+    for (const resumeItem of 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<any, any, any, any>
+      >
+      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 {
@@ -3624,6 +4327,58 @@ class TextEngine<
         this.resumeCancelledToolCallIds.add(toolCallId)
       }
     }
+    if (state?.genericInterrupts) {
+      for (const [interruptId, resolution] of state.genericInterrupts) {
+        this.resumeGenericInterrupts.set(interruptId, resolution)
+      }
+    }
+    if (state?.genericInterruptRequests) {
+      for (const [interruptId, request] of state.genericInterruptRequests) {
+        this.resumeGenericInterruptRequests.set(interruptId, request)
+      }
+    }
+  }
+
+  private async applyDurableGenericInterruptResolution(): Promise<void> {
+    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<InterruptDefinition<any, any, any, any>>) =>
+        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()) {
+        this.resumeCancelledToolCallIds.add(toolCall.id)
+      }
+    }
   }
 
   private applyMiddlewareConfig(config: ChatMiddlewareConfig): void {
@@ -3662,6 +4417,9 @@ class TextEngine<
       chunk,
     )
     for (const outputChunk of outputChunks) {
+      if (outputChunk.type === EventType.RUN_STARTED) {
+        this.hasPublicRunStarted = true
+      }
       yield outputChunk
       this.middlewareCtx.chunkIndex++
     }
@@ -3802,67 +4560,136 @@ export function chat<
     TStream,
     any
   >['tools'] = TextActivityOptions<TAdapter, TSchema, TStream, any>['tools'],
-  const TMiddleware extends TextActivityOptions<
-    TAdapter,
-    TSchema,
-    TStream,
-    any
-  >['middleware'] = TextActivityOptions<
-    TAdapter,
-    TSchema,
-    TStream,
-    any
-  >['middleware'],
+  const TInterrupts extends ReadonlyArray<
+    InterruptDefinition<any, any, any, any>
+  > = [],
+  TContext = unknown,
+  const TMiddleware extends Array<unknown> | undefined = undefined,
 >(
   options: TextActivityOptionsWithContext<
     TAdapter,
     TSchema,
     TStream,
     TTools,
+    TInterrupts,
+    TContext,
     TMiddleware
   >,
 ): TextActivityResult<TSchema, TStream, TTools> {
-  validateCapabilities(options.middleware ?? [], options.adapter)
+  validateInterruptDefinitions(options.interrupts)
+  validateCapabilities(
+    readRuntimeMiddleware(options.middleware) ?? [],
+    options.adapter,
+  )
   if (options.tools) {
     assertUniqueToolNames(options.tools)
   }
 
   const { outputSchema, stream } = options
 
-  // outputSchema + stream:true is the only branch that streams structured
-  // output. Without an explicit `stream: true`, schema-bearing calls run the
-  // agent loop and resolve to a typed Promise<InferSchemaType<TSchema>>.
   if (outputSchema && stream === true) {
-    return runStreamingStructuredOutput({
-      ...options,
-      outputSchema,
-      stream,
-    }) as TextActivityResult<TSchema, TStream, TTools>
+    return runStreamingStructuredOutput(
+      toRuntimeTextActivityOptions(options, {
+        outputSchema,
+        stream: true,
+      }),
+    ) as TextActivityResult<TSchema, TStream, TTools>
   }
 
-  // If outputSchema is provided, run agentic structured output (Promise<T>)
   if (outputSchema) {
-    return runAgenticStructuredOutput({
-      ...options,
-      outputSchema,
-    }) as TextActivityResult<TSchema, TStream, TTools>
+    return runAgenticStructuredOutput(
+      toRuntimeTextActivityOptions(options, {
+        outputSchema,
+        stream: false,
+      }),
+    ) as TextActivityResult<TSchema, TStream, TTools>
   }
 
-  // If stream is explicitly false, run non-streaming text
   if (stream === false) {
-    return runNonStreamingText({
-      ...options,
+    return runNonStreamingText(
+      toRuntimeTextActivityOptions(options, {
+        outputSchema: undefined,
+        stream: false,
+      }),
+    ) as TextActivityResult<TSchema, TStream, TTools>
+  }
+
+  return runStreamingText(
+    toRuntimeTextActivityOptions(options, {
       outputSchema: undefined,
-      stream,
-    }) as TextActivityResult<TSchema, TStream, TTools>
+      stream: true,
+    }),
+  ) as TextActivityResult<TSchema, TStream, TTools>
+}
+
+type RuntimeTextActivityOptions<
+  TAdapter extends AnyTextAdapter,
+  TSchema extends SchemaInput | undefined,
+  TStream extends boolean,
+> = Omit<TextActivityOptions<TAdapter, TSchema, TStream, any>, 'middleware'> & {
+  middleware?: Array<AnyChatMiddleware>
+}
+
+function readRuntimeMiddleware(
+  middleware: unknown,
+): Array<AnyChatMiddleware> | undefined {
+  if (middleware === undefined) return undefined
+  if (!Array.isArray(middleware)) {
+    throw new TypeError('Chat middleware must be an array.')
   }
+  return middleware
+}
 
-  // Otherwise, run streaming text (default)
-  return runStreamingText({
-    ...options,
-    outputSchema: undefined,
-    stream,
-  }) as TextActivityResult<TSchema, TStream, TTools>
+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<InterruptDefinition<any, any, any, any>>,
+  TContext,
+  TMiddleware extends Array<unknown> | undefined,
+>(
+  options: TextActivityOptionsWithContext<
+    TAdapter,
+    TInputSchema,
+    TInputStream,
+    TTools,
+    TInterrupts,
+    TContext,
+    TMiddleware
+  >,
+  overrides: { outputSchema: TOutputSchema; stream: TOutputStream },
+): RuntimeTextActivityOptions<TAdapter, TOutputSchema, TOutputStream> {
+  const { middleware, ...rest } = options
+  return {
+    ...rest,
+    ...overrides,
+    ...(middleware === undefined
+      ? {}
+      : { middleware: readRuntimeMiddleware(middleware) }),
+  }
+}
+
+function validateInterruptDefinitions(
+  definitions:
+    | ReadonlyArray<InterruptDefinition<any, any, any, any>>
+    | undefined,
+): void {
+  if (!definitions) return
+  const seen = new Set<string>()
+  for (const definition of definitions) {
+    if (seen.has(definition.id)) {
+      throw new Error(`Duplicate interrupt definition id: ${definition.id}`)
+    }
+    seen.add(definition.id)
+  }
 }
 
 /**
@@ -3914,8 +4741,8 @@ function publishDeliverySeams(
  * 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<TContext = unknown>(
-  options: TextActivityOptions<AnyTextAdapter, undefined, true, TContext>,
+function runStreamingText(
+  options: RuntimeTextActivityOptions<AnyTextAdapter, undefined, boolean>,
 ): AsyncIterable<StreamChunk> {
   const engineRef: DeliveryEngineRef = {}
   const stream = streamTextChunks(options, engineRef)
@@ -3923,8 +4750,8 @@ function runStreamingText<TContext = unknown>(
   return stream
 }
 
-async function* streamTextChunks<TContext = unknown>(
-  options: TextActivityOptions<AnyTextAdapter, undefined, true, TContext>,
+async function* streamTextChunks(
+  options: RuntimeTextActivityOptions<AnyTextAdapter, undefined, boolean>,
   engineRef: DeliveryEngineRef,
 ): AsyncIterable<StreamChunk> {
   const { adapter, middleware, context, debug, mcp, ...textOptions } = options
@@ -3943,7 +4770,7 @@ async function* streamTextChunks<TContext = unknown>(
       params: { ...textOptions, model, logger } as TextOptions<
         Record<string, any>,
         Record<string, any>,
-        TContext
+        any
       >,
       middleware,
       context,
@@ -3965,19 +4792,13 @@ async function* streamTextChunks<TContext = unknown>(
  * Run non-streaming text - collects all content and returns as a string.
  * Runs the full agentic loop (if tools are provided) but returns collected text.
  */
-function runNonStreamingText<TContext = unknown>(
-  options: TextActivityOptions<AnyTextAdapter, undefined, false, TContext>,
+function runNonStreamingText(
+  options: RuntimeTextActivityOptions<AnyTextAdapter, undefined, false>,
 ): Promise<string> {
-  // Run the streaming text and collect all text using streamToText.
-  const stream = runStreamingText(
-    // oxlint-disable-next-line eslint-js/no-restricted-syntax -- generic-stream remap: caller is non-streaming (false), but runStreamingText is invoked internally to collect text; concrete `false`→`true` literals don't structurally overlap.
-    options as unknown as TextActivityOptions<
-      AnyTextAdapter,
-      undefined,
-      true,
-      TContext
-    >,
-  )
+  const stream = runStreamingText({
+    ...options,
+    stream: true,
+  })
 
   return streamToText(stream)
 }
@@ -3988,11 +4809,8 @@ function runNonStreamingText<TContext = unknown>(
  * 2. Once complete, call adapter.structuredOutput with the conversation context
  * 3. Validate and return the structured result
  */
-async function runAgenticStructuredOutput<
-  TSchema extends SchemaInput,
-  TContext = unknown,
->(
-  options: TextActivityOptions<AnyTextAdapter, TSchema, boolean, TContext>,
+async function runAgenticStructuredOutput<TSchema extends SchemaInput>(
+  options: RuntimeTextActivityOptions<AnyTextAdapter, TSchema, boolean>,
 ): Promise<InferSchemaType<TSchema>> {
   const {
     adapter,
@@ -4063,7 +4881,7 @@ async function runAgenticStructuredOutput<
       params: { ...textOptions, model, logger } as TextOptions<
         Record<string, unknown>,
         Record<string, unknown>,
-        TContext
+        any
       >,
       middleware,
       context,
@@ -4126,6 +4944,15 @@ async function runAgenticStructuredOutput<
  * 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 {
@@ -4271,11 +5098,8 @@ async function* fallbackStructuredOutputStream(
  * synchronously at call time rather than as a yielded RUN_ERROR mid-stream —
  * those are programmer errors, not runtime conditions.
  */
-function runStreamingStructuredOutput<
-  TSchema extends SchemaInput,
-  TContext = unknown,
->(
-  options: TextActivityOptions<AnyTextAdapter, TSchema, true, TContext>,
+function runStreamingStructuredOutput<TSchema extends SchemaInput>(
+  options: RuntimeTextActivityOptions<AnyTextAdapter, TSchema, true>,
 ): StructuredOutputStream<InferSchemaType<TSchema>> {
   const { outputSchema } = options
 
@@ -4336,11 +5160,8 @@ type StructuredOutputStreamInternal<T> = AsyncIterable<
   StreamChunk | StructuredOutputCompleteEvent<T>
 >
 
-async function* runStreamingStructuredOutputImpl<
-  TSchema extends SchemaInput,
-  TContext = unknown,
->(
-  options: TextActivityOptions<AnyTextAdapter, TSchema, true, TContext>,
+async function* runStreamingStructuredOutputImpl<TSchema extends SchemaInput>(
+  options: RuntimeTextActivityOptions<AnyTextAdapter, TSchema, true>,
   jsonSchema: NonNullable<ReturnType<typeof convertSchemaToJsonSchema>>,
   normalize: (data: unknown) => unknown,
   engineRef: DeliveryEngineRef,
@@ -4383,7 +5204,7 @@ async function* runStreamingStructuredOutputImpl<
       params: { ...textOptions, model, logger } as TextOptions<
         Record<string, unknown>,
         Record<string, unknown>,
-        TContext
+        any
       >,
       middleware,
       context,