@tanstack/ai 0.45.1 → 0.47.1

package/src/interrupt-resume.ts

@@ -25,6 +25,10 @@ import type {
   ChatMiddlewareConfig,
   ChatResumeToolState,
 } from './activities/chat/middleware/types'
+import type {
+  GenericInterruptRequest,
+  InterruptDefinition,
+} from './interrupt-definition'
 import type { Interrupt, RunAgentResumeItem } from './types'
 
 /**
@@ -46,6 +50,10 @@ export interface PendingInterruptResumeRecord {
   interruptId: string
   payload: unknown
   binding: InterruptBinding
+  /** Present for a first-party generic interrupt. */
+  genericRequest?: GenericInterruptRequest<
+    InterruptDefinition<any, any, any, any>
+  >
 }
 
 export interface ValidateInterruptResumeBatchInput {
@@ -164,6 +172,17 @@ function runtimeTool(
   return tools.find((tool) => tool.name === name) as RuntimeTool | undefined
 }
 
+async function parseSchemaValue(
+  schema: unknown,
+  value: unknown,
+): Promise<{ success: true; data: unknown } | { success: false }> {
+  if (!isStandardSchema(schema)) return { success: true, data: value }
+  const result = await validateWithStandardSchema<unknown>(schema, value)
+  return result.success
+    ? { success: true, data: result.data }
+    : { success: false }
+}
+
 function descriptorResponseSchema(
   record: PendingInterruptResumeRecord,
 ): unknown {
@@ -219,9 +238,14 @@ function validateDescriptorSchema(
   errors: Array<InterruptSubmissionError>,
 ): unknown {
   const schema = descriptorResponseSchema(record)
+  const responseSchemaHash = binding.responseSchemaHash
+  if (schema === undefined && responseSchemaHash === undefined) {
+    return undefined
+  }
   if (
     schema === undefined ||
-    schemaHash(schema) !== binding.responseSchemaHash
+    responseSchemaHash === undefined ||
+    schemaHash(schema) !== responseSchemaHash
   ) {
     errors.push(
       interruptItemError(
@@ -276,12 +300,24 @@ export async function validateInterruptResumeBatch(
     }
   }
 
+  const pendingGenerics = input.pending.filter(
+    (record) => record.binding.kind === 'generic',
+  )
+  const genericBatchSatisfied =
+    pendingGenerics.length > 0 &&
+    pendingGenerics.every((record) => resumeById.has(record.interruptId))
+
   let incomplete = false
   for (const record of input.pending) {
     const errors = group(record.interruptId)
     const entry = resumeById.get(record.interruptId)
     const binding = record.binding
     if (!entry) {
+      // Client tools that share a generic interrupt batch wait for
+      // `toolResume`. `continue` re-emits them; `cancel` / `stop` skip them.
+      if (genericBatchSatisfied && binding.kind === 'client-tool-execution') {
+        continue
+      }
       incomplete = true
       errors.push(
         interruptItemError(
@@ -307,19 +343,29 @@ export async function validateInterruptResumeBatch(
         ),
       )
     }
-    if (
-      binding.expiresAt !== undefined &&
-      Date.parse(binding.expiresAt) <= (input.now ?? Date.now())
-    ) {
-      errors.push(
-        interruptItemError(
-          input,
-          record.interruptId,
-          'expired',
-          `Interrupt ${record.interruptId} has expired.`,
-          { source: 'server' },
-        ),
-      )
+    if (binding.expiresAt !== undefined) {
+      const expiresAt = Date.parse(binding.expiresAt)
+      if (!Number.isFinite(expiresAt)) {
+        errors.push(
+          interruptItemError(
+            input,
+            record.interruptId,
+            'invalid-payload',
+            `Interrupt ${record.interruptId} has an invalid expiresAt.`,
+            { source: 'server' },
+          ),
+        )
+      } else if (expiresAt <= (input.now ?? Date.now())) {
+        errors.push(
+          interruptItemError(
+            input,
+            record.interruptId,
+            'expired',
+            `Interrupt ${record.interruptId} has expired.`,
+            { source: 'server' },
+          ),
+        )
+      }
     }
 
     const responseSchema = validateDescriptorSchema(
@@ -342,6 +388,28 @@ export async function validateInterruptResumeBatch(
       continue
     }
     if (binding.kind === 'generic') {
+      const genericRequest = record.genericRequest
+      if (genericRequest !== undefined) {
+        const batchIndex = binding.batchIndex
+        if (
+          binding.definitionId !== genericRequest.definition.id ||
+          binding.key !== genericRequest.key ||
+          binding.interruptId !== record.interruptId ||
+          batchIndex === undefined ||
+          !Number.isInteger(batchIndex) ||
+          batchIndex < 0
+        ) {
+          errors.push(
+            interruptItemError(
+              input,
+              record.interruptId,
+              'stale',
+              `Generic interrupt ${record.interruptId} has stale definition metadata.`,
+              { source: 'server' },
+            ),
+          )
+        }
+      }
       if (entry.status === 'cancelled') {
         if (entry.payload !== undefined) {
           errors.push(
@@ -353,6 +421,16 @@ export async function validateInterruptResumeBatch(
             ),
           )
         }
+      } else if (genericRequest !== undefined) {
+        await pushSchemaIssues({
+          request: input,
+          errors,
+          interruptId: record.interruptId,
+          schema: genericRequest.definition.responseSchema,
+          value: entry.payload,
+          code: 'invalid-payload',
+          label: `Interrupt ${record.interruptId} payload is invalid`,
+        })
       } else if (responseSchema !== undefined) {
         await pushSchemaIssues({
           request: input,
@@ -616,16 +694,42 @@ export async function validateInterruptResumeBatch(
     if (!entry) continue
     const binding = record.binding
     if (binding.kind === 'generic') {
-      genericInterrupts.set(
-        record.interruptId,
-        entry.status === 'resolved'
-          ? {
-              interruptId: record.interruptId,
-              status: 'resolved',
-              payload: entry.payload,
-            }
-          : { interruptId: record.interruptId, status: 'cancelled' },
+      if (entry.status !== 'resolved') {
+        genericInterrupts.set(record.interruptId, {
+          interruptId: record.interruptId,
+          status: 'cancelled',
+        })
+        continue
+      }
+      if (record.genericRequest === undefined) {
+        genericInterrupts.set(record.interruptId, {
+          interruptId: record.interruptId,
+          status: 'resolved',
+          payload: entry.payload,
+        })
+        continue
+      }
+      const parsed = await parseSchemaValue(
+        record.genericRequest.definition.responseSchema,
+        entry.payload,
       )
+      if (!parsed.success) {
+        return {
+          errors: [
+            interruptItemError(
+              input,
+              record.interruptId,
+              'invalid-payload',
+              `Interrupt ${record.interruptId} payload is invalid.`,
+            ),
+          ],
+        }
+      }
+      genericInterrupts.set(record.interruptId, {
+        interruptId: record.interruptId,
+        status: 'resolved',
+        payload: parsed.data,
+      })
       continue
     }
     if (entry.status === 'cancelled') {
@@ -711,17 +815,44 @@ export function readUnopenedInterruptBinding(
   const interruptId = stringField(raw, 'interruptId')
   const responseSchemaHash = stringField(raw, 'responseSchemaHash')
   const expiresAt = stringField(raw, 'expiresAt')
-  if (!interruptId || !responseSchemaHash) return undefined
+  if (!interruptId || responseSchemaHash === '') return undefined
+  if (expiresAt !== undefined && !Number.isFinite(Date.parse(expiresAt))) {
+    return undefined
+  }
   const v = INTERRUPT_BINDING_VERSION
   if (kind === 'generic') {
+    const definitionId = stringField(raw, 'definitionId')
+    const key = stringField(raw, 'key')
+    const batchIndex = raw['batchIndex']
+    const payloadSchemaHash = stringField(raw, 'payloadSchemaHash')
+    const hasFirstPartyFields =
+      definitionId !== undefined ||
+      key !== undefined ||
+      batchIndex !== undefined ||
+      payloadSchemaHash !== undefined
+    if (
+      hasFirstPartyFields &&
+      (!definitionId ||
+        !key ||
+        typeof batchIndex !== 'number' ||
+        !Number.isInteger(batchIndex) ||
+        batchIndex < 0)
+    ) {
+      return undefined
+    }
     return {
       v,
       kind,
       interruptId,
-      responseSchemaHash,
+      ...(responseSchemaHash ? { responseSchemaHash } : {}),
       ...(expiresAt ? { expiresAt } : {}),
+      ...(definitionId ? { definitionId } : {}),
+      ...(key ? { key } : {}),
+      ...(typeof batchIndex === 'number' ? { batchIndex } : {}),
+      ...(payloadSchemaHash ? { payloadSchemaHash } : {}),
     }
   }
+  if (!responseSchemaHash) return undefined
   const toolName = stringField(raw, 'toolName')
   const toolCallId = stringField(raw, 'toolCallId')
   if (!toolName || !toolCallId) return undefined

package/src/interrupts.ts

@@ -84,12 +84,15 @@ interface InterruptBindingBase {
   interruptId: string
   interruptedRunId: string
   generation: number
-  responseSchemaHash: string
   expiresAt?: string
 }
 
+interface ResponseSchemaInterruptBindingBase extends InterruptBindingBase {
+  responseSchemaHash: string
+}
+
 export type InterruptBinding =
-  | (InterruptBindingBase & {
+  | (ResponseSchemaInterruptBindingBase & {
       kind: 'tool-approval'
       toolName: string
       toolCallId: string
@@ -97,7 +100,7 @@ export type InterruptBinding =
       inputSchemaHash: string
       approvalSchemaHash: string
     })
-  | (InterruptBindingBase & {
+  | (ResponseSchemaInterruptBindingBase & {
       kind: 'client-tool-execution'
       toolName: string
       toolCallId: string
@@ -105,6 +108,13 @@ export type InterruptBinding =
     })
   | (InterruptBindingBase & {
       kind: 'generic'
+      /** Omitted when the generic interrupt accepts an unvalidated response. */
+      responseSchemaHash?: string
+      /** Present only for a first-party generic interrupt. */
+      definitionId?: string
+      key?: string
+      batchIndex?: number
+      payloadSchemaHash?: string
     })
 
 export type UnopenedInterruptBinding = InterruptBinding extends infer TBinding

package/src/middlewares/usage-attributes.ts

@@ -12,8 +12,8 @@ import type { TokenUsage } from '../types'
  * `gen_ai.usage.cost` and `gen_ai.usage.total_tokens` are de-facto extensions
  * consumed by backends like PostHog (which otherwise re-derive cost from their
  * own price tables, losing cache discounts and gateway markup). Fields with no
- * semconv or de-facto convention (`costDetails`, `durationSeconds`,
- * `unitsBilled`) are TanStack-namespaced.
+ * semconv or de-facto convention (`billed`, `costDetails`, and the deprecated
+ * `durationSeconds`/`unitsBilled`) are TanStack-namespaced.
  *
  * Shared by `otelMiddleware` across every activity (chat and the media
  * activities) so usage lands identically whichever activity produced the span.
@@ -30,6 +30,16 @@ export function usageAttributes(
     'gen_ai.usage.input_tokens': usage.promptTokens,
     'gen_ai.usage.output_tokens': usage.completionTokens,
   }
+  // The self-describing billed quantity: the unit rides along as a string
+  // attribute so backends can label/aggregate non-token usage without
+  // out-of-band knowledge of the provider.
+  if (usage.billed !== undefined) {
+    const quantity = firstNumber(usage.billed.quantity)
+    if (quantity !== undefined) {
+      attrs['tanstack.ai.usage.billed_quantity'] = quantity
+      attrs['tanstack.ai.usage.billed_unit'] = usage.billed.unit
+    }
+  }
   const optional: Array<[key: string, value: unknown]> = [
     ['gen_ai.usage.total_tokens', usage.totalTokens],
     ['gen_ai.usage.cost', usage.cost],

package/src/stream-to-response.ts

@@ -78,7 +78,7 @@ function combineFailures(
   )
 }
 
-function runErrorChunk(
+export function runErrorChunk(
   error: unknown,
 ): Extract<StreamChunk, { type: 'RUN_ERROR' }> {
   const payload = toRunErrorPayload(error)
@@ -366,7 +366,7 @@ export const RUN_ACCEPTED_EVENT = 'run.accepted'
  * The returned `getId` maps each forwarded chunk to the exact opaque offset
  * returned by the durability adapter for the SSE `id:` line.
  */
-function durableStreamSource<TOffset extends string>(
+export function durableStreamSource<TOffset extends string>(
   stream: AsyncIterable<StreamChunk>,
   durability: StreamDurability<TOffset>,
   options: {