@tanstack/ai 0.46.0 → 0.47.2

package/src/activities/chat/messages.ts

@@ -4,6 +4,7 @@ import type {
   ContentPart,
   MessagePart,
   ModelMessage,
+  StructuredOutputPart,
   TextPart,
   ToolCallPart,
   UIMessage,
@@ -26,9 +27,9 @@ function isContentPart(part: MessagePart): part is ContentPart {
   )
 }
 
-function safeJsonStringify(value: unknown): string {
+export function safeJsonStringify(value: unknown): string {
   try {
-    return JSON.stringify(value)
+    return JSON.stringify(value) ?? ''
   } catch {
     return ''
   }
@@ -196,6 +197,7 @@ function buildUserOrToolMessage(uiMessage: UIMessage): ModelMessage {
 // Accumulator for building an assistant segment (content + tool calls)
 interface AssistantSegment {
   contentParts: Array<ContentPart>
+  structuredOutput?: StructuredOutputPart
   toolCalls: Array<{
     id: string
     type: 'function'
@@ -255,6 +257,9 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
         content,
         ...(hasToolCalls && { toolCalls: current.toolCalls }),
         ...(pendingThinking.length > 0 && { thinking: pendingThinking }),
+        ...(current.structuredOutput && {
+          structuredOutput: current.structuredOutput,
+        }),
         ...(uiMessage.createdAt !== undefined && {
           createdAt: uiMessage.createdAt,
         }),
@@ -333,6 +338,7 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
                 : ''
           if (serialized !== '') {
             current.contentParts.push({ type: 'text', content: serialized })
+            current.structuredOutput = part
           }
         }
         break
@@ -445,7 +451,9 @@ export function modelMessageToUIMessage(
 
   // Handle tool results (when role is "tool") - only produce tool-result part,
   // not a text part (the content IS the tool result, not display text)
-  if (modelMessage.role === 'tool' && modelMessage.toolCallId) {
+  if (modelMessage.role === 'assistant' && modelMessage.structuredOutput) {
+    parts.push(modelMessage.structuredOutput)
+  } else if (modelMessage.role === 'tool' && modelMessage.toolCallId) {
     parts.push({
       type: 'tool-result',
       toolCallId: modelMessage.toolCallId,

package/src/activities/chat/middleware/builder.ts

@@ -1,6 +1,9 @@
 import type { CapabilityHandle } from './capabilities'
 import type { AnyChatMiddleware, ChatMiddleware } from './types'
 import type { DefinedChatMiddleware } from './define'
+import type { InterruptDefinition } from '../../../interrupt-definition'
+
+type AnyInterruptDefinition = InterruptDefinition<any, any, any, any>
 
 /** Union of capability NAME literals from a tuple of handles. */
 export type NamesOf<T extends ReadonlyArray<CapabilityHandle>> =
@@ -67,19 +70,41 @@ export type CheckCoverage<TList extends ReadonlyArray<AnyChatMiddleware>> = [
 export interface ChatMiddlewareBuilder<
   TList extends ReadonlyArray<AnyChatMiddleware>,
   TProvided extends string,
+  TInterruptDefinitions extends AnyInterruptDefinition = never,
 > {
   use: <
     TRequires extends ReadonlyArray<CapabilityHandle>,
     TProvides extends ReadonlyArray<CapabilityHandle>,
     TContext = unknown,
+    TMiddlewareInterruptDefinitions extends AnyInterruptDefinition =
+      TInterruptDefinitions,
   >(
     middleware: [NamesOf<TRequires>] extends [TProvided]
-      ? DefinedChatMiddleware<TContext, TRequires, TProvides>
-      : DefinedChatMiddleware<TContext, TRequires, TProvides> &
+      ? DefinedChatMiddleware<
+          TContext,
+          TRequires,
+          TProvides,
+          TMiddlewareInterruptDefinitions
+        >
+      : DefinedChatMiddleware<
+          TContext,
+          TRequires,
+          TProvides,
+          TMiddlewareInterruptDefinitions
+        > &
           MissingCapabilities<Exclude<NamesOf<TRequires>, TProvided>>,
   ) => ChatMiddlewareBuilder<
-    readonly [...TList, DefinedChatMiddleware<TContext, TRequires, TProvides>],
-    TProvided | NamesOf<TProvides>
+    readonly [
+      ...TList,
+      DefinedChatMiddleware<
+        TContext,
+        TRequires,
+        TProvides,
+        TMiddlewareInterruptDefinitions
+      >,
+    ],
+    TProvided | NamesOf<TProvides>,
+    TInterruptDefinitions | TMiddlewareInterruptDefinitions
   >
 
   build: () => [...TList]

package/src/activities/chat/middleware/compose.ts

@@ -10,6 +10,9 @@ import type {
   ChatMiddlewareContext,
   ErrorInfo,
   FinishInfo,
+  InterruptBoundaryPhase,
+  InterruptResolutionCollection,
+  InterruptToolResume,
   IterationInfo,
   SandboxFileHookEvent,
   StructuredOutputMiddlewareConfig,
@@ -17,6 +20,10 @@ import type {
   ToolPhaseCompleteInfo,
   UsageInfo,
 } from './types'
+import type {
+  GenericInterruptRequest,
+  InterruptDefinition,
+} from '../../../interrupt-definition'
 
 /** One middleware's terminal-hook throw, captured instead of propagated. */
 interface HookFailure {
@@ -25,7 +32,7 @@ interface HookFailure {
 }
 
 /** Check if a middleware should be skipped for instrumentation events. */
-function shouldSkipInstrumentation(mw: ChatMiddleware<any>): boolean {
+function shouldSkipInstrumentation(mw: ChatMiddleware<any, any>): boolean {
   return mw.name === 'devtools' || mw.name === 'strip-to-spec'
 }
 
@@ -43,12 +50,18 @@ function instrumentCtx(ctx: ChatMiddlewareContext<any>) {
  * Internal middleware runner that manages composed execution of middleware hooks.
  * Created once per chat() invocation.
  */
-export class MiddlewareRunner<TContext = unknown> {
-  private readonly middlewares: ReadonlyArray<ChatMiddleware<TContext>>
+export class MiddlewareRunner<
+  TContext = unknown,
+  TInterruptDefinitions extends InterruptDefinition<any, any, any, any> =
+    InterruptDefinition<any, any, any, any>,
+> {
+  private readonly middlewares: ReadonlyArray<
+    ChatMiddleware<TContext, TInterruptDefinitions>
+  >
   private readonly logger: InternalLogger
 
   constructor(
-    middlewares: ReadonlyArray<ChatMiddleware<TContext>>,
+    middlewares: ReadonlyArray<ChatMiddleware<TContext, TInterruptDefinitions>>,
     logger: InternalLogger,
   ) {
     this.middlewares = middlewares
@@ -59,6 +72,83 @@ export class MiddlewareRunner<TContext = unknown> {
     return this.middlewares.length > 0
   }
 
+  async runOnInterruptBoundary(
+    ctx: ChatMiddlewareContext<TContext> & { phase: InterruptBoundaryPhase },
+  ): Promise<ReadonlyArray<GenericInterruptRequest<TInterruptDefinitions>>> {
+    const requests: Array<GenericInterruptRequest<TInterruptDefinitions>> = []
+    for (const mw of this.middlewares) {
+      if (mw.onInterruptBoundary) {
+        const skip = shouldSkipInstrumentation(mw)
+        const start = Date.now()
+        const result = await mw.onInterruptBoundary(ctx)
+        if (result?.interrupts) requests.push(...result.interrupts)
+        if (!skip) {
+          this.logger.middleware(
+            `hook=onInterruptBoundary middleware=${mw.name ?? 'unnamed'}`,
+            {
+              middleware: mw.name ?? 'unnamed',
+              hook: 'onInterruptBoundary',
+            },
+          )
+          aiEventClient.emit('middleware:hook:executed', {
+            ...instrumentCtx(ctx),
+            middlewareName: mw.name || 'unnamed',
+            hookName: 'onInterruptBoundary',
+            iteration: ctx.iteration,
+            duration: Date.now() - start,
+            hasTransform: result?.interrupts !== undefined,
+          })
+        }
+      }
+    }
+    return requests
+  }
+
+  async runOnInterruptResolution(
+    ctx: ChatMiddlewareContext<TContext>,
+    resolutions: InterruptResolutionCollection<TInterruptDefinitions>,
+  ): Promise<{ toolResume?: InterruptToolResume }> {
+    let toolResume: InterruptToolResume | undefined
+    for (const mw of this.middlewares) {
+      if (mw.onInterruptResolution) {
+        const skip = shouldSkipInstrumentation(mw)
+        const start = Date.now()
+        const next = await mw.onInterruptResolution(ctx, resolutions)
+        if (next?.toolResume !== undefined) {
+          const priority: Record<InterruptToolResume, number> = {
+            continue: 0,
+            cancel: 1,
+            stop: 2,
+          }
+          if (
+            toolResume === undefined ||
+            priority[next.toolResume] > priority[toolResume]
+          ) {
+            toolResume = next.toolResume
+          }
+        }
+        if (!skip) {
+          this.logger.middleware(
+            `hook=onInterruptResolution middleware=${mw.name ?? 'unnamed'}`,
+            {
+              middleware: mw.name ?? 'unnamed',
+              hook: 'onInterruptResolution',
+            },
+          )
+          aiEventClient.emit('middleware:hook:executed', {
+            ...instrumentCtx(ctx),
+            middlewareName: mw.name || 'unnamed',
+            hookName: 'onInterruptResolution',
+            iteration: ctx.iteration,
+            duration: Date.now() - start,
+            hasTransform: next !== undefined,
+          })
+        }
+      }
+    }
+    return toolResume === undefined ? {} : { toolResume }
+  }
+
   /**
    * Pipe config through all middleware onConfig hooks in order.
    * Each middleware receives the merged config from previous middleware.
@@ -492,7 +582,7 @@ export class MiddlewareRunner<TContext = unknown> {
    * {@link runOnError}.
    */
   private async captureTerminalHook(
-    mw: ChatMiddleware<TContext>,
+    mw: ChatMiddleware<TContext, TInterruptDefinitions>,
     hookName: 'onFinish' | 'onAbort' | 'onError',
     invoke: () => void | Promise<void>,
   ): Promise<HookFailure | undefined> {

package/src/activities/chat/middleware/define.ts

@@ -1,5 +1,8 @@
 import type { CapabilityHandle } from './capabilities'
 import type { ChatMiddleware } from './types'
+import type { InterruptDefinition } from '../../../interrupt-definition'
+
+type AnyInterruptDefinition = InterruptDefinition<any, any, any, any>
 
 /**
  * A middleware whose `requires`/`provides` tuple types are captured precisely
@@ -9,7 +12,8 @@ export interface DefinedChatMiddleware<
   TContext,
   TRequires extends ReadonlyArray<CapabilityHandle>,
   TProvides extends ReadonlyArray<CapabilityHandle>,
-> extends ChatMiddleware<TContext> {
+  TInterruptDefinitions extends AnyInterruptDefinition = never,
+> extends ChatMiddleware<TContext, TInterruptDefinitions> {
   requires?: TRequires
   provides?: TProvides
 }
@@ -24,11 +28,17 @@ export function defineChatMiddleware<
   TContext = unknown,
   const TRequires extends ReadonlyArray<CapabilityHandle> = readonly [],
   const TProvides extends ReadonlyArray<CapabilityHandle> = readonly [],
+  TInterruptDefinitions extends AnyInterruptDefinition = never,
 >(
-  middleware: ChatMiddleware<TContext> & {
+  middleware: ChatMiddleware<TContext, TInterruptDefinitions> & {
     requires?: TRequires
     provides?: TProvides
   },
-): DefinedChatMiddleware<TContext, TRequires, TProvides> {
+): DefinedChatMiddleware<
+  TContext,
+  TRequires,
+  TProvides,
+  TInterruptDefinitions
+> {
   return middleware
 }

package/src/activities/chat/middleware/generic-interrupts.ts

@@ -0,0 +1,26 @@
+import { createCapability } from './capabilities'
+import type { InterruptDefinition } from '../../../interrupt-definition'
+
+/**
+ * Internal per-run registry of first-party generic interrupt definitions.
+ *
+ * Persistence uses this bridge while restoring a durable interrupt. It never
+ * receives a definition from the stored record; it can only look up one that
+ * the current chat call registered.
+ */
+export interface GenericInterruptDefinitionRegistry {
+  readonly definitions: ReadonlyMap<
+    string,
+    InterruptDefinition<any, any, any, any>
+  >
+}
+
+export const GenericInterruptDefinitionRegistryCapability =
+  createCapability<GenericInterruptDefinitionRegistry>()(
+    'generic-interrupt-definition-registry',
+  )
+
+export const [
+  getGenericInterruptDefinitionRegistry,
+  provideGenericInterruptDefinitionRegistry,
+] = GenericInterruptDefinitionRegistryCapability

package/src/activities/chat/middleware/index.ts

@@ -18,8 +18,23 @@ export type {
   SandboxFileEvent,
   SandboxFileHookEvent,
   ChatSandboxHooks,
+  InterruptBoundaryPhase,
+  InterruptToolResume,
+  InterruptResolutionCollection,
+  GenericInterruptResolution,
+  InterruptBoundaryResult,
+  InterruptResolutionResult,
 } from './types'
 
+export { INTERRUPT_BOUNDARY_PHASES, INTERRUPT_TOOL_RESUMES } from './types'
+
+export {
+  GenericInterruptDefinitionRegistryCapability,
+  getGenericInterruptDefinitionRegistry,
+  provideGenericInterruptDefinitionRegistry,
+} from './generic-interrupts'
+export type { GenericInterruptDefinitionRegistry } from './generic-interrupts'
+
 export { MiddlewareRunner } from './compose'
 
 export { createCapability, CapabilityRegistry } from './capabilities'

package/src/activities/chat/middleware/types.ts

@@ -1,3 +1,7 @@
+import type {
+  StandardJSONSchemaV1,
+  StandardSchemaV1,
+} from '@standard-schema/spec'
 import type {
   AgentLoopState,
   JSONSchema,
@@ -10,6 +14,10 @@ import type {
 } from '../../../types'
 import type { SystemPrompt } from '../../../system-prompts'
 import type { ToolApprovalResolution } from '../../../interrupts'
+import type {
+  GenericInterruptRequest,
+  InterruptDefinition,
+} from '../../../interrupt-definition'
 import type {
   Capability,
   CapabilityHandle,
@@ -68,6 +76,7 @@ export interface ChatSandboxHooks<TContext = unknown> {
  * Phase of the chat middleware lifecycle.
  * - 'init': Initial config transform before the chat engine starts
  * - 'beforeModel': Before each adapter chatStream call (per agent iteration)
+ * - 'afterModel': After each adapter chatStream call (per agent iteration)
  * - 'modelStream': During model streaming
  * - 'beforeTools': Before tool execution phase
  * - 'afterTools': After tool execution phase
@@ -77,11 +86,97 @@ export interface ChatSandboxHooks<TContext = unknown> {
 export type ChatMiddlewarePhase =
   | 'init'
   | 'beforeModel'
+  | 'afterModel'
   | 'modelStream'
   | 'beforeTools'
   | 'afterTools'
   | 'structuredOutput'
 
+export const INTERRUPT_BOUNDARY_PHASES = [
+  'beforeModel',
+  'afterModel',
+  'beforeTools',
+  'afterTools',
+] as const
+
+export type InterruptBoundaryPhase = (typeof INTERRUPT_BOUNDARY_PHASES)[number]
+
+export const INTERRUPT_TOOL_RESUMES = ['continue', 'cancel', 'stop'] as const
+
+export type InterruptToolResume = (typeof INTERRUPT_TOOL_RESUMES)[number]
+
+type AnyInterruptDefinition = InterruptDefinition<any, any, any, any>
+
+type InterruptResponse<TDefinition> =
+  TDefinition extends InterruptDefinition<any, any, infer TResponseSchema, any>
+    ? TResponseSchema extends StandardSchemaV1<any, infer TResponse>
+      ? TResponse
+      : TResponseSchema extends StandardJSONSchemaV1<any, infer TResponse>
+        ? TResponse
+        : unknown
+    : unknown
+
+export type GenericInterruptResolution<
+  TDefinition extends AnyInterruptDefinition,
+> = TDefinition extends AnyInterruptDefinition
+  ?
+      | {
+          readonly request: GenericInterruptRequest<TDefinition>
+          readonly status: 'resolved'
+          readonly response: InterruptResponse<TDefinition>
+        }
+      | {
+          readonly request: GenericInterruptRequest<TDefinition>
+          readonly status: 'cancelled'
+          readonly response?: never
+        }
+  : never
+
+export interface InterruptResolutionCollection<
+  TDefinitions extends AnyInterruptDefinition = AnyInterruptDefinition,
+> {
+  for: <
+    TDefinition extends ([TDefinitions] extends [never]
+      ? AnyInterruptDefinition
+      : TDefinitions),
+  >(
+    definition: TDefinition,
+  ) => ReadonlyArray<GenericInterruptResolution<TDefinition>>
+  all: {
+    (): ReadonlyArray<GenericInterruptResolution<TDefinitions>>
+    <const TSelected extends ReadonlyArray<TDefinitions>>(
+      ...definitions: TSelected
+    ): ReadonlyArray<GenericInterruptResolution<TSelected[number]>>
+  }
+}
+
+type BivariantInterruptResolutionHook<
+  TContext,
+  TDefinitions extends AnyInterruptDefinition,
+> = InterruptResolutionHookSignature<TContext, TDefinitions>['call']
+
+declare abstract class InterruptResolutionHookSignature<
+  TContext,
+  TDefinitions extends AnyInterruptDefinition,
+> {
+  abstract call(
+    ctx: ChatMiddlewareContext<TContext>,
+    resolutions: InterruptResolutionCollection<TDefinitions>,
+  ): InterruptResolutionResult | Promise<InterruptResolutionResult>
+}
+
+export type InterruptBoundaryResult<
+  TDefinitions extends AnyInterruptDefinition = AnyInterruptDefinition,
+> =
+  | undefined
+  | {
+      readonly interrupts: ReadonlyArray<GenericInterruptRequest<TDefinitions>>
+    }
+
+export type InterruptResolutionResult = void | {
+  readonly toolResume: InterruptToolResume
+}
+
 /**
  * Stable context object passed to all middleware hooks.
  * Created once per chat() invocation and shared across all hooks.
@@ -230,6 +325,13 @@ export interface ChatResumeToolState {
   genericInterrupts?:
     | ReadonlyMap<string, ChatResumeGenericResolution>
     | undefined
+  /** Durable generic requests reconstructed by server middleware. */
+  genericInterruptRequests?:
+    | ReadonlyMap<
+        string,
+        GenericInterruptRequest<InterruptDefinition<any, any, any, any>>
+      >
+    | undefined
   deniedToolResults?: ReadonlyMap<string, unknown> | undefined
   cancelledToolCallIds?: ReadonlySet<string> | undefined
 }
@@ -460,10 +562,32 @@ export interface ErrorInfo {
  * }
  * ```
  */
-export interface ChatMiddleware<TContext = unknown> {
+export interface ChatMiddleware<
+  TContext = unknown,
+  TInterruptDefinitions extends AnyInterruptDefinition = never,
+> {
   /** Optional name for debugging and identification */
   name?: string
 
+  /**
+   * Called at a lifecycle boundary. Return interrupt requests to pause the run.
+   * Requests from every middleware in the same boundary form one batch.
+   */
+  onInterruptBoundary?: (
+    ctx: ChatMiddlewareContext<TContext> & { phase: InterruptBoundaryPhase },
+  ) =>
+    | InterruptBoundaryResult<TInterruptDefinitions>
+    | Promise<InterruptBoundaryResult<TInterruptDefinitions>>
+
+  /**
+   * Called on a continuation run after the client answers registered interrupts.
+   * Return `toolResume` to decide whether pending tools continue, cancel, or stop.
+   */
+  onInterruptResolution?: BivariantInterruptResolutionHook<
+    TContext,
+    TInterruptDefinitions
+  >
+
   /**
    * Capabilities this middleware requires. `chat()` validates that some
    * middleware (or the adapter) provides each one; unsatisfied requirements are
@@ -653,4 +777,5 @@ export interface ChatMiddleware<TContext = unknown> {
 }
 
 /** A `ChatMiddleware` with a permissive context — for use as a constraint. */
-export type AnyChatMiddleware = ChatMiddleware<any>
+/** A permissive middleware constraint that retains the definition parameter. */
+export type AnyChatMiddleware = ChatMiddleware<any, any>

package/src/activities/chat/stream/processor.ts

@@ -38,6 +38,7 @@ import {
   updateToolResultPart,
 } from './message-updaters'
 import { ImmediateStrategy } from './strategies'
+import { INTERRUPT_BINDING_METADATA_KEY } from '../../../interrupt-resume'
 import type {
   ChunkRecording,
   ChunkStrategy,
@@ -138,6 +139,22 @@ export interface StreamProcessorOptions {
 
 const STRUCTURED_OUTPUT_UPDATE_BATCH_SIZE = 12
 
+function interruptBatchHasGeneric(interrupts: Array<Interrupt>): boolean {
+  return interrupts.some((interrupt) => {
+    const metadata = interrupt.metadata
+    if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) {
+      return false
+    }
+    const binding = metadata[INTERRUPT_BINDING_METADATA_KEY]
+    return (
+      binding !== null &&
+      typeof binding === 'object' &&
+      !Array.isArray(binding) &&
+      binding.kind === 'generic'
+    )
+  })
+}
+
 /**
  * StreamProcessor - State machine for processing AI response streams
  *
@@ -1548,6 +1565,7 @@ export class StreamProcessor {
   }
 
   private handleInterrupts(interrupts: Array<Interrupt>): void {
+    const hasGeneric = interruptBatchHasGeneric(interrupts)
     for (const interrupt of interrupts) {
       const metadata =
         interrupt.metadata && typeof interrupt.metadata === 'object'
@@ -1598,6 +1616,9 @@ export class StreamProcessor {
       }
 
       if (kind === 'client_tool' || interrupt.reason === 'client_tool_input') {
+        // Generic interrupts in the same batch decide `toolResume`. Do not
+        // run client tools until that policy is `continue`.
+        if (hasGeneric) continue
         this.events.onToolCall?.({
           toolCallId,
           toolName,

package/src/adapter-internals.ts

@@ -25,6 +25,26 @@ export {
   PendingTurnCapability,
   providePendingTurn,
 } from './activities/chat/middleware/pending-turn'
+export {
+  getGenericInterruptDefinitionRegistry,
+  GenericInterruptDefinitionRegistryCapability,
+  provideGenericInterruptDefinitionRegistry,
+} from './activities/chat/middleware/generic-interrupts'
+export type { GenericInterruptDefinitionRegistry } from './activities/chat/middleware/generic-interrupts'
+export {
+  createInterruptBinding,
+  getInterruptRequestInput,
+  rehydrateInterruptRequest,
+} from './interrupt-definition'
+export type {
+  GenericInterruptRequest,
+  InterruptDefinition,
+} from './interrupt-definition'
+export {
+  readInterruptBinding,
+  validateInterruptResumeBatch,
+} from './interrupt-resume'
+export type { PendingInterruptResumeRecord } from './interrupt-resume'
 export {
   assertUniqueToolNames,
   DuplicateToolNameError,

package/src/client.ts

@@ -343,6 +343,26 @@ export {
   INTERRUPT_BINDING_VERSION,
   canonicalizeInterruptResolutions,
 } from './interrupts'
+export {
+  defineInterrupt,
+  hashInterruptDefinitionSchema,
+  INTERRUPT_PAYLOAD_METADATA_KEY,
+} from './interrupt-definition'
+export {
+  INTERRUPT_CONTINUATION_METADATA_KEY,
+  INTERRUPT_CONTINUATION_VERSION,
+  genericInterruptContinuationFromDescriptor,
+  readGenericInterruptContinuation,
+  wrapGenericInterruptContinuation,
+} from './generic-interrupt-continuation'
+export type {
+  GenericInterruptContinuation,
+  GenericInterruptContinuationReadResult,
+} from './generic-interrupt-continuation'
+export type {
+  GenericInterruptRequest,
+  InterruptDefinition,
+} from './interrupt-definition'
 export type {
   BatchInterruptError,
   BatchInterruptErrorCode,