@tanstack/ai 0.63.0 → 0.64.0

package/src/activities/chat/index.ts

@@ -41,6 +41,7 @@ import {
 import { subagentHostMessageId } from '../../utilities/subagent-wire'
 import { withDurabilityBatchHint } from '../../utilities/durability-batch'
 import { normalizeStreamChunk } from '../../utilities/normalize-stream-chunk'
+import { isRedactedThinkingId } from '../../utilities/reasoning-encrypted-value'
 import { restorePublicUsage } from '../../utilities/restore-inbound-chunk'
 import type { AdapterYieldChunk } from '../../utilities/adapter-yield-chunk'
 import {
@@ -523,6 +524,8 @@ export interface TextActivityOptions<
   abortController?: TextOptions['abortController']
   /** Strategy for controlling the agent loop */
   agentLoopStrategy?: TextOptions['agentLoopStrategy']
+  /** How the server tools of one model turn run. Default `'parallel'`. */
+  toolExecution?: TextOptions['toolExecution']
   /**
    * Optional configuration for lazy-tool discovery (tools marked `lazy: true`).
    * Tunes how much of each lazy tool's description appears in the discovery
@@ -853,8 +856,7 @@ class TextEngine<
   private currentMessageCreatedAt: Date | null = null
   private streamIdentityCaptured = false
   private accumulatedContent = ''
-  private accumulatedThinking: Array<{ content: string; signature?: string }> =
-    []
+  private accumulatedThinking: NonNullable<ModelMessage['thinking']> = []
   /**
    * Arrival order of this iteration's thinking steps, text and tool calls.
    * A ModelMessage keeps `thinking` apart from `content`/`toolCalls`, so a
@@ -866,6 +868,7 @@ class TextEngine<
   private turnParts: Array<TurnPart> | null = []
   private currentThinkingContent = ''
   private currentThinkingSignature = ''
+  private currentThinkingRedacted = false
   private eventOptions?: Record<string, unknown> | undefined
   private eventToolNames?: Array<string>
   private finishedEvent: RunFinishedEvent | null = null
@@ -1524,6 +1527,7 @@ class TextEngine<
     this.turnParts = []
     this.currentThinkingContent = ''
     this.currentThinkingSignature = ''
+    this.currentThinkingRedacted = false
 
     this.finishedEvent = null
     this.streamedToolErrorResults.clear()
@@ -1992,6 +1996,7 @@ class TextEngine<
         ...(this.currentThinkingSignature && {
           signature: this.currentThinkingSignature,
         }),
+        ...(this.currentThinkingRedacted && { redacted: true }),
       })
       if (this.turnParts) {
         const placeholder = [...this.turnParts]
@@ -2009,6 +2014,7 @@ class TextEngine<
       }
       this.currentThinkingContent = ''
       this.currentThinkingSignature = ''
+      this.currentThinkingRedacted = false
     }
   }
 
@@ -2036,6 +2042,7 @@ class TextEngine<
     if (typeof chunk.signature === 'string' && chunk.signature !== '') {
       this.noteThinkingStepPosition()
       this.currentThinkingSignature = chunk.signature
+      this.currentThinkingRedacted = isRedactedThinkingId(chunk.stepId)
     }
   }
 
@@ -2065,6 +2072,7 @@ class TextEngine<
     }
     this.noteThinkingStepPosition()
     this.currentThinkingSignature = chunk.encryptedValue
+    this.currentThinkingRedacted = isRedactedThinkingId(chunk.entityId)
   }
 
   /**
@@ -2202,6 +2210,7 @@ class TextEngine<
         cancelledToolCallIds: this.resumeCancelledToolCallIds,
         inputResponses: this.resumeInputResponses,
       },
+      this.params.toolExecution,
     )
 
     // Consume the async generator, yielding custom events and collecting the return value
@@ -2390,6 +2399,7 @@ class TextEngine<
         cancelledToolCallIds: this.resumeCancelledToolCallIds,
         inputResponses: this.resumeInputResponses,
       },
+      this.params.toolExecution,
     )
 
     // Consume the async generator, yielding custom events and collecting the return value
@@ -2579,7 +2589,7 @@ class TextEngine<
       ),
     )
     type Segment = {
-      thinking: Array<{ content: string; signature?: string }>
+      thinking: NonNullable<ModelMessage['thinking']>
       text: string
       callIds: Array<string>
     }

package/src/activities/chat/messages.ts

@@ -11,6 +11,7 @@ import {
   tanstackMetadata,
   withTanstackMetadata,
 } from '../../utilities/merge-metadata'
+import { isRedactedThinkingId } from '../../utilities/reasoning-encrypted-value'
 import {
   splitSubagentWire,
   subagentWireText,
@@ -72,6 +73,13 @@ function encryptedValueFrom(value: object): string | undefined {
   return nonEmptyString(tanstackMetadata(value)?.signature)
 }
 
+/** `{ redacted: true }` when a reasoning message's id marks a redacted block. */
+function redactedFrom(value: object) {
+  return 'id' in value && isRedactedThinkingId(value.id)
+    ? { redacted: true }
+    : {}
+}
+
 function toolCallFromWire(toolCall: ToolCall, bag: unknown): ToolCall {
   const fromBag =
     bag != null && typeof bag === 'object' && !Array.isArray(bag)
@@ -246,7 +254,7 @@ function convertOwnMessages(
   }
 
   const modelMessages: Array<ModelMessage> = []
-  let pendingThinking: Array<{ content: string; signature?: string }> = []
+  let pendingThinking: NonNullable<ModelMessage['thinking']> = []
   for (const msg of messages) {
     if ('parts' in msg) {
       modelMessages.push(...uiMessageToModelMessages(msg))
@@ -273,6 +281,7 @@ function convertOwnMessages(
         pendingThinking.push({
           content: typeof content === 'string' ? content : '',
           ...(signature !== undefined ? { signature } : {}),
+          ...redactedFrom(msg),
         })
       }
       continue
@@ -663,7 +672,7 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
   // shared UI id on each one so persistence can retain the original identity.
   const messageList: Array<ModelMessage> = []
   let current = createSegment()
-  let pendingThinking: Array<{ content: string; signature?: string }> = []
+  let pendingThinking: NonNullable<ModelMessage['thinking']> = []
 
   // Track emitted tool result IDs to avoid duplicates.
   // A tool call can have BOTH an explicit tool-result part AND an output
@@ -764,6 +773,7 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
           pendingThinking.push({
             content: part.content,
             ...(part.signature && { signature: part.signature }),
+            ...(part.redacted && { redacted: true }),
           })
         }
         break
@@ -898,6 +908,7 @@ export function modelMessageToUIMessage(
         type: 'thinking',
         content: thinking.content,
         ...(thinking.signature && { signature: thinking.signature }),
+        ...(thinking.redacted && { redacted: true }),
       })
     }
   }
@@ -1121,6 +1132,7 @@ export function aguiSnapshotMessageToUIMessage(
                   type: 'thinking' as const,
                   content,
                   ...(signature !== undefined ? { signature } : {}),
+                  ...redactedFrom(message),
                 },
               ]
             : [],

