@tanstack/ai 0.43.1 → 0.44.0

package/src/activities/generateSpeech/index.ts

@@ -11,11 +11,18 @@ import { resolveDebugOption } from '../../logger/resolve'
 import {
   applyGenerationResultTransforms,
   createGenerationContext,
+  runGenerationAbort,
   runGenerationError,
   runGenerationFinish,
   runGenerationStart,
   runGenerationUsage,
 } from '../middleware/run'
+import {
+  abortReasonMessage,
+  createActivityAbortControls,
+  isActivityAbortError,
+  raceWithAbort,
+} from '../../utilities/activity-abort'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
 import type { GenerationMiddleware } from '../middleware/types'
@@ -36,10 +43,11 @@ export const kind = 'tts' as const
 /**
  * Extract provider options from a TTSAdapter via ~types.
  */
-export type TTSProviderOptions<TAdapter> =
-  TAdapter extends TTSAdapter<any, any>
-    ? TAdapter['~types']['providerOptions']
-    : object
+export type TTSProviderOptions<TAdapter> = TAdapter extends {
+  '~types': { providerOptions: infer P extends object }
+}
+  ? P
+  : object
 
 // ===========================
 // Activity Options Type
@@ -92,6 +100,18 @@ export interface TTSActivityOptions<
   threadId?: string
   /** Stable run id for correlating this run when persisted. */
   runId?: string
+  /**
+   * Maximum duration of this activity invocation in milliseconds.
+   * No SDK-wide default — choose a value suitable for the provider and job.
+   * Composed with {@link abortSignal}; the first abort wins.
+   */
+  timeout?: number
+  /**
+   * Caller cancellation signal (request disconnects, job/runtime cancellation).
+   * Composed with {@link timeout} into an effective signal forwarded to the
+   * adapter. Request-specific — not stored on global provider client config.
+   */
+  abortSignal?: AbortSignal
 }
 
 // ===========================
@@ -175,12 +195,18 @@ async function runGenerateSpeech<
     middleware,
     threadId,
     runId,
+    timeout,
+    abortSignal: callerAbortSignal,
     ...rest
   } = options
   const model = adapter.model
   const requestId = createId('speech')
   const startTime = Date.now()
   const logger: InternalLogger = resolveDebugOption(options.debug)
+  const abortControls = createActivityAbortControls({
+    timeout,
+    abortSignal: callerAbortSignal,
+  })
   const providerName =
     (adapter as { name?: string; provider?: string }).provider ??
     (adapter as { name?: string }).name ??
