@tanstack/ai 0.55.0 → 0.58.0

package/src/activities/index.ts

@@ -20,9 +20,11 @@ import type { AnyImageAdapter } from './generateImage/adapter'
 import type { AnyAudioAdapter } from './generateAudio/adapter'
 import type { AnyVideoAdapter } from './generateVideo/adapter'
 import type { AnyTTSAdapter } from './generateSpeech/adapter'
+import type { AnyVoiceAdapter } from './generateVoice/adapter'
 import type { AnyTranscriptionAdapter } from './generateTranscription/adapter'
 import type { AnyEmbeddingAdapter } from './embed/adapter'
 import type { AnyRerankAdapter } from './rerank/adapter'
+import type { AnyEvaluateAdapter } from './evaluate/adapter'
 import type { AnyWorldAdapter } from './generateWorld/adapter'
 import type { AnyLiveVideoAdapter } from './generateLiveVideo/adapter'
 
@@ -89,6 +91,46 @@ export {
   type AnyRerankAdapter,
 } from './rerank/adapter'
 
+// ===========================
+// Evaluate Activity
+// ===========================
+
+export {
+  kind as evaluateKind,
+  decide,
+  choice,
+  score,
+  boolean,
+  type EvaluateActivityOptions,
+  type EvaluateResult,
+  type EvaluateResultMeta,
+  type EvaluateProviderOptions,
+  type ChoiceAnswer,
+  type ScoreAnswer,
+  type BooleanAnswer,
+  type InferEvaluateAnswer,
+} from './evaluate/index'
+
+export {
+  BaseEvaluateAdapter,
+  type EvaluateAdapter,
+  type EvaluateAdapterConfig,
+  type AnyEvaluateAdapter,
+  type EvaluateOptions,
+  type EvaluateAdapterResult,
+  type EvaluateState,
+  type EvaluateInstructions,
+  type EvaluateJsonValue,
+  type WireQuestion,
+  type WireAnswer,
+  type WireChoiceQuestion,
+  type WireScoreQuestion,
+  type WireNoulQuestion,
+  type WireChoiceAnswer,
+  type WireScoreAnswer,
+  type WireNoulAnswer,
+} from './evaluate/adapter'
+
 // ===========================
 // Image Activity
 // ===========================
