@tanstack/ai-client 0.24.0 → 0.25.2

package/src/types.ts

@@ -9,6 +9,7 @@ import type {
   DocumentPart,
   ImagePart,
   InferSchemaType,
+  InterruptDefinition,
   InferToolInput,
   InferToolOutput,
   InputSchemaOf,
@@ -86,6 +87,51 @@ export interface GenericAGUIInterrupt extends BoundInterruptBase {
   resolveInterrupt: (payload: unknown) => void
 }
 
+type InterruptResponseInput<TDefinition> =
+  TDefinition extends InterruptDefinition<any, any, infer TResponseSchema, any>
+    ? InferSchemaType<TResponseSchema>
+    : never
+
+type RegisteredGenericInterruptFor<
+  TDefinition extends InterruptDefinition<any, any, any, any>,
+> =
+  TDefinition extends InterruptDefinition<
+    infer TDefinitionId,
+    any,
+    any,
+    infer TPayload
+  >
+    ? BoundInterruptBase & {
+        readonly kind: 'generic'
+        readonly definitionId: TDefinitionId
+        readonly key: string
+        readonly payload: TPayload | undefined
+        readonly binding: Readonly<
+          Extract<InterruptBinding, { kind: 'generic' }> & {
+            definitionId: TDefinitionId
+            key: string
+            batchIndex: number
+          }
+        >
+        resolveInterrupt: (
+          response: InterruptResponseInput<TDefinition>,
+        ) => void
+      }
+    : never
+
+export type RegisteredGenericInterrupt<
+  TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>>,
+> = TInterrupts[number] extends infer TDefinition
+  ? TDefinition extends InterruptDefinition<any, any, any, any>
+    ? RegisteredGenericInterruptFor<TDefinition>
+    : never
+  : never
+
+/** A bound generic interrupt for one `defineInterrupt()` definition. */
+export type GenericInterrupt<
+  TDefinition extends InterruptDefinition<any, any, any, any>,
+> = RegisteredGenericInterruptFor<TDefinition>
+
 /**
  * An interrupt that arrived on the stream carrying no resume binding this
  * client understands — no `tanstack:interruptBinding`, or one written at a
@@ -98,7 +144,10 @@ export interface GenericAGUIInterrupt extends BoundInterruptBase {
  * send an answer no one is waiting for. Render it, or route it to whatever
  * actually owns the pause.
  */
-export interface UnboundInterrupt extends BoundInterruptBase {
+export interface UnboundInterrupt extends Omit<
+  BoundInterruptBase,
+  'cancel' | 'clearResolution'
+> {
   readonly kind: 'unbound'
   readonly binding?: undefined
   readonly canResolve: false
@@ -188,18 +237,37 @@ type ApprovalInterrupts<TTools extends ReadonlyArray<AnyClientTool>> =
 // union.
 export type ChatInterrupt<
   TTools extends ReadonlyArray<AnyClientTool> = ReadonlyArray<AnyClientTool>,
-> = GenericAGUIInterrupt | UnboundInterrupt | ApprovalInterrupts<TTools>
+  TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> =
+    readonly [],
+> =
+  | GenericAGUIInterrupt
+  | RegisteredGenericInterrupt<TInterrupts>
+  | UnboundInterrupt
+  | ApprovalInterrupts<TTools>
+
+export type ResolvableChatInterrupt<
+  TTools extends ReadonlyArray<AnyClientTool> = ReadonlyArray<AnyClientTool>,
+  TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> =
+    readonly [],
+> =
+  | GenericAGUIInterrupt
+  | RegisteredGenericInterrupt<TInterrupts>
+  | ApprovalInterrupts<TTools>
 
 export type BoundInterrupts<
   TTools extends ReadonlyArray<AnyClientTool> = ReadonlyArray<AnyClientTool>,
-> = ReadonlyArray<ChatInterrupt<TTools>>
+  TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> =
+    readonly [],
+> = ReadonlyArray<ChatInterrupt<TTools, TInterrupts>>
 
 export interface ChatInterruptState<
   TTools extends ReadonlyArray<AnyClientTool> = ReadonlyArray<AnyClientTool>,
+  TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> =
+    readonly [],
 > {
-  readonly interrupts: BoundInterrupts<TTools>
+  readonly interrupts: BoundInterrupts<TTools, TInterrupts>
   /** @deprecated Use `interrupts`. Same snapshot today. */
-  readonly pendingInterrupts: BoundInterrupts<TTools>
+  readonly pendingInterrupts: BoundInterrupts<TTools, TInterrupts>
   readonly interruptErrors: ReadonlyArray<BatchInterruptError>
   readonly resuming: boolean
 }
@@ -742,6 +810,8 @@ export type ClientContextOptionFromTools<TTools, TContext> = [
 export interface ChatClientBaseOptions<
   TTools extends ReadonlyArray<AnyClientTool> = any,
   TContext = unknown,
+  TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> =
+    readonly [],
 > {
   /**
    * Initial messages to populate the chat
@@ -864,7 +934,7 @@ export interface ChatClientBaseOptions<
    */
   onResumeStateChange?: (
     resumeState: ChatResumeState | null,
-    pendingInterrupts: BoundInterrupts<TTools>,
+    pendingInterrupts: BoundInterrupts<TTools, TInterrupts>,
   ) => void
 
   /**
@@ -873,8 +943,15 @@ export interface ChatClientBaseOptions<
    */
   onRunIdChange?: (runId: string | null) => void
 
-  /** Callback when the immutable interrupt state snapshot changes. */
-  onInterruptStateChange?: (state: ChatInterruptState<TTools>) => void
+  /**
+   * Callback when the immutable interrupt state snapshot changes.
+   * Snapshot restoration passes `{ source: 'hydrate' }`; streamed and
+   * client-initiated updates pass `{ source: 'live' }`.
+   */
+  onInterruptStateChange?: (
+    state: ChatInterruptState<TTools, TInterrupts>,
+    context: { source: 'hydrate' | 'live' },
+  ) => void
 
   /**
    * Callback when a custom event is received from a server-side tool.
@@ -896,6 +973,9 @@ export interface ChatClientBaseOptions<
    */
   tools?: TTools
 
+  /** First-party generic interrupts this client can type and resolve. */
+  interrupts?: TInterrupts
+
   /**
    * Devtools hook metadata for this client instance.
    */
@@ -931,7 +1011,12 @@ export interface ChatClientBaseOptions<
 export type ChatClientOptions<
   TTools extends ReadonlyArray<AnyClientTool> = any,
   TContext = InferredClientContext<TTools>,
-> = DistributedOmit<ChatClientBaseOptions<TTools, TContext>, 'context'> &
+  TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> =
+    readonly [],
+> = DistributedOmit<
+  ChatClientBaseOptions<TTools, TContext, TInterrupts>,
+  'context'
+> &
   ClientContextOptionFromTools<TTools, TContext> &
   ChatTransport &
   ChatPersistenceOptions<TTools>
@@ -981,9 +1066,12 @@ export function clientTools<const T extends Array<AnyClientTool>>(
 export function createChatClientOptions<
   const TTools extends ReadonlyArray<AnyClientTool>,
   TContext = InferredClientContext<TTools>,
+  const TInterrupts extends ReadonlyArray<
+    InterruptDefinition<any, any, any, any>
+  > = readonly [],
 >(
-  options: ChatClientOptions<TTools, TContext>,
-): ChatClientOptions<TTools, TContext> {
+  options: ChatClientOptions<TTools, TContext, TInterrupts>,
+): ChatClientOptions<TTools, TContext, TInterrupts> {
   return options
 }