@tanstack/ai 0.42.0 → 0.43.1

package/src/interrupt-serialization.ts

@@ -0,0 +1,183 @@
+// Dependency-free SHA-256 (FIPS 180-4). Sync and isomorphic (Node + browser)
+// so interrupt hashing needs no crypto library. Users can replace the whole
+// algorithm through the `interrupts.hash` option; this is only the default.
+// ponytail: bundled ~60-line hash, swap via interrupts.hash if you need more.
+const SHA256_K = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1,
+  0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
+  0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786,
+  0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147,
+  0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+  0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b,
+  0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a,
+  0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208,
+  0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+])
+
+function rotr(x: number, n: number): number {
+  return (x >>> n) | (x << (32 - n))
+}
+
+function sha256Hex(input: string): string {
+  const msg = new TextEncoder().encode(input)
+
+  const bitLen = msg.length * 8
+  const withOne = msg.length + 1
+  const total = withOne + ((56 - (withOne % 64) + 64) % 64) + 8
+  const bytes = new Uint8Array(total)
+  bytes.set(msg)
+  bytes[msg.length] = 0x80
+  const view = new DataView(bytes.buffer)
+  view.setUint32(total - 8, Math.floor(bitLen / 0x100000000))
+  view.setUint32(total - 4, bitLen >>> 0)
+
+  let h0 = 0x6a09e667
+  let h1 = 0xbb67ae85
+  let h2 = 0x3c6ef372
+  let h3 = 0xa54ff53a
+  let h4 = 0x510e527f
+  let h5 = 0x9b05688c
+  let h6 = 0x1f83d9ab
+  let h7 = 0x5be0cd19
+
+  const w = new Uint32Array(64)
+  for (let offset = 0; offset < total; offset += 64) {
+    for (let i = 0; i < 16; i++) w[i] = view.getUint32(offset + i * 4)
+    for (let i = 16; i < 64; i++) {
+      const x15 = w[i - 15] ?? 0
+      const x2 = w[i - 2] ?? 0
+      const s0 = rotr(x15, 7) ^ rotr(x15, 18) ^ (x15 >>> 3)
+      const s1 = rotr(x2, 17) ^ rotr(x2, 19) ^ (x2 >>> 10)
+      w[i] = ((w[i - 16] ?? 0) + s0 + (w[i - 7] ?? 0) + s1) >>> 0
+    }
+
+    let a = h0
+    let b = h1
+    let c = h2
+    let d = h3
+    let e = h4
+    let f = h5
+    let g = h6
+    let hh = h7
+    for (let i = 0; i < 64; i++) {
+      const bigS1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)
+      const ch = (e & f) ^ (~e & g)
+      const t1 = (hh + bigS1 + ch + (SHA256_K[i] ?? 0) + (w[i] ?? 0)) >>> 0
+      const bigS0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)
+      const maj = (a & b) ^ (a & c) ^ (b & c)
+      const t2 = (bigS0 + maj) >>> 0
+      hh = g
+      g = f
+      f = e
+      e = (d + t1) >>> 0
+      d = c
+      c = b
+      b = a
+      a = (t1 + t2) >>> 0
+    }
+    h0 = (h0 + a) >>> 0
+    h1 = (h1 + b) >>> 0
+    h2 = (h2 + c) >>> 0
+    h3 = (h3 + d) >>> 0
+    h4 = (h4 + e) >>> 0
+    h5 = (h5 + f) >>> 0
+    h6 = (h6 + g) >>> 0
+    h7 = (h7 + hh) >>> 0
+  }
+
+  const hex = (n: number): string => (n >>> 0).toString(16).padStart(8, '0')
+  return (
+    hex(h0) +
+    hex(h1) +
+    hex(h2) +
+    hex(h3) +
+    hex(h4) +
+    hex(h5) +
+    hex(h6) +
+    hex(h7)
+  )
+}
+
+/**
+ * A hash function for interrupt bindings and resolution fingerprints. Receives
+ * canonical JSON text and returns an opaque string. Must be deterministic; the
+ * server compares hashes it computed against the ones in a binding, so the same
+ * function has to run wherever a given binding is produced and checked.
+ */
+export type InterruptHash = (canonicalJson: string) => string
+
+/** The built-in default: SHA-256, prefixed so the algorithm is self-describing. */
+export function defaultInterruptHash(canonicalJson: string): string {
+  return `sha256:${sha256Hex(canonicalJson)}`
+}
+
+function canonical(value: unknown, active: WeakSet<object>): string {
+  if (value === null) return 'null'
+  if (typeof value === 'string' || typeof value === 'boolean') {
+    return JSON.stringify(value)
+  }
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return JSON.stringify(value)
+  }
+  if (typeof value !== 'object') {
+    throw new TypeError('Interrupt values must be JSON-compatible.')
+  }
+  if (active.has(value)) {
+    throw new TypeError('Interrupt values must not cycle.')
+  }
+  if (
+    !Array.isArray(value) &&
+    Object.getPrototypeOf(value) !== Object.prototype &&
+    Object.getPrototypeOf(value) !== null
+  ) {
+    throw new TypeError('Interrupt values must use plain JSON objects.')
+  }
+
+  active.add(value)
+  let encoded: string
+  if (Array.isArray(value)) {
+    const items: Array<string> = []
+    for (let index = 0; index < value.length; index++) {
+      items.push(canonical(value[index], active))
+    }
+    encoded = `[${items.join(',')}]`
+  } else {
+    const record = value as Record<string, unknown>
+    encoded = `{${Object.keys(record)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonical(record[key], active)}`)
+      .join(',')}}`
+  }
+  active.delete(value)
+  return encoded
+}
+
+export function canonicalInterruptJson(value: unknown): string {
+  return canonical(value, new WeakSet<object>())
+}
+
+export function digestInterruptJson(
+  canonicalJson: string,
+  hash: InterruptHash = defaultInterruptHash,
+): string {
+  if (typeof canonicalJson !== 'string') {
+    throw new TypeError('Interrupt digests require canonical JSON text.')
+  }
+  return hash(canonicalJson)
+}
+
+function freezeTree(value: unknown): void {
+  if (value === null || typeof value !== 'object' || Object.isFrozen(value)) {
+    return
+  }
+  Object.values(value).forEach(freezeTree)
+  Object.freeze(value)
+}
+
+export function cloneAndDeepFreezeJson<T>(value: T): T {
+  const clone: T = JSON.parse(canonicalInterruptJson(value))
+  freezeTree(clone)
+  return clone
+}

package/src/interrupts.ts

@@ -0,0 +1,146 @@
+import {
+  canonicalInterruptJson,
+  cloneAndDeepFreezeJson,
+  digestInterruptJson,
+} from './interrupt-serialization'
+import type { RunAgentResumeItem } from './types'
+
+export interface InterruptCorrelation {
+  threadId: string
+  interruptedRunId: string
+  generation: number
+  submissionId?: string
+  continuationRunId?: string
+}
+
+export type ItemInterruptErrorCode =
+  | 'invalid-payload'
+  | 'invalid-edited-args'
+  | 'invalid-tool-output'
+  | 'invalid-response-schema'
+  | 'unknown-interrupt'
+  | 'expired'
+  | 'stale'
+  | 'conflict'
+  | 'legacy-unsupported'
+
+export type BatchInterruptErrorCode =
+  | 'incomplete-batch'
+  | 'item-validation-failed'
+  | 'unsupported-bulk-operation'
+  | 'async-resolver'
+  | 'inactive-transaction'
+  | 'mixed-provenance'
+  | 'transport'
+  | 'server'
+  | 'protocol'
+  | 'invalid-response-schema'
+  | 'expired'
+  | 'stale'
+  | 'conflict'
+  | 'legacy-submit-failed'
+
+export interface ItemInterruptError extends InterruptCorrelation {
+  scope: 'item'
+  interruptId: string
+  code: ItemInterruptErrorCode
+  message: string
+  path?: ReadonlyArray<string | number>
+  source: 'client' | 'server'
+  retryable: boolean
+}
+
+export interface BatchInterruptError extends InterruptCorrelation {
+  scope: 'batch'
+  code: BatchInterruptErrorCode
+  message: string
+  source: 'client' | 'server' | 'transport'
+  retryable: boolean
+  interruptIds: ReadonlyArray<string>
+}
+
+export type InterruptSubmissionError = ItemInterruptError | BatchInterruptError
+
+/**
+ * Wire version of {@link InterruptBinding}.
+ *
+ * The binding is the only part of an AG-UI `Interrupt` that this package
+ * claims — it rides in `metadata` under
+ * {@link INTERRUPT_BINDING_METADATA_KEY} and tells the resume path how to
+ * correlate an answer back to a paused run. Producers stamp `v`; readers
+ * reject any version they don't understand rather than duck-typing the fields.
+ *
+ * That matters because an AG-UI `Interrupt` is a shared envelope. Another
+ * producer — a workflow engine projecting a durable approval, a third-party
+ * agent — can legitimately put its own binding in the same envelope. Versioning
+ * makes "not mine" a clean rejection instead of a partial match that resumes
+ * against the wrong owner.
+ */
+export const INTERRUPT_BINDING_VERSION = 1 as const
+
+interface InterruptBindingBase {
+  /** @see INTERRUPT_BINDING_VERSION */
+  v: typeof INTERRUPT_BINDING_VERSION
+  interruptId: string
+  interruptedRunId: string
+  generation: number
+  responseSchemaHash: string
+  expiresAt?: string
+}
+
+export type InterruptBinding =
+  | (InterruptBindingBase & {
+      kind: 'tool-approval'
+      toolName: string
+      toolCallId: string
+      originalArgs: unknown
+      inputSchemaHash: string
+      approvalSchemaHash: string
+    })
+  | (InterruptBindingBase & {
+      kind: 'client-tool-execution'
+      toolName: string
+      toolCallId: string
+      outputSchemaHash: string
+    })
+  | (InterruptBindingBase & {
+      kind: 'generic'
+    })
+
+export type UnopenedInterruptBinding = InterruptBinding extends infer TBinding
+  ? TBinding extends InterruptBinding
+    ? Omit<TBinding, 'interruptedRunId' | 'generation'>
+    : never
+  : never
+
+export type ToolApprovalResolution =
+  | boolean
+  | {
+      approved: true
+      editedArgs?: unknown
+      payload?: unknown
+    }
+  | {
+      approved: false
+      payload?: unknown
+      editedArgs?: never
+    }
+
+export function canonicalizeInterruptResolutions(
+  resolutions: ReadonlyArray<RunAgentResumeItem>,
+): {
+  resolutions: ReadonlyArray<RunAgentResumeItem>
+  canonicalResolutions: string
+  fingerprint: string
+} {
+  const sorted = [...resolutions].sort((left, right) =>
+    left.interruptId.localeCompare(right.interruptId),
+  )
+  const frozen = cloneAndDeepFreezeJson(sorted)
+  const canonicalResolutions = canonicalInterruptJson(frozen)
+  return Object.freeze({
+    resolutions: frozen,
+    canonicalResolutions,
+    fingerprint: digestInterruptJson(canonicalResolutions),
+  })
+}

package/src/locks.ts

@@ -0,0 +1,17 @@
+/**
+ * Distributed-mutex primitive — coordination, not state persistence.
+ *
+ * Its own subpath (`@tanstack/ai/locks`) so it stays out of the main barrel and
+ * consumers opt in explicitly. Provide a store with `withLocks`; downstream
+ * middleware (e.g. `@tanstack/ai-sandbox`'s `ensure`) reads it via `getLocks` /
+ * `LocksCapability`. Import from here, not from `@tanstack/ai-persistence`.
+ */
+export {
+  LocksCapability,
+  getLocks,
+  provideLocks,
+  InMemoryLockStore,
+  withLocks,
+  defineLock,
+} from './activities/chat/middleware/index'
+export type { LockStore } from './activities/chat/middleware/index'

package/src/logger/types.ts

@@ -29,7 +29,7 @@ export interface Logger {
  */
 export interface DebugCategories {
   /**
-   * Raw chunks/frames received from a provider SDK (OpenAI, Anthropic, Gemini, Ollama, Grok, Groq, OpenRouter, fal, ElevenLabs). Emitted inside every streaming adapter's chunk loop.
+   * Raw chunks/frames received from a provider SDK (OpenAI, Anthropic, Gemini, Ollama, Grok, Groq, OpenRouter, fal, ElevenLabs, BytePlus). Emitted inside every streaming adapter's chunk loop.
    */
   provider?: boolean
   /**

package/src/middlewares/otel.ts

@@ -33,7 +33,9 @@ import type {
  * Scope (role) of an OTel span emitted by this middleware.
  *
  * - `chat` — the root span for a single `chat()` call
- * - `iteration` — one per agent-loop iteration (one model call)
+ * - `iteration` — one per provider model call (agent-loop `beforeModel`
+ *   turn, or the separate `structuredOutput` finalization when
+ *   `outputSchema` skips the agent loop — see #1054)
  * - `tool` — one per tool execution inside an iteration
  * - `generation` — the single span for a media activity call
  *   (`generateImage`, `generateVideo`, `generateSpeech`, …)
@@ -83,6 +85,7 @@ const OPERATION_NAME: Record<GenerationActivity, string> = {
   audio: 'audio_generation',
   tts: 'text_to_speech',
   transcription: 'transcription',
+  summarize: 'summarize',
 }
 
 export interface OtelMiddlewareOptions {
@@ -400,7 +403,16 @@ export function otelMiddleware(
     },
 
     onConfig(ctx, config) {
-      if (ctx.phase !== 'beforeModel') return
+      // Open an iteration span for every provider model call:
+      // - `beforeModel`: agent-loop chatStream turns
+      // - `structuredOutput`: separate structured-output finalization
+      //   (no-tools + outputSchema skips the agent loop, so without this
+      //   phase there is no generation span and captureContent is a silent
+      //   no-op — see #1054).
+      // Native-combined mode never fires `structuredOutput`, so a run that
+      // already opened spans via `beforeModel` is not double-counted.
+      if (ctx.phase !== 'beforeModel' && ctx.phase !== 'structuredOutput')
+        return
       safeCall('otel.onConfig', () => {
         const state = stateByCtx.get(ctx)
         if (!state) return
@@ -410,20 +422,26 @@ export function otelMiddleware(
         // on it. Close it here, just before opening the next iteration.
         closeIterationSpan(state, ctx)
 
+        // Number spans by the order of model calls this middleware has seen,
+        // not by `ctx.iteration`. After an agent-loop turn, structured-output
+        // finalization reuses the engine's last iteration index; using our
+        // own counter keeps finalization as a distinct leaf (#N+1).
+        const iteration = state.iterationCount
+
         const info: OtelSpanInfo<'iteration'> = {
           kind: 'iteration',
           ctx,
-          iteration: ctx.iteration,
+          iteration,
         }
         const name =
           safeCall('otel.spanNameFormatter', () => spanNameFormatter?.(info)) ??
-          `chat ${ctx.model} #${ctx.iteration}`
+          `chat ${ctx.model} #${iteration}`
 
         const baseAttrs: Record<string, AttributeValue> = {
           'gen_ai.system': ctx.provider,
           'gen_ai.operation.name': 'chat',
           'gen_ai.request.model': ctx.model,
-          'tanstack.ai.iteration': ctx.iteration,
+          'tanstack.ai.iteration': iteration,
         }
         // Sampling options now live in provider-native `modelOptions`, and
         // providers spell them differently (e.g. `max_output_tokens`,