@@ -162,6 +204,8 @@ export { snapToDurationOption } from './generateVideo/snap'
 export {
   kind as ttsKind,
   generateSpeech,
+  listVoices,
+  type ListVoicesActivityOptions,
   type TTSActivityOptions,
   type TTSActivityResult,
   type TTSProviderOptions,
@@ -171,9 +215,30 @@ export {
   BaseTTSAdapter,
   type TTSAdapter,
   type TTSAdapterConfig,
+  type TTSCapabilities,
   type AnyTTSAdapter,
 } from './generateSpeech/adapter'
 
+// ===========================
+// Voice Activity
+// ===========================
+
+export {
+  kind as voiceKind,
+  generateVoice,
+  createVoiceOptions,
+  type VoiceActivityOptions,
+  type VoiceActivityResult,
+  type VoiceProviderOptions,
+} from './generateVoice/index'
+
+export {
+  BaseVoiceAdapter,
+  type VoiceAdapter,
+  type VoiceAdapterConfig,
+  type AnyVoiceAdapter,
+} from './generateVoice/adapter'
+
 // ===========================
 // Transcription Activity
 // ===========================
@@ -262,9 +327,11 @@ export type AIAdapter =
   | AnyAudioAdapter
   | AnyVideoAdapter
   | AnyTTSAdapter
+  | AnyVoiceAdapter
   | AnyTranscriptionAdapter
   | AnyEmbeddingAdapter
   | AnyRerankAdapter
+  | AnyEvaluateAdapter
   | AnyWorldAdapter
   | AnyLiveVideoAdapter
 
@@ -276,8 +343,10 @@ export type AdapterKind =
   | 'audio'
   | 'video'
   | 'tts'
+  | 'voice'
   | 'transcription'
   | 'embedding'
   | 'rerank'
+  | 'evaluate'
   | 'world'
   | 'liveVideo'

package/src/activities/middleware/types.ts

@@ -40,9 +40,11 @@ export type GenerationActivity =
   | 'video'
   | 'audio'
   | 'tts'
+  | 'voice'
   | 'transcription'
   | 'embedding'
   | 'rerank'
+  | 'evaluate'
   | 'summarize'
   | 'world'
   | 'liveVideo'

package/src/client.ts

@@ -3,6 +3,7 @@ import type {
   ImageGenerationOptions,
   TTSOptions,
   TranscriptionOptions,
+  VoiceGenerationOptions,
   VideoGenerationOptions,
   WorldGenerationOptions,
   LiveVideoGenerationOptions,
@@ -12,6 +13,7 @@ export type GenerationKind =
   | 'image'
   | 'audio'
   | 'tts'
+  | 'voice'
   | 'video'
   | 'transcription'
   | 'world'
@@ -21,6 +23,7 @@ type GenerationInputByKind = {
   image: Omit<ImageGenerationOptions, 'logger' | 'model'>
   audio: Omit<AudioGenerationOptions, 'logger' | 'model'>
   tts: Omit<TTSOptions, 'logger' | 'model'>
+  voice: Omit<VoiceGenerationOptions, 'logger' | 'model'>
   video: Omit<VideoGenerationOptions, 'logger' | 'model'>
   transcription: Omit<TranscriptionOptions, 'logger' | 'model'>
   world: Omit<WorldGenerationOptions, 'logger' | 'model'>
@@ -38,6 +41,7 @@ const generationKinds = [
   'image',
   'audio',
   'tts',
+  'voice',
   'video',
   'transcription',
   'world',
@@ -69,6 +73,31 @@ function assertGenerationKind(kind: unknown): asserts kind is GenerationKind {
   }
 }
 
+/**
+ * The input field(s) that identify a generation body for a kind. Most kinds
+ * have exactly one; `voice` accepts either of its two creation modes, so any
+ * one of its keys is enough.
+ */
+function requiredKeysForKind(kind: GenerationKind): Array<string> {
+  // Enumerated rather than defaulted so a new generation kind has to declare
+  // the field that identifies its body instead of silently inheriting
+  // `prompt`.
+  switch (kind) {
+    case 'tts':
+      return ['text']
+    case 'transcription':
+      return ['audio']
+    case 'voice':
+      return ['prompt', 'referenceAudio']
+    case 'image':
+    case 'audio':
+    case 'video':
+    case 'world':
+    case 'liveVideo':
+      return ['prompt']
+  }
+}
+
 function assertInputForKind(
   kind: GenerationKind,
   input: unknown,
@@ -77,21 +106,19 @@ function assertInputForKind(
     throw new Error(`Generation ${kind} input must be an object.`)
   }
 
-  const requiredKey =
-    kind === 'tts' ? 'text' : kind === 'transcription' ? 'audio' : 'prompt'
+  const requiredKeys = requiredKeysForKind(kind)
 
-  if (!hasOwnKey(input, requiredKey)) {
-    throw new Error(`Generation ${kind} input must include ${requiredKey}.`)
+  if (!requiredKeys.some((key) => hasOwnKey(input, key))) {
+    throw new Error(
+      `Generation ${kind} input must include ${requiredKeys.join(' or ')}.`,
+    )
   }
 }
 
 function isInputForKind(kind: GenerationKind, input: unknown): boolean {
   if (!isRecord(input)) return false
 
-  const requiredKey =
-    kind === 'tts' ? 'text' : kind === 'transcription' ? 'audio' : 'prompt'
-
-  return hasOwnKey(input, requiredKey)
+  return requiredKeysForKind(kind).some((key) => hasOwnKey(input, key))
 }
 
 function forwardedPropsFromEnvelope(

package/src/index.ts

@@ -3,11 +3,17 @@ export {
   chat,
   summarize,
   rerank,
+  decide,
+  choice,
+  score,
+  boolean,
   generateImage,
   generateAudio,
   generateVideo,
   getVideoJobStatus,
   generateSpeech,
+  listVoices,
+  generateVoice,
   generateTranscription,
   embed,
   generateWorld,
@@ -22,6 +28,7 @@ export { createImageOptions } from './activities/generateImage/index'
 export { createAudioOptions } from './activities/generateAudio/index'
 export { createVideoOptions } from './activities/generateVideo/index'
 export { createSpeechOptions } from './activities/generateSpeech/index'
+export { createVoiceOptions } from './activities/generateVoice/index'
 export { createTranscriptionOptions } from './activities/generateTranscription/index'
 export { createEmbedOptions } from './activities/embed/index'
 export { createWorldOptions } from './activities/generateWorld/index'
@@ -40,6 +47,9 @@ export type {
   AudioAdapter,
   AnyTTSAdapter,
   TTSAdapter,
+  TTSCapabilities,
+  AnyVoiceAdapter,
+  VoiceAdapter,
   AnyTranscriptionAdapter,
   TranscriptionAdapter,
   AnyVideoAdapter,
@@ -48,6 +58,14 @@ export type {
   EmbeddingAdapter,
   AnyRerankAdapter,
   RerankAdapter,
+  AnyEvaluateAdapter,
+  EvaluateAdapter,
+  ChoiceAnswer,
+  ScoreAnswer,
+  BooleanAnswer,
+  EvaluateResult,
+  WireQuestion,
+  WireAnswer,
   AnyWorldAdapter,
   WorldAdapter,
   AnyLiveVideoAdapter,
@@ -57,6 +75,9 @@ export type {
 // Rerank adapter base + types
 export { BaseRerankAdapter } from './activities/rerank/adapter'
 
+// Evaluate adapter base + types
+export { BaseEvaluateAdapter } from './activities/evaluate/adapter'
+
 // Tool definition
 export {
   toolDefinition,

package/src/middlewares/otel.ts

@@ -87,9 +87,11 @@ const OPERATION_NAME: Record<GenerationActivity, string> = {
   video: 'video_generation',
   audio: 'audio_generation',
   tts: 'text_to_speech',
+  voice: 'voice_generation',
   transcription: 'transcription',
   embedding: 'embeddings',
   rerank: 'rerank',
+  evaluate: 'evaluate',
   summarize: 'summarize',
   world: 'world_generation',
   liveVideo: 'live_video_generation',

package/src/realtime/index.ts

@@ -22,7 +22,7 @@ export type * from './types'
  * // 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' }),
+ *   adapter: openaiRealtimeToken({ model: 'gpt-realtime-2.1' }),
  * })
  * ```
  */

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))
 }