package/src/activities/chat/stream/message-updaters.ts

@@ -5,6 +5,7 @@
  * These are used by StreamProcessor to manage the message array.
  */
 
+import { isRedactedThinkingId } from '../../../utilities/reasoning-encrypted-value'
 import { parsePartialJSON } from './json-parser'
 import type {
   ContentPart,
@@ -483,12 +484,16 @@ export function updateThinkingPart(
     // not carry one; losing it would strip the provider's encrypted reasoning
     // from a message that is about to be sent back.
     const nextSignature = signature ?? adopted?.signature
+    // A hydrated part has no stepId to carry the redacted marker, so it keeps
+    // its own flag.
+    const redacted = isRedactedThinkingId(stepId) || adopted?.redacted === true
 
     const thinkingPart: ThinkingPart = {
       type: 'thinking',
       content,
       stepId,
       ...(nextSignature && { signature: nextSignature }),
+      ...(redacted && { redacted: true }),
     }
 
     if (thinkingPartIndex >= 0) {

package/src/activities/chat/tools/schema-converter.ts

@@ -230,6 +230,14 @@ export interface ConvertSchemaOptions {
    * @default false
    */
   forStructuredOutput?: boolean
+  /**
+   * Which view of a Standard JSON Schema to convert. A schema with a
+   * transform or a pipe has a different `output` view. Use `'output'` to
+   * describe the value that parsing returns.
+   *
+   * @default 'input'
+   */
+  io?: 'input' | 'output'
 }
 
 /**
@@ -238,16 +246,20 @@ export interface ConvertSchemaOptions {
  *
  * - Standard JSON Schemas are rebuilt structurally (dropping `$schema`, which
  *   LLM providers ignore) and given the explicit `type`/`properties`/`required`
- *   defaults object shapes need downstream.
+ *   defaults object shapes need downstream. `io` picks the `input` (default)
+ *   or `output` view.
  * - Plain `JSONSchema` inputs are rebuilt into the typed view; non-object inputs
  *   are surfaced untouched (they can't be widened).
  * - Standard Schema validators lacking a `~standard.jsonSchema` converter throw
  *   with actionable guidance, rather than shipping `{ '~standard': … }` to the
  *   provider and producing an opaque downstream error.
  */
-function toTypedJsonSchema(schema: SchemaInput): JSONSchema | undefined {
+function toTypedJsonSchema(
+  schema: SchemaInput,
+  io: 'input' | 'output' = 'input',
+): JSONSchema | undefined {
   if (isStandardJSONSchema(schema)) {
-    const jsonSchema = schema['~standard'].jsonSchema.input({
+    const jsonSchema = schema['~standard'].jsonSchema[io]({
       target: 'draft-07',
     })
     const result: JSONSchema = toJsonSchema(jsonSchema)
@@ -340,7 +352,7 @@ export function convertSchemaToJsonSchema(
 ): JSONSchema | undefined {
   if (!schema) return undefined
 
-  const { forStructuredOutput = false } = options
+  const { forStructuredOutput = false, io } = options
 
   // Plain-JSONSchema passthrough: with no widening requested, return the schema
   // by reference so callers comparing via `===` keep identity. Only the widening
@@ -353,7 +365,7 @@ export function convertSchemaToJsonSchema(
     return schema
   }
 
-  const base = toTypedJsonSchema(schema)
+  const base = toTypedJsonSchema(schema, io)
   // Non-object inputs can't be widened; surface them untouched.
   if (!base || typeof base !== 'object') return base
   if (!forStructuredOutput) return base

package/src/activities/chat/tools/tool-calls.ts

@@ -1,6 +1,7 @@
 import { normalizeToolResult } from '../../../utilities/tool-result'
 import { tanstackMetadata } from '../../../utilities/merge-metadata'
 import { isProviderExecutedToolCall } from '../../../utilities/provider-executed'
+import { mergeStreams } from '../../../utilities/merge-streams'
 import type { AdapterYieldChunk } from '../../../utilities/adapter-yield-chunk'
 import {
   StandardSchemaValidationError,
@@ -18,6 +19,7 @@ import type {
   ModelMessage,
   RunFinishedEvent,
   StreamChunk,
+  TextOptions,
   Tool,
   ToolCall,
   ToolCallArgsEvent,
@@ -887,6 +889,9 @@ async function buildClientToolResult(
  * @param approvals - Map keyed by toolCallId (or `approval_${toolCallId}`) → ToolApprovalResolution
  * @param clientResults - Map of client-side execution results (toolCallId -> result)
  * @param createCustomEventChunk - Factory to create CustomEvent chunks (optional)
+ * @param toolExecution - `'parallel'` (default) prepares every call in call
+ *   order, then starts the server tools together. `'sequential'` runs one
+ *   call at a time. Results come back in call order either way.
  */
 export async function* executeToolCalls<TContext = unknown>(
   toolCalls: Array<ToolCall>,
@@ -902,12 +907,12 @@ export async function* executeToolCalls<TContext = unknown>(
   userContext?: TContext,
   abortSignal?: AbortSignal,
   resumeState?: ToolResumeExecutionState,
+  toolExecution: NonNullable<TextOptions['toolExecution']> = 'parallel',
 ): AsyncGenerator<CustomEvent | StreamChunk, ExecuteToolCallsResult, void> {
   const results: Array<ToolResult> = []
   const needsApproval: Array<ApprovalRequest> = []
   const needsClientExecution: Array<ClientToolRequest> = []
   const inputRequired: Array<McpInputRequest> = []
-  const subagentInterrupts: Array<Interrupt> = []
 
   // Create tool lookup map
   const toolMap = new Map<string, AnyTool>()
@@ -915,6 +920,66 @@ export async function* executeToolCalls<TContext = unknown>(
     toolMap.set(tool.name, tool)
   }
 
+  const runsInOrder = toolExecution === 'sequential'
+  // Parallel mode collects the server runs here. `mergeStreams` starts them
+  // together after the loop.
+  const runs: Array<AsyncGenerator<CustomEvent | StreamChunk, void, void>> = []
+  // Errors thrown by a run or a before-hook. They are rethrown only after every
+  // started tool has finished, so no tool outlives the batch.
+  const failures: Array<unknown> = []
+  // Each call's subagent interrupts, so they come back in call order.
+  const interruptsByCall = new Map<string, Array<Interrupt>>()
+
+  // A tool that has not started when the run aborts never starts. It gets an
+  // error result, so every call of the batch still has a result.
+  async function* runServerTool(
+    toolCall: ToolCall,
+    tool: AnyTool,
+    toolName: string,
+    input: unknown,
+    context: ToolExecutionContext<TContext>,
+    pendingEvents: Array<CustomEvent | StreamChunk>,
+  ): AsyncGenerator<CustomEvent | StreamChunk, void, void> {
+    try {
+      if (abortSignal?.aborted) {
+        results.push({
+          toolCallId: toolCall.id,
+          toolName,
+          result: { error: 'Operation aborted' },
+          input,
+          state: 'output-error',
+          duration: 0,
+        })
+        await middlewareHooks?.onAfterToolCall?.({
+          toolCall,
+          tool,
+          toolName,
+          toolCallId: toolCall.id,
+          ok: false,
+          duration: 0,
+          error: new Error('Operation aborted'),
+        })
+        return
+      }
+      const interrupts: Array<Interrupt> = []
+      interruptsByCall.set(toolCall.id, interrupts)
+      yield* executeServerTool(
+        toolCall,
+        tool,
+        toolName,
+        input,
+        context,
+        pendingEvents,
+        results,
+        middlewareHooks,
+        inputRequired,
+        interrupts,
+      )
+    } catch (error) {
+      failures.push(error)
+    }
+  }
+
   // Batch gating: when any tool in the batch still needs an approval decision,
   // defer all execution so side effects don't happen before the user decides.
   const hasPendingApprovals = toolCalls.some((tc) => {
@@ -1128,52 +1193,7 @@ export async function* executeToolCalls<TContext = unknown>(
       const approvalId = `approval_${toolCall.id}`
       const resolution = approvalResolution(approvals, toolCall.id)
 
-      // Check if approval decision exists
-      if (resolution !== undefined) {
-        const approved = isApproved(resolution)
-
-        if (approved) {
-          input = editedApprovalArgs(resolution) ?? input
-          // Apply middleware before-hook for approved tools
-          if (middlewareHooks) {
-            const decision = await applyBeforeToolCallDecision(
-              toolCall,
-              tool,
-              input,
-              toolName,
-              middlewareHooks,
-              results,
-            )
-            if (!decision.proceed) continue
-            input = decision.input
-          }
-
-          yield* executeServerTool(
-            toolCall,
-            tool,
-            toolName,
-            input,
-            context,
-            pendingEvents,
-            results,
-            middlewareHooks,
-            inputRequired,
-            subagentInterrupts,
-          )
-        } else {
-          // User declined
-          results.push({
-            toolCallId: toolCall.id,
-            toolName,
-            result:
-              resumeState?.deniedToolResults?.get(toolCall.id) ??
-              deniedApprovalResult(resolution),
-            input,
-            state: 'output-error',
-            outcome: 'denied',
-          })
-        }
-      } else {
+      if (resolution === undefined) {
         // Need approval
         needsApproval.push({
           toolCallId: toolCall.id,
@@ -1181,43 +1201,81 @@ export async function* executeToolCalls<TContext = unknown>(
           input,
           approvalId,
         })
+        continue
       }
-      continue
+      if (!isApproved(resolution)) {
+        // User declined
+        results.push({
+          toolCallId: toolCall.id,
+          toolName,
+          result:
+            resumeState?.deniedToolResults?.get(toolCall.id) ??
+            deniedApprovalResult(resolution),
+          input,
+          state: 'output-error',
+          outcome: 'denied',
+        })
+        continue
+      }
+      // Approved: run it like any other server tool below.
+      input = editedApprovalArgs(resolution) ?? input
     }
 
-    // CASE 3: Normal server tool - execute immediately
+    // CASE 3: Server tool, approved or with no approval
     if (middlewareHooks) {
-      const decision = await applyBeforeToolCallDecision(
-        toolCall,
-        tool,
-        input,
-        toolName,
-        middlewareHooks,
-        results,
-      )
+      let decision: Awaited<ReturnType<typeof applyBeforeToolCallDecision>>
+      try {
+        decision = await applyBeforeToolCallDecision(
+          toolCall,
+          tool,
+          input,
+          toolName,
+          middlewareHooks,
+          results,
+        )
+      } catch (error) {
+        // The calls prepared so far still run, as they would one at a time.
+        failures.push(error)
+        break
+      }
       if (!decision.proceed) continue
       input = decision.input
     }
 
-    yield* executeServerTool(
+    const run = runServerTool(
       toolCall,
       tool,
       toolName,
       input,
       context,
       pendingEvents,
-      results,
-      middlewareHooks,
-      inputRequired,
-      subagentInterrupts,
     )
+    if (!runsInOrder) {
+      runs.push(run)
+      continue
+    }
+    yield* run
+    if (failures.length > 0) break
   }
 
+  yield* mergeStreams(runs)
+  if (failures.length > 0) throw failures[0]
+
+  // Parallel tools finish in any order. The model gets the results, input
+  // requests, and interrupts in the order it made the calls.
+  const callOrder = new Map(toolCalls.map((tc, index) => [tc.id, index]))
+  const byCallOrder = (a: { toolCallId: string }, b: { toolCallId: string }) =>
+    (callOrder.get(a.toolCallId) ?? 0) - (callOrder.get(b.toolCallId) ?? 0)
+  results.sort(byCallOrder)
+  inputRequired.sort(byCallOrder)
+
   return {
     results,
     needsApproval,
     needsClientExecution,
     inputRequired,
-    subagentInterrupts,
+    subagentInterrupts: toolCalls.flatMap(
+      (tc) => interruptsByCall.get(tc.id) ?? [],
+    ),
   }
 }

package/src/activities/generateSpeech/index.ts

@@ -445,7 +445,7 @@ export interface ListVoicesActivityOptions<
  * import { elevenlabsSpeech } from '@tanstack/ai-elevenlabs'
  *
  * const { voices } = await listVoices({
- *   adapter: elevenlabsSpeech('eleven_v3'),
+ *   adapter: elevenlabsSpeech('eleven_v4'),
  *   origins: ['generated', 'cloned'],
  * })
  * ```

package/src/activities/generateVideo/adapter.ts

@@ -1,3 +1,4 @@
+import { snapToDurationOption } from './snap'
 import type {
   ModelInputModalitiesByName,
   VideoGenerationOptions,
@@ -25,6 +26,12 @@ export type DurationOptions<T extends string | number | undefined> =
     }
   | { kind: 'none' }
 
+/**
+ * Spellings of one clip length: the number `6`, the string `"6"`, or the
+ * template `"6s"`.
+ */
+export type VideoDurationSpell<N extends number> = N | `${N}` | `${N}s`
+
 /**
  * Configuration for video adapter instances
  *
@@ -126,10 +133,15 @@ export interface VideoAdapter<
   availableDurations: () => DurationOptions<TModelDurationByName[TModel]>
 
   /**
-   * Coerce a raw seconds value to the closest valid duration for this model.
-   * Returns `undefined` for models with no duration field.
+   * Coerce `input` to the closest duration this model accepts.
+   * `input` may be seconds (`7`), a numeric string (`"7"`), a template
+   * (`"6s"`), or a keyword the model lists (`"auto"`).
+   * Returns `undefined` when the model has no duration field, or when
+   * `input` is a keyword that model does not list.
    */
-  snapDuration: (seconds: number) => TModelDurationByName[TModel] | undefined
+  snapDuration: (
+    input: number | string,
+  ) => TModelDurationByName[TModel] | undefined
 }
 
 /**
@@ -208,11 +220,13 @@ export abstract class BaseVideoAdapter<
   }
 
   /**
-   * Default implementation returns `undefined`. Adapters that have declared
-   * their per-model duration map should override.
+   * Uses `availableDurations()`. Adapters that declare a duration map only
+   * need to override that method.
    */
-  snapDuration(_seconds: number): TModelDurationByName[TModel] | undefined {
-    return undefined
+  snapDuration(
+    input: number | string,
+  ): TModelDurationByName[TModel] | undefined {
+    return snapToDurationOption(input, this.availableDurations())
   }
 
   protected generateId(): string {

package/src/activities/generateVideo/index.ts

@@ -173,10 +173,11 @@ export type VideoCreateOptions<
   /** Video size — format depends on the provider (e.g., "16:9", "1280x720") */
   size?: VideoSizeForAdapter<TAdapter>
   /**
-   * Video duration in seconds. Adapters that declare a per-model duration
-   * map narrow this to the model's valid union (e.g. `4 | 6 | 8` for Veo 3).
-   * Pass `adapter.snapDuration(seconds)` to coerce raw seconds to a valid
-   * value.
+   * Video duration. Adapters that declare a per-model duration map narrow
+   * this to that model's union (for example `4 | 6 | 8` for Veo 3, or
+   * `4 | "4" | "4s"` for Sora). Pass `adapter.snapDuration(input)` to coerce
+   * a raw value. `input` may be seconds, a `"6s"` template, or `"auto"` when
+   * the model lists it.
    */
   duration?: VideoDurationForAdapter<TAdapter>
   /**

package/src/activities/generateVideo/snap.ts

@@ -1,8 +1,38 @@
 import type { DurationOptions } from './adapter'
 
+/**
+ * `"6"`, `"6s"`, and `"6.5s"` are seconds. Anything else (`"auto"`) is a
+ * keyword the model must list exactly.
+ */
+const DURATION_TEMPLATE = /^(\d+(?:\.\d+)?)s?$/
+
+/**
+ * Seconds from a caller-supplied template, or `null` when `input` is a
+ * keyword (`"auto"`) rather than a length.
+ */
+function templateToSeconds(input: string): number | null {
+  const match = DURATION_TEMPLATE.exec(input)
+  const digits = match?.[1]
+  if (digits === undefined) return null
+  const seconds = Number(digits)
+  return Number.isFinite(seconds) ? seconds : null
+}
+
+/**
+ * Seconds from a duration a caller wrote: `6`, `"6"`, or `"6s"`.
+ * Returns `undefined` for keywords such as `"auto"` and for non-finite numbers.
+ */
+export function durationToSeconds(input: number | string): number | undefined {
+  if (typeof input === 'number') {
+    return Number.isFinite(input) ? input : undefined
+  }
+  const seconds = templateToSeconds(input)
+  return seconds === null ? undefined : seconds
+}
+
 /**
  * Extract a numeric seconds value from a `DurationOptions` entry. Returns
- * `null` for entries that don't parse as a number — e.g. `'auto'`.
+ * `null` for entries that don't parse as a number, for example `'auto'`.
  *
  * Handles the keyword-with-unit form FAL uses for Luma/Veo (`'8s'`, `'9s'`)
  * by stripping a trailing `s`. Pure-numeric strings (`'5'`, `'10'`) parse via
@@ -12,14 +42,16 @@ function entryToSeconds(entry: string | number): number | null {
   if (typeof entry === 'number') {
     return Number.isFinite(entry) ? entry : null
   }
-  const stripped = entry.endsWith('s') ? entry.slice(0, -1) : entry
-  const parsed = Number(stripped)
-  return Number.isFinite(parsed) ? parsed : null
+  return templateToSeconds(entry)
 }
 
 /**
- * Snap a raw seconds value to the closest valid duration for a model's
- * `DurationOptions`.
+ * Snap a caller duration to the closest valid option.
+ *
+ * `input` may be seconds (`7`), a numeric string (`"7"`), a template
+ * (`"6s"`), or a keyword the model lists (`"auto"`). A keyword that is not
+ * in the set returns `undefined`. Equal numeric distances keep the earlier
+ * option.
  *
  * - `none`            → `undefined`
  * - `discrete`        → closest numeric-parseable entry; if none parse,
@@ -30,6 +62,32 @@ function entryToSeconds(entry: string | number): number | null {
  * @experimental Video generation is an experimental feature and may change.
  */
 export function snapToDurationOption<T extends string | number | undefined>(
+  input: number | string,
+  options: DurationOptions<T>,
+): T | undefined {
+  // NaN is not a length. Infinity still clamps inside snapSeconds.
+  if (typeof input === 'number' && Number.isNaN(input)) return undefined
+
+  if (typeof input === 'string') {
+    const seconds = templateToSeconds(input)
+    if (seconds === null) return matchKeyword(input, options)
+    return snapSeconds(seconds, options)
+  }
+  return snapSeconds(input, options)
+}
+
+function matchKeyword<T extends string | number | undefined>(
+  keyword: string,
+  options: DurationOptions<T>,
+): T | undefined {
+  if (options.kind !== 'discrete' && options.kind !== 'mixed') return undefined
+  for (const value of options.values) {
+    if (value === keyword) return value
+  }
+  return undefined
+}
+
+function snapSeconds<T extends string | number | undefined>(
   seconds: number,
   options: DurationOptions<T>,
 ): T | undefined {