@@ -223,7 +249,16 @@ async function runGenerateSpeech<
   })
 
   try {
-    const rawResult = await adapter.generateSpeech({ ...rest, model, logger })
+    const rawResult = await raceWithAbort(
+      adapter.generateSpeech({
+        ...rest,
+        model,
+        logger,
+        ...(abortControls.signal ? { abortSignal: abortControls.signal } : {}),
+      }),
+      abortControls.signal,
+    )
+    abortControls.clear()
     const result = await applyGenerationResultTransforms(mwCtx, rawResult)
     const duration = Date.now() - startTime
 
@@ -263,6 +298,7 @@ async function runGenerateSpeech<
 
     return result
   } catch (error) {
+    abortControls.clear()
     const duration = Date.now() - startTime
     const err = error as Error
     aiEventClient.emit('speech:request:error', {
@@ -274,10 +310,17 @@ async function runGenerateSpeech<
       modelOptions: rest.modelOptions as Record<string, unknown> | undefined,
       timestamp: Date.now(),
     })
-    await runGenerationError(middleware, mwCtx, {
-      error,
-      duration,
-    })
+    if (isActivityAbortError(error, abortControls.signal)) {
+      await runGenerationAbort(middleware, mwCtx, {
+        reason: abortReasonMessage(error, abortControls.signal),
+        duration,
+      })
+    } else {
+      await runGenerationError(middleware, mwCtx, {
+        error,
+        duration,
+      })
+    }
     logger.errors('generateSpeech activity failed', {
       error,
       source: 'generateSpeech',

package/src/activities/generateTranscription/index.ts

@@ -11,11 +11,18 @@ import { resolveDebugOption } from '../../logger/resolve'
 import {
   applyGenerationResultTransforms,
   createGenerationContext,
+  runGenerationAbort,
   runGenerationError,
   runGenerationFinish,
   runGenerationStart,
   runGenerationUsage,
 } from '../middleware/run'
+import {
+  abortReasonMessage,
+  createActivityAbortControls,
+  isActivityAbortError,
+  raceWithAbort,
+} from '../../utilities/activity-abort'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
 import type { GenerationMiddleware } from '../middleware/types'
@@ -40,10 +47,11 @@ export const kind = 'transcription' as const
 /**
  * Extract provider options from a TranscriptionAdapter via ~types.
  */
-export type TranscriptionProviderOptions<TAdapter> =
-  TAdapter extends TranscriptionAdapter<any, any>
-    ? TAdapter['~types']['providerOptions']
-    : object
+export type TranscriptionProviderOptions<TAdapter> = TAdapter extends {
+  '~types': { providerOptions: infer P extends object }
+}
+  ? P
+  : object
 
 // ===========================
 // Activity Options Type
@@ -99,6 +107,18 @@ export interface TranscriptionActivityOptions<
   threadId?: string
   /** Stable run id for correlating this run when persisted. */
   runId?: string
+  /**
+   * Maximum duration of this activity invocation in milliseconds.
+   * No SDK-wide default — choose a value suitable for the provider and job.
+   * Composed with {@link abortSignal}; the first abort wins.
+   */
+  timeout?: number
+  /**
+   * Caller cancellation signal (request disconnects, job/runtime cancellation).
+   * Composed with {@link timeout} into an effective signal forwarded to the
+   * adapter. Request-specific — not stored on global provider client config.
+   */
+  abortSignal?: AbortSignal
 }
 
 // ===========================
@@ -211,12 +231,18 @@ async function runGenerateTranscription<
     middleware,
     threadId,
     runId,
+    timeout,
+    abortSignal: callerAbortSignal,
     ...rest
   } = options
   const model = adapter.model
   const requestId = createId('transcription')
   const startTime = Date.now()
   const logger: InternalLogger = resolveDebugOption(options.debug)
+  const abortControls = createActivityAbortControls({
+    timeout,
+    abortSignal: callerAbortSignal,
+  })
   const providerName =
     (adapter as { name?: string; provider?: string }).provider ??
     (adapter as { name?: string }).name ??
@@ -258,7 +284,16 @@ async function runGenerateTranscription<
   })
 
   try {
-    const rawResult = await adapter.transcribe({ ...rest, model, logger })
+    const rawResult = await raceWithAbort(
+      adapter.transcribe({
+        ...rest,
+        model,
+        logger,
+        ...(abortControls.signal ? { abortSignal: abortControls.signal } : {}),
+      }),
+      abortControls.signal,
+    )
+    abortControls.clear()
     const result = await applyGenerationResultTransforms(mwCtx, rawResult)
     const duration = Date.now() - startTime
 
@@ -286,6 +321,7 @@ async function runGenerateTranscription<
 
     return result
   } catch (error) {
+    abortControls.clear()
     const duration = Date.now() - startTime
     const err = error as Error
     aiEventClient.emit('transcription:request:error', {
@@ -297,10 +333,17 @@ async function runGenerateTranscription<
       modelOptions: rest.modelOptions as Record<string, unknown> | undefined,
       timestamp: Date.now(),
     })
-    await runGenerationError(middleware, mwCtx, {
-      error,
-      duration,
-    })
+    if (isActivityAbortError(error, abortControls.signal)) {
+      await runGenerationAbort(middleware, mwCtx, {
+        reason: abortReasonMessage(error, abortControls.signal),
+        duration,
+      })
+    } else {
+      await runGenerationError(middleware, mwCtx, {
+        error,
+        duration,
+      })
+    }
     logger.errors('generateTranscription activity failed', {
       error,
       source: 'generateTranscription',

package/src/activities/generateVideo/index.ts

@@ -19,6 +19,13 @@ import {
   runGenerationStart,
   runGenerationUsage,
 } from '../middleware/run'
+import {
+  abortReasonMessage,
+  createActivityAbortControls,
+  isActivityAbortError,
+  raceWithAbort,
+  toAbortError,
+} from '../../utilities/activity-abort'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
 import type {
@@ -235,6 +242,24 @@ export type VideoCreateOptions<
    * job to resume.
    */
   middleware?: Array<GenerationMiddleware>
+  /**
+   * Maximum duration of this activity invocation in milliseconds.
+   * No SDK-wide default — choose a value suitable for the provider and job.
+   * Composed with {@link abortSignal}; the first abort wins.
+   *
+   * In stream mode this bounds the full create→poll→complete lifecycle and
+   * complements {@link maxDuration} (which defaults to 10 minutes). When both
+   * are set, the shorter limit wins via signal composition against the
+   * polling deadline.
+   */
+  timeout?: number
+  /**
+   * Caller cancellation signal (request disconnects, job/runtime cancellation).
+   * Composed with {@link timeout} into an effective signal forwarded to the
+   * adapter on job submission. Request-specific — not stored on global
+   * provider client config.
+   */
+  abortSignal?: AbortSignal
 } & ({} extends VideoProviderOptions<TAdapter>
     ? {
         /** Provider-specific options for video generation */ modelOptions?: VideoProviderOptions<TAdapter>
@@ -413,11 +438,24 @@ function videoRunIdForJob(provider: string, jobId: string): string {
 async function runCreateVideoJob<
   TAdapter extends VideoAdapter<string, any, any, any, any, any>,
 >(options: VideoCreateOptions<TAdapter, boolean>): Promise<VideoJobResult> {
-  const { adapter, prompt, size, duration, modelOptions, middleware } = options
+  const {
+    adapter,
+    prompt,
+    size,
+    duration,
+    modelOptions,
+    middleware,
+    timeout,
+    abortSignal: callerAbortSignal,
+  } = options
   const model = adapter.model
   const requestId = createId('video')
   const startTime = Date.now()
   const logger: InternalLogger = resolveDebugOption(options.debug)
+  const abortControls = createActivityAbortControls({
+    timeout,
+    abortSignal: callerAbortSignal,
+  })
   const providerName =
     (adapter as { name?: string; provider?: string }).provider ??
     (adapter as { name?: string }).name ??
@@ -451,24 +489,38 @@ async function runCreateVideoJob<
 
   let jobResult: VideoJobResult
   try {
-    jobResult = await adapter.createVideoJob({
-      model,
-      prompt,
-      size,
-      duration,
-      modelOptions,
-      logger,
-    })
+    jobResult = await raceWithAbort(
+      adapter.createVideoJob({
+        model,
+        prompt,
+        size,
+        duration,
+        modelOptions,
+        logger,
+        ...(abortControls.signal ? { abortSignal: abortControls.signal } : {}),
+      }),
+      abortControls.signal,
+    )
+    abortControls.clear()
   } catch (error) {
+    abortControls.clear()
     // No jobId exists, so this run can only be keyed on the request. Start it
     // just to fail it: `generationRuns.update` on an unknown run id is a no-op
     // by contract, so without the `onStart` the failure would persist nowhere.
     const failedCtx = contextFor()
     await runGenerationStart(middleware, failedCtx)
-    await runGenerationError(middleware, failedCtx, {
-      error,
-      duration: Date.now() - startTime,
-    })
+    const elapsed = Date.now() - startTime
+    if (isActivityAbortError(error, abortControls.signal)) {
+      await runGenerationAbort(middleware, failedCtx, {
+        reason: abortReasonMessage(error, abortControls.signal),
+        duration: elapsed,
+      })
+    } else {
+      await runGenerationError(middleware, failedCtx, {
+        error,
+        duration: elapsed,
+      })
+    }
     logger.errors('generateVideo activity failed', {
       error,
       source: 'generateVideo',
@@ -489,8 +541,25 @@ async function runCreateVideoJob<
   return await applyGenerationResultTransforms(mwCtx, jobResult)
 }
 
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms))
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  if (!signal) {
+    return new Promise((resolve) => setTimeout(resolve, ms))
+  }
+  if (signal.aborted) {
+    return Promise.reject(toAbortError(signal.reason))
+  }
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal.removeEventListener('abort', onAbort)
+      resolve()
+    }, ms)
+    const onAbort = () => {
+      clearTimeout(timer)
+      signal.removeEventListener('abort', onAbort)
+      reject(toAbortError(signal.reason))
+    }
+    signal.addEventListener('abort', onAbort, { once: true })
+  })
 }
 
 /**
@@ -500,7 +569,16 @@ function sleep(ms: number): Promise<void> {
 async function* runStreamingVideoGeneration<
   TAdapter extends VideoAdapter<string, any, any, any, any, any>,
 >(options: VideoCreateOptions<TAdapter, true>): AsyncIterable<StreamChunk> {
-  const { adapter, prompt, size, duration, modelOptions, middleware } = options
+  const {
+    adapter,
+    prompt,
+    size,
+    duration,
+    modelOptions,
+    middleware,
+    timeout,
+    abortSignal: callerAbortSignal,
+  } = options
   const model = adapter.model
   const runId = options.runId ?? createId('run')
   const requestId = createId('video')
@@ -508,6 +586,10 @@ async function* runStreamingVideoGeneration<
   const pollingInterval = options.pollingInterval ?? 2000
   const maxDuration = options.maxDuration ?? 600_000
   const logger: InternalLogger = resolveDebugOption(options.debug)
+  const abortControls = createActivityAbortControls({
+    timeout,
+    abortSignal: callerAbortSignal,
+  })
   const providerName =
     (adapter as { name?: string; provider?: string }).provider ??
     (adapter as { name?: string }).name ??
@@ -555,19 +637,24 @@ async function* runStreamingVideoGeneration<
     },
   )
 
-  // Tracks whether a terminal observer event (finish/error) has already fired,
-  // so the `finally` below can fire one on abandonment without double-firing.
+  // Tracks whether a terminal observer event (finish/error/abort) has already
+  // fired, so the `finally` below can fire one on abandonment without
+  // double-firing.
   let settled = false
   try {
     // Create the video generation job
-    const jobResult = await adapter.createVideoJob({
-      model,
-      prompt,
-      size,
-      duration,
-      modelOptions,
-      logger,
-    })
+    const jobResult = await raceWithAbort(
+      adapter.createVideoJob({
+        model,
+        prompt,
+        size,
+        duration,
+        modelOptions,
+        logger,
+        ...(abortControls.signal ? { abortSignal: abortControls.signal } : {}),
+      }),
+      abortControls.signal,
+    )
 
     yield {
       type: 'CUSTOM',
@@ -579,7 +666,7 @@ async function* runStreamingVideoGeneration<
     // Poll for completion
     const startTime = Date.now()
     while (Date.now() - startTime < maxDuration) {
-      await sleep(pollingInterval)
+      await sleep(pollingInterval, abortControls.signal)
 
       const statusResult = await adapter.getVideoStatus(jobResult.jobId)
 
@@ -632,6 +719,7 @@ async function* runStreamingVideoGeneration<
           usage: urlResult.usage,
         })
         settled = true
+        abortControls.clear()
 
         yield {
           type: 'CUSTOM',
@@ -657,15 +745,24 @@ async function* runStreamingVideoGeneration<
 
     throw new Error('Video generation timed out')
   } catch (error: unknown) {
+    abortControls.clear()
     const payload = toRunErrorPayload(error, 'Video generation failed')
-    // Mark settled before firing onError: if a user error-hook throws, the
-    // `finally` below must still not double-fire onAbort over the same op
+    // Mark settled before firing terminal hooks: if a user error-hook throws,
+    // the `finally` below must still not double-fire onAbort over the same op
     // (which would mask the original error and end the span twice).
     settled = true
-    await runGenerationError(middleware, mwCtx, {
-      error,
-      duration: Date.now() - obsStartTime,
-    })
+    const elapsed = Date.now() - obsStartTime
+    if (isActivityAbortError(error, abortControls.signal)) {
+      await runGenerationAbort(middleware, mwCtx, {
+        reason: abortReasonMessage(error, abortControls.signal),
+        duration: elapsed,
+      })
+    } else {
+      await runGenerationError(middleware, mwCtx, {
+        error,
+        duration: elapsed,
+      })
+    }
     logger.errors('generateVideo activity failed', {
       message: payload.message,
       code: payload.code,
@@ -681,6 +778,7 @@ async function* runStreamingVideoGeneration<
       timestamp: Date.now(),
     } as StreamChunk
   } finally {
+    abortControls.clear()
     if (!settled) {
       // The consumer abandoned the stream (broke the `for await` loop or
       // disconnected) before completion, so the generator is being unwound at

package/src/activities/index.ts

@@ -21,6 +21,8 @@ import type { AnyAudioAdapter } from './generateAudio/adapter'
 import type { AnyVideoAdapter } from './generateVideo/adapter'
 import type { AnyTTSAdapter } from './generateSpeech/adapter'
 import type { AnyTranscriptionAdapter } from './generateTranscription/adapter'
+import type { AnyEmbeddingAdapter } from './embed/adapter'
+import type { AnyRerankAdapter } from './rerank/adapter'
 
 // ===========================
 // Chat Activity
@@ -66,6 +68,25 @@ export {
   type InferTextProviderOptions,
 } from './summarize/chat-stream-summarize'
 
+// ===========================
+// Rerank Activity
+// ===========================
+
+export {
+  kind as rerankKind,
+  rerank,
+  createRerankOptions,
+  type RerankActivityOptions,
+  type RerankProviderOptions,
+} from './rerank/index'
+
+export {
+  BaseRerankAdapter,
+  type RerankAdapter,
+  type RerankAdapterConfig,
+  type AnyRerankAdapter,
+} from './rerank/adapter'
+
 // ===========================
 // Image Activity
 // ===========================
@@ -170,6 +191,25 @@ export {
   type AnyTranscriptionAdapter,
 } from './generateTranscription/adapter'
 
+// ===========================
+// Embed Activity
+// ===========================
+
+export {
+  kind as embeddingKind,
+  embed,
+  type EmbedOptions,
+  type EmbedProviderOptionsForModel,
+  type EmbeddingInputForModel,
+} from './embed/index'
+
+export {
+  BaseEmbeddingAdapter,
+  type EmbeddingAdapter,
+  type EmbeddingAdapterConfig,
+  type AnyEmbeddingAdapter,
+} from './embed/adapter'
+
 // ===========================
 // Adapter Union Types
 // ===========================
@@ -183,6 +223,8 @@ export type AIAdapter =
   | AnyVideoAdapter
   | AnyTTSAdapter
   | AnyTranscriptionAdapter
+  | AnyEmbeddingAdapter
+  | AnyRerankAdapter
 
 /** Union type of all adapter kinds */
 export type AdapterKind =
@@ -193,3 +235,5 @@ export type AdapterKind =
   | 'video'
   | 'tts'
   | 'transcription'
+  | 'embedding'
+  | 'rerank'

package/src/activities/middleware/types.ts

@@ -41,6 +41,8 @@ export type GenerationActivity =
   | 'audio'
   | 'tts'
   | 'transcription'
+  | 'embedding'
+  | 'rerank'
   | 'summarize'
 
 /**

package/src/activities/rerank/adapter.ts

@@ -0,0 +1,90 @@
+import type { RerankAdapterResult, RerankOptions } from '../../types'
+
+/**
+ * Configuration for rerank adapter instances
+ */
+export interface RerankAdapterConfig {
+  apiKey?: string
+  baseUrl?: string
+  timeout?: number
+  headers?: Record<string, string>
+}
+
+/**
+ * Rerank adapter interface with pre-resolved generics.
+ *
+ * An adapter is created by a provider function: `provider('model')` → `adapter`
+ * All type resolution happens at the provider call site, not in this interface.
+ *
+ * Generic parameters:
+ * - TModel: The specific model name (e.g. 'rerank-v3.5')
+ * - TProviderOptions: Provider-specific options (already resolved)
+ */
+export interface RerankAdapter<
+  TModel extends string = string,
+  TProviderOptions extends object = Record<string, unknown>,
+> {
+  /** Discriminator for adapter kind */
+  readonly kind: 'rerank'
+  /** Adapter name identifier */
+  readonly name: string
+  /** The model this adapter is configured for */
+  readonly model: TModel
+
+  /**
+   * @internal Type-only properties for inference. Not assigned at runtime.
+   */
+  '~types': {
+    providerOptions: TProviderOptions
+  }
+
+  /**
+   * Rerank the given (pre-serialized) documents against the query, returning
+   * scored indices into `options.documents`. The activity layer maps these
+   * back to the caller's original documents.
+   */
+  rerank: (
+    options: RerankOptions<TProviderOptions>,
+  ) => Promise<RerankAdapterResult>
+}
+
+/**
+ * A RerankAdapter with any/unknown type parameters.
+ * Useful as a constraint in generic functions and interfaces.
+ */
+export type AnyRerankAdapter = RerankAdapter<any, any>
+
+/**
+ * Abstract base class for rerank adapters.
+ * Extend this class to implement a rerank adapter for a specific provider.
+ *
+ * Generic parameters match RerankAdapter - all pre-resolved by the provider function.
+ */
+export abstract class BaseRerankAdapter<
+  TModel extends string = string,
+  TProviderOptions extends object = Record<string, unknown>,
+> implements RerankAdapter<TModel, TProviderOptions> {
+  readonly kind = 'rerank' as const
+  abstract readonly name: string
+  readonly model: TModel
+
+  // Type-only property - never assigned at runtime
+  declare '~types': {
+    providerOptions: TProviderOptions
+  }
+
+  protected config: RerankAdapterConfig
+
+  constructor(config: RerankAdapterConfig = {}, model: TModel) {
+    this.config = config
+    this.model = model
+  }
+
+  abstract rerank(
+    options: RerankOptions<TProviderOptions>,
+  ): Promise<RerankAdapterResult>
+
+  protected generateId(): string {
+    return `${this.name}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`
+  }
+}