@tanstack/ai 0.57.0 → 0.58.0

package/src/stream-to-response.ts

@@ -9,6 +9,10 @@ import { notifyRunDisconnected } from './delivery-disconnect'
 import { resolveResumeRunId } from './stream-durability'
 import { EventType } from './types'
 import { toWireChunk } from './strip-to-spec-middleware'
+import {
+  isDurabilityBatchedCustom,
+  stripDurabilityBatchHint,
+} from './utilities/durability-batch'
 import { resolveDebugOption } from './logger/resolve'
 import { runErrorEventToError } from './utilities/errors'
 import type { LockStore } from './activities/chat/middleware/locks'
@@ -319,23 +323,29 @@ function resolveBatchSize(batch: number | undefined): number {
 
 /**
  * Boundaries at which the batching producer flushes early, regardless of the
- * batch size — the run-start marker, terminal events, and tool-call ends.
- * Flushing here keeps the durability log promptly consistent at semantically
- * meaningful points.
+ * batch size: run-start, terminals, tool-call ends, and CUSTOM events that
+ * are not high-volume adapter output.
  *
  * `RUN_STARTED` matters especially for one-shot activities (image, speech,
  * transcription, summarize): they emit `RUN_STARTED`, then await the provider
  * for seconds, then a terminal. Without flushing `RUN_STARTED` the log stays
  * empty for the whole run, so a mount-time `joinRun` finds nothing and its
- * empty-log deadline fast-fails as "run gone" — even though the run is alive.
+ * empty-log deadline fast-fails as "run gone" even though the run is alive.
  * Flushing it immediately makes the run resumable from the instant it starts.
+ *
+ * CUSTOM progress events (compaction, tool progress, middleware) flush at
+ * emit time so a live indicator can render. `process.stdout`,
+ * `process.stderr`, `sandbox.file`, and `sandbox.file.diff` stay batched.
+ * `emitCustomEvent(name, value, { batch: true })` opts a single event into
+ * that same batch.
  */
 function isDurabilityFlushBoundary(chunk: StreamChunk): boolean {
   return (
     chunk.type === 'RUN_STARTED' ||
     chunk.type === 'RUN_FINISHED' ||
     chunk.type === 'RUN_ERROR' ||
-    chunk.type === 'TOOL_CALL_END'
+    chunk.type === 'TOOL_CALL_END' ||
+    (chunk.type === 'CUSTOM' && !isDurabilityBatchedCustom(chunk))
   )
 }
 
@@ -446,7 +456,7 @@ export function durableStreamSource<TOffset extends string>(
 
     async function* flush(): AsyncIterable<StreamChunk> {
       if (batch.length === 0) return
-      const toForward = batch
+      const toForward = batch.map(stripDurabilityBatchHint)
       batch = []
       // Tag each chunk with the exact backend offset. Requiring one opaque
       // token per chunk preserves exact-once resume at any batch size.

package/src/strip-to-spec-middleware.ts

@@ -6,6 +6,7 @@ import {
   tanstackMetadata,
   withTanstackMetadata,
 } from './utilities/merge-metadata'
+import { stripDurabilityBatchHint } from './utilities/durability-batch'
 import { normalizeStreamChunk } from './utilities/normalize-stream-chunk'
 import { isSpecTopLevelKey } from './utilities/spec-event-keys'
 
@@ -54,5 +55,5 @@ export function toWireChunk(
   chunk: StreamChunk | AdapterYieldChunk,
 ): StreamChunk {
   const [normalized] = normalizeStreamChunk(chunk)
-  return stripToSpec(normalized ?? chunk)
+  return stripDurabilityBatchHint(stripToSpec(normalized ?? chunk))
 }

package/src/types.ts

@@ -629,6 +629,22 @@ type RuntimeContextField<TContext> =
         context: TContext
       }
 
+/**
+ * Options for a single `emitCustomEvent` call, on both the tool-execution and
+ * middleware contexts.
+ */
+export interface EmitCustomEventOptions {
+  /**
+   * Keep this event in the durability batch with later chunks.
+   * CUSTOM events flush as soon as they are emitted, so a progress
+   * indicator can render at emit time. Pass `{ batch: true }` for a
+   * high-volume stream that should share appends with later output.
+   * `process.stdout`, `process.stderr`, `sandbox.file`, and
+   * `sandbox.file.diff` already batch.
+   */
+  batch?: boolean
+}
+
 /**
  * Context passed to tool execute functions, providing capabilities like
  * emitting custom events during execution.
@@ -649,6 +665,8 @@ export type ToolExecutionContext<TContext = unknown> =
      *
      * @param eventName - Name of the custom event
      * @param value - Event payload value
+     * @param options - Pass `{ batch: true }` to keep this event in the
+     *   durability batch instead of flushing it immediately
      *
      * @example
      * ```ts
@@ -661,7 +679,11 @@ export type ToolExecutionContext<TContext = unknown> =
      * })
      * ```
      */
-    emitCustomEvent: (eventName: string, value: Record<string, any>) => void
+    emitCustomEvent: (
+      eventName: string,
+      value: Record<string, any>,
+      options?: EmitCustomEventOptions,
+    ) => void
   }
 
 export type ToolExecuteFunction<

package/src/utilities/durability-batch.ts

@@ -0,0 +1,48 @@
+import { CUSTOM_EVENT } from '../custom-events'
+import type { CustomEvent, StreamChunk } from '../types'
+import { tanstackMetadata, withTanstackMetadata } from './merge-metadata'
+
+/**
+ * High-volume CUSTOM names that stay in the durability batch.
+ * Everything else flushes as soon as it is emitted.
+ */
+const BATCHED_CUSTOM_EVENT_NAMES = new Set<string>([
+  CUSTOM_EVENT.PROCESS_STDOUT,
+  CUSTOM_EVENT.PROCESS_STDERR,
+  'sandbox.file',
+  'sandbox.file.diff',
+])
+
+function hasBatchHint(chunk: StreamChunk): boolean {
+  const tanstack = tanstackMetadata(chunk)
+  if (tanstack == null) return false
+  return Reflect.get(tanstack, 'batch') === true
+}
+
+/** Mark a CUSTOM chunk so the durability producer keeps it in the batch. */
+export function withDurabilityBatchHint(chunk: CustomEvent): CustomEvent {
+  return withTanstackMetadata(chunk, { batch: true })
+}
+
+export function isDurabilityBatchedCustom(chunk: StreamChunk): boolean {
+  if (chunk.type !== 'CUSTOM') return false
+  if (BATCHED_CUSTOM_EVENT_NAMES.has(chunk.name)) return true
+  return hasBatchHint(chunk)
+}
+
+/**
+ * Drop the in-process batch hint so it does not sit in the log or on the wire.
+ */
+export function stripDurabilityBatchHint(chunk: StreamChunk): StreamChunk {
+  const tanstack = tanstackMetadata(chunk)
+  if (tanstack == null || Reflect.get(tanstack, 'batch') !== true) return chunk
+  Reflect.deleteProperty(tanstack, 'batch')
+  const metadata = chunk.metadata
+  if (metadata != null && Object.keys(tanstack).length === 0) {
+    Reflect.deleteProperty(metadata, 'tanstack')
+    if (Object.keys(metadata).length === 0) {
+      Reflect.deleteProperty(chunk, 'metadata')
+    }
+  }
+  return chunk
+}