package/src/realtime/index.ts

@@ -19,15 +19,11 @@ export type * from './types'
  * import { realtimeToken } from '@tanstack/ai'
  * import { openaiRealtimeToken } from '@tanstack/ai-openai'
  *
- * // Server function (TanStack Start example)
- * export const getRealtimeToken = createServerFn()
- *   .handler(async () => {
- *     return realtimeToken({
- *       adapter: openaiRealtimeToken({
- *         model: 'gpt-realtime',
- *       }),
- *     })
- *   })
+ * // On the server (e.g. inside a server route or framework server
+ * // function), mint an ephemeral token for the client:
+ * const token = await realtimeToken({
+ *   adapter: openaiRealtimeToken({ model: 'gpt-realtime' }),
+ * })
  * ```
  */
 export async function realtimeToken(

package/src/scope.ts

@@ -0,0 +1,47 @@
+/**
+ * Shared identity/isolation scope for the TanStack AI subsystems that persist
+ * or recall per-conversation data — `@tanstack/ai-persistence` (keyed CRUD over
+ * threads, runs, interrupts) and `@tanstack/ai-memory` (ranked recall/save).
+ *
+ * Both subsystems answer the same underlying question — "whose data is this?" —
+ * so they share ONE identity vocabulary defined here rather than each inventing
+ * its own. `threadId` is the single conversation key across the codebase (it is
+ * `ChatMiddlewareContext.threadId`, and `conversationId` is deprecated in favor
+ * of it); a subsystem must never introduce a second name (`sessionId`,
+ * `conversationId`, …) for the same concept.
+ *
+ * ## Security
+ *
+ * A `Scope` is an isolation boundary. Derive every field server-side from
+ * trusted, validated session state — **never** from client input. `threadId`
+ * in particular resolves from a client-supplied value on the request, so a
+ * subsystem that reads/writes user-owned data (memory, per-user metadata) must
+ * pair it with a server-trusted `userId`/`tenantId` and must not treat a bare
+ * client `threadId` as sufficient isolation: thread ids are guessable, so on
+ * their own they let one caller read another's data.
+ */
+export interface Scope {
+  /**
+   * The conversation this data belongs to. Required — the minimal isolation
+   * key both subsystems already center on. Same concept as
+   * `ChatMiddlewareContext.threadId`.
+   */
+  threadId: string
+  /**
+   * Durable end-user identity, for cross-thread recall and per-user isolation.
+   * Optional, but required in practice for any multi-user deployment — a
+   * `threadId` alone is not an authorization boundary (see Security above).
+   */
+  userId?: string
+  /**
+   * Tenant/organization boundary for multi-tenant deployments. When present,
+   * every read and write must be confined to it.
+   */
+  tenantId?: string
+  /**
+   * Logical partition within a tenant/user (e.g. separating distinct memory
+   * banks or persistence namespaces). Reserved — no subsystem keys on it yet;
+   * adapters that don't understand it must ignore it rather than error.
+   */
+  namespace?: string
+}