@tanstack/ai 0.36.0 → 0.37.0

package/dist/esm/activities/generateVideo/snap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snap.js","sources":["../../../../src/activities/generateVideo/snap.ts"],"sourcesContent":["import type { DurationOptions } from './adapter'\n\n/**\n * Extract a numeric seconds value from a `DurationOptions` entry. Returns\n * `null` for entries that don't parse as a number — e.g. `'auto'`.\n *\n * Handles the keyword-with-unit form FAL uses for Luma/Veo (`'8s'`, `'9s'`)\n * by stripping a trailing `s`. Pure-numeric strings (`'5'`, `'10'`) parse via\n * Number(). Numbers pass through.\n */\nfunction entryToSeconds(entry: string | number): number | null {\n  if (typeof entry === 'number') {\n    return Number.isFinite(entry) ? entry : null\n  }\n  const stripped = entry.endsWith('s') ? entry.slice(0, -1) : entry\n  const parsed = Number(stripped)\n  return Number.isFinite(parsed) ? parsed : null\n}\n\n/**\n * Snap a raw seconds value to the closest valid duration for a model's\n * `DurationOptions`.\n *\n * - `none`            → `undefined`\n * - `discrete`        → closest numeric-parseable entry; if none parse,\n *                       returns `values[0]` (keyword-only models like 'auto')\n * - `range`           → clamped to [min, max] and rounded to `step` (default 1)\n * - `mixed`           → closest of (discrete numerics ∪ range values)\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nexport function snapToDurationOption<T extends string | number | undefined>(\n  seconds: number,\n  options: DurationOptions<T>,\n): T | undefined {\n  switch (options.kind) {\n    case 'none':\n      return undefined\n\n    case 'discrete': {\n      return pickClosestDiscrete(seconds, options.values)\n    }\n\n    case 'range': {\n      const step = options.step ?? 1\n      const clamped = Math.min(options.max, Math.max(options.min, seconds))\n      const snapped =\n        Math.round((clamped - options.min) / step) * step + options.min\n      return Math.min(options.max, Math.max(options.min, snapped)) as T\n    }\n\n    case 'mixed': {\n      const discreteCandidate = pickClosestDiscrete(seconds, options.values)\n      if (!options.range) return discreteCandidate\n\n      const { min, max, step = 1 } = options.range\n      const clamped = Math.min(max, Math.max(min, seconds))\n      const rangeValue = Math.min(\n        max,\n        Math.max(min, Math.round((clamped - min) / step) * step + min),\n      )\n\n      // Compare distance; range value is numeric, discrete may have non-numeric\n      // first-entry fallback (return distance Infinity for non-numerics).\n      const discreteSeconds =\n        typeof discreteCandidate === 'number'\n          ? discreteCandidate\n          : discreteCandidate !== undefined\n            ? (entryToSeconds(discreteCandidate) ?? Infinity)\n            : Infinity\n\n      return Math.abs(discreteSeconds - seconds) <=\n        Math.abs(rangeValue - seconds)\n        ? discreteCandidate\n        : (rangeValue as T)\n    }\n  }\n}\n\nfunction pickClosestDiscrete<T extends string | number>(\n  seconds: number,\n  values: ReadonlyArray<T>,\n): T | undefined {\n  if (values.length === 0) return undefined\n\n  let best: T | undefined\n  let bestDistance = Infinity\n  for (const value of values) {\n    const v = entryToSeconds(value)\n    if (v === null) continue\n    const distance = Math.abs(v - seconds)\n    if (distance < bestDistance) {\n      bestDistance = distance\n      best = value\n    }\n  }\n\n  // Keyword-only set (no numeric-parseable entries) — fall back to first entry.\n  return best ?? values[0]\n}\n"],"names":[],"mappings":"AAUA,SAAS,eAAe,OAAuC;AAC7D,MAAI,OAAO,UAAU,UAAU;AAC7B,WAAO,OAAO,SAAS,KAAK,IAAI,QAAQ;AAAA,EAC1C;AACA,QAAM,WAAW,MAAM,SAAS,GAAG,IAAI,MAAM,MAAM,GAAG,EAAE,IAAI;AAC5D,QAAM,SAAS,OAAO,QAAQ;AAC9B,SAAO,OAAO,SAAS,MAAM,IAAI,SAAS;AAC5C;AAcO,SAAS,qBACd,SACA,SACe;AACf,UAAQ,QAAQ,MAAA;AAAA,IACd,KAAK;AACH,aAAO;AAAA,IAET,KAAK,YAAY;AACf,aAAO,oBAAoB,SAAS,QAAQ,MAAM;AAAA,IACpD;AAAA,IAEA,KAAK,SAAS;AACZ,YAAM,OAAO,QAAQ,QAAQ;AAC7B,YAAM,UAAU,KAAK,IAAI,QAAQ,KAAK,KAAK,IAAI,QAAQ,KAAK,OAAO,CAAC;AACpE,YAAM,UACJ,KAAK,OAAO,UAAU,QAAQ,OAAO,IAAI,IAAI,OAAO,QAAQ;AAC9D,aAAO,KAAK,IAAI,QAAQ,KAAK,KAAK,IAAI,QAAQ,KAAK,OAAO,CAAC;AAAA,IAC7D;AAAA,IAEA,KAAK,SAAS;AACZ,YAAM,oBAAoB,oBAAoB,SAAS,QAAQ,MAAM;AACrE,UAAI,CAAC,QAAQ,MAAO,QAAO;AAE3B,YAAM,EAAE,KAAK,KAAK,OAAO,EAAA,IAAM,QAAQ;AACvC,YAAM,UAAU,KAAK,IAAI,KAAK,KAAK,IAAI,KAAK,OAAO,CAAC;AACpD,YAAM,aAAa,KAAK;AAAA,QACtB;AAAA,QACA,KAAK,IAAI,KAAK,KAAK,OAAO,UAAU,OAAO,IAAI,IAAI,OAAO,GAAG;AAAA,MAAA;AAK/D,YAAM,kBACJ,OAAO,sBAAsB,WACzB,oBACA,sBAAsB,SACnB,eAAe,iBAAiB,KAAK,WACtC;AAER,aAAO,KAAK,IAAI,kBAAkB,OAAO,KACvC,KAAK,IAAI,aAAa,OAAO,IAC3B,oBACC;AAAA,IACP;AAAA,EAAA;AAEJ;AAEA,SAAS,oBACP,SACA,QACe;AACf,MAAI,OAAO,WAAW,EAAG,QAAO;AAEhC,MAAI;AACJ,MAAI,eAAe;AACnB,aAAW,SAAS,QAAQ;AAC1B,UAAM,IAAI,eAAe,KAAK;AAC9B,QAAI,MAAM,KAAM;AAChB,UAAM,WAAW,KAAK,IAAI,IAAI,OAAO;AACrC,QAAI,WAAW,cAAc;AAC3B,qBAAe;AACf,aAAO;AAAA,IACT;AAAA,EACF;AAGA,SAAO,QAAQ,OAAO,CAAC;AACzB;"}

package/dist/esm/activities/index.d.ts

@@ -0,0 +1,27 @@
+import { AnyTextAdapter } from './chat/adapter.js';
+import { AnySummarizeAdapter } from './summarize/adapter.js';
+import { AnyImageAdapter } from './generateImage/adapter.js';
+import { AnyAudioAdapter } from './generateAudio/adapter.js';
+import { AnyVideoAdapter } from './generateVideo/adapter.js';
+import { AnyTTSAdapter } from './generateSpeech/adapter.js';
+import { AnyTranscriptionAdapter } from './generateTranscription/adapter.js';
+export { kind as textKind, chat, type TextActivityOptions, type TextActivityResult, } from './chat/index.js';
+export { BaseTextAdapter, type AnyTextAdapter, type TextAdapter, type TextAdapterConfig, type StructuredOutputOptions, type StructuredOutputResult, } from './chat/adapter.js';
+export { kind as summarizeKind, summarize, type SummarizeActivityOptions, type SummarizeActivityResult, type SummarizeProviderOptions, } from './summarize/index.js';
+export { BaseSummarizeAdapter, type SummarizeAdapter, type SummarizeAdapterConfig, type AnySummarizeAdapter, } from './summarize/adapter.js';
+export { ChatStreamSummarizeAdapter, type ChatStreamCapable, type InferTextProviderOptions, } from './summarize/chat-stream-summarize.js';
+export { kind as imageKind, generateImage, type ImageActivityOptions, type ImageActivityResult, type ImageProviderOptionsForModel, type ImageSizeForModel, } from './generateImage/index.js';
+export { BaseImageAdapter, type ImageAdapter, type ImageAdapterConfig, type AnyImageAdapter, } from './generateImage/adapter.js';
+export { kind as audioKind, generateAudio, type AudioActivityOptions, type AudioActivityResult, type AudioProviderOptions, } from './generateAudio/index.js';
+export { BaseAudioAdapter, type AudioAdapter, type AudioAdapterConfig, type AnyAudioAdapter, } from './generateAudio/adapter.js';
+export { kind as videoKind, generateVideo, getVideoJobStatus, type VideoActivityOptions, type VideoActivityResult, type VideoProviderOptions, type VideoCreateOptions, type VideoStatusOptions, type VideoUrlOptions, type VideoDurationForAdapter, } from './generateVideo/index.js';
+export { BaseVideoAdapter, type VideoAdapter, type VideoAdapterConfig, type AnyVideoAdapter, type DurationOptions, } from './generateVideo/adapter.js';
+export { snapToDurationOption } from './generateVideo/snap.js';
+export { kind as ttsKind, generateSpeech, type TTSActivityOptions, type TTSActivityResult, type TTSProviderOptions, } from './generateSpeech/index.js';
+export { BaseTTSAdapter, type TTSAdapter, type TTSAdapterConfig, type AnyTTSAdapter, } from './generateSpeech/adapter.js';
+export { kind as transcriptionKind, generateTranscription, type TranscriptionActivityOptions, type TranscriptionActivityResult, type TranscriptionProviderOptions, } from './generateTranscription/index.js';
+export { BaseTranscriptionAdapter, type TranscriptionAdapter, type TranscriptionAdapterConfig, type AnyTranscriptionAdapter, } from './generateTranscription/adapter.js';
+/** Union of all adapter types that can be passed to chat() */
+export type AIAdapter = AnyTextAdapter | AnySummarizeAdapter | AnyImageAdapter | AnyAudioAdapter | AnyVideoAdapter | AnyTTSAdapter | AnyTranscriptionAdapter;
+/** Union type of all adapter kinds */
+export type AdapterKind = 'text' | 'summarize' | 'image' | 'audio' | 'video' | 'tts' | 'transcription';

package/dist/esm/activities/index.js

@@ -0,0 +1,43 @@
+import { chat, kind } from "./chat/index.js";
+import { BaseTextAdapter } from "./chat/adapter.js";
+import { summarize, kind as kind2 } from "./summarize/index.js";
+import { BaseSummarizeAdapter } from "./summarize/adapter.js";
+import { ChatStreamSummarizeAdapter } from "./summarize/chat-stream-summarize.js";
+import { generateImage, kind as kind3 } from "./generateImage/index.js";
+import { BaseImageAdapter } from "./generateImage/adapter.js";
+import { kind as kind4, generateAudio } from "./generateAudio/index.js";
+import { BaseAudioAdapter } from "./generateAudio/adapter.js";
+import { generateVideo, getVideoJobStatus, kind as kind5 } from "./generateVideo/index.js";
+import { BaseVideoAdapter } from "./generateVideo/adapter.js";
+import { snapToDurationOption } from "./generateVideo/snap.js";
+import { generateSpeech, kind as kind6 } from "./generateSpeech/index.js";
+import { BaseTTSAdapter } from "./generateSpeech/adapter.js";
+import { generateTranscription, kind as kind7 } from "./generateTranscription/index.js";
+import { BaseTranscriptionAdapter } from "./generateTranscription/adapter.js";
+export {
+  BaseAudioAdapter,
+  BaseImageAdapter,
+  BaseSummarizeAdapter,
+  BaseTTSAdapter,
+  BaseTextAdapter,
+  BaseTranscriptionAdapter,
+  BaseVideoAdapter,
+  ChatStreamSummarizeAdapter,
+  kind4 as audioKind,
+  chat,
+  generateAudio,
+  generateImage,
+  generateSpeech,
+  generateTranscription,
+  generateVideo,
+  getVideoJobStatus,
+  kind3 as imageKind,
+  snapToDurationOption,
+  summarize,
+  kind2 as summarizeKind,
+  kind as textKind,
+  kind7 as transcriptionKind,
+  kind6 as ttsKind,
+  kind5 as videoKind
+};
+//# sourceMappingURL=index.js.map

package/dist/esm/activities/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;"}

package/dist/esm/activities/middleware/index.d.ts

@@ -0,0 +1,2 @@
+export type { GenerationActivity, GenerationMiddleware, GenerationMiddlewareContext, GenerationUsageInfo, GenerationFinishInfo, GenerationAbortInfo, GenerationErrorInfo, AnyGenerationMiddleware, } from './types.js';
+export { createGenerationContext, runGenerationStart, runGenerationUsage, runGenerationFinish, runGenerationAbort, runGenerationError, } from './run.js';

package/dist/esm/activities/middleware/run.d.ts

@@ -0,0 +1,20 @@
+import { GenerationAbortInfo, GenerationErrorInfo, GenerationFinishInfo, GenerationMiddleware, GenerationMiddlewareContext, GenerationUsageInfo } from './types.js';
+/**
+ * Build the stable context for a single media-activity call.
+ *
+ * Media activities are always server-side and carry no user runtime context,
+ * so `source` is fixed to `'server'` and `context` to `undefined`.
+ */
+export declare function createGenerationContext(args: {
+    requestId: string;
+    activity: GenerationMiddlewareContext['activity'];
+    provider: string;
+    model: string;
+    modelOptions?: unknown;
+    createId: (prefix: string) => string;
+}): GenerationMiddlewareContext;
+export declare function runGenerationStart(middleware: ReadonlyArray<GenerationMiddleware> | undefined, ctx: GenerationMiddlewareContext): Promise<void>;
+export declare function runGenerationUsage(middleware: ReadonlyArray<GenerationMiddleware> | undefined, ctx: GenerationMiddlewareContext, usage: GenerationUsageInfo): Promise<void>;
+export declare function runGenerationFinish(middleware: ReadonlyArray<GenerationMiddleware> | undefined, ctx: GenerationMiddlewareContext, info: GenerationFinishInfo): Promise<void>;
+export declare function runGenerationAbort(middleware: ReadonlyArray<GenerationMiddleware> | undefined, ctx: GenerationMiddlewareContext, info: GenerationAbortInfo): Promise<void>;
+export declare function runGenerationError(middleware: ReadonlyArray<GenerationMiddleware> | undefined, ctx: GenerationMiddlewareContext, info: GenerationErrorInfo): Promise<void>;

package/dist/esm/activities/middleware/run.js

@@ -0,0 +1,42 @@
+function createGenerationContext(args) {
+  return {
+    requestId: args.requestId,
+    activity: args.activity,
+    provider: args.provider,
+    model: args.model,
+    modelOptions: args.modelOptions,
+    source: "server",
+    createId: args.createId,
+    context: void 0
+  };
+}
+async function run(middleware, invoke) {
+  if (!middleware || middleware.length === 0) return;
+  for (const mw of middleware) {
+    await invoke(mw);
+  }
+}
+function runGenerationStart(middleware, ctx) {
+  return run(middleware, (mw) => mw.onStart?.(ctx));
+}
+function runGenerationUsage(middleware, ctx, usage) {
+  return run(middleware, (mw) => mw.onUsage?.(ctx, usage));
+}
+function runGenerationFinish(middleware, ctx, info) {
+  return run(middleware, (mw) => mw.onFinish?.(ctx, info));
+}
+function runGenerationAbort(middleware, ctx, info) {
+  return run(middleware, (mw) => mw.onAbort?.(ctx, info));
+}
+function runGenerationError(middleware, ctx, info) {
+  return run(middleware, (mw) => mw.onError?.(ctx, info));
+}
+export {
+  createGenerationContext,
+  runGenerationAbort,
+  runGenerationError,
+  runGenerationFinish,
+  runGenerationStart,
+  runGenerationUsage
+};
+//# sourceMappingURL=run.js.map

package/dist/esm/activities/middleware/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sources":["../../../../src/activities/middleware/run.ts"],"sourcesContent":["import type {\n  GenerationAbortInfo,\n  GenerationErrorInfo,\n  GenerationFinishInfo,\n  GenerationMiddleware,\n  GenerationMiddlewareContext,\n  GenerationUsageInfo,\n} from './types'\n\n/**\n * Build the stable context for a single media-activity call.\n *\n * Media activities are always server-side and carry no user runtime context,\n * so `source` is fixed to `'server'` and `context` to `undefined`.\n */\nexport function createGenerationContext(args: {\n  requestId: string\n  activity: GenerationMiddlewareContext['activity']\n  provider: string\n  model: string\n  modelOptions?: unknown\n  createId: (prefix: string) => string\n}): GenerationMiddlewareContext {\n  return {\n    requestId: args.requestId,\n    activity: args.activity,\n    provider: args.provider,\n    model: args.model,\n    modelOptions: args.modelOptions,\n    source: 'server',\n    createId: args.createId,\n    context: undefined,\n  }\n}\n\n/**\n * Run a single lifecycle hook across each middleware in registration order,\n * awaiting each. Exceptions PROPAGATE (matching `chat()` middleware) — a\n * broken middleware fails the activity rather than being silently swallowed.\n */\nasync function run(\n  middleware: ReadonlyArray<GenerationMiddleware> | undefined,\n  invoke: (mw: GenerationMiddleware) => void | Promise<void>,\n): Promise<void> {\n  if (!middleware || middleware.length === 0) return\n  for (const mw of middleware) {\n    await invoke(mw)\n  }\n}\n\nexport function runGenerationStart(\n  middleware: ReadonlyArray<GenerationMiddleware> | undefined,\n  ctx: GenerationMiddlewareContext,\n): Promise<void> {\n  return run(middleware, (mw) => mw.onStart?.(ctx))\n}\n\nexport function runGenerationUsage(\n  middleware: ReadonlyArray<GenerationMiddleware> | undefined,\n  ctx: GenerationMiddlewareContext,\n  usage: GenerationUsageInfo,\n): Promise<void> {\n  return run(middleware, (mw) => mw.onUsage?.(ctx, usage))\n}\n\nexport function runGenerationFinish(\n  middleware: ReadonlyArray<GenerationMiddleware> | undefined,\n  ctx: GenerationMiddlewareContext,\n  info: GenerationFinishInfo,\n): Promise<void> {\n  return run(middleware, (mw) => mw.onFinish?.(ctx, info))\n}\n\nexport function runGenerationAbort(\n  middleware: ReadonlyArray<GenerationMiddleware> | undefined,\n  ctx: GenerationMiddlewareContext,\n  info: GenerationAbortInfo,\n): Promise<void> {\n  return run(middleware, (mw) => mw.onAbort?.(ctx, info))\n}\n\nexport function runGenerationError(\n  middleware: ReadonlyArray<GenerationMiddleware> | undefined,\n  ctx: GenerationMiddlewareContext,\n  info: GenerationErrorInfo,\n): Promise<void> {\n  return run(middleware, (mw) => mw.onError?.(ctx, info))\n}\n"],"names":[],"mappings":"AAeO,SAAS,wBAAwB,MAOR;AAC9B,SAAO;AAAA,IACL,WAAW,KAAK;AAAA,IAChB,UAAU,KAAK;AAAA,IACf,UAAU,KAAK;AAAA,IACf,OAAO,KAAK;AAAA,IACZ,cAAc,KAAK;AAAA,IACnB,QAAQ;AAAA,IACR,UAAU,KAAK;AAAA,IACf,SAAS;AAAA,EAAA;AAEb;AAOA,eAAe,IACb,YACA,QACe;AACf,MAAI,CAAC,cAAc,WAAW,WAAW,EAAG;AAC5C,aAAW,MAAM,YAAY;AAC3B,UAAM,OAAO,EAAE;AAAA,EACjB;AACF;AAEO,SAAS,mBACd,YACA,KACe;AACf,SAAO,IAAI,YAAY,CAAC,OAAO,GAAG,UAAU,GAAG,CAAC;AAClD;AAEO,SAAS,mBACd,YACA,KACA,OACe;AACf,SAAO,IAAI,YAAY,CAAC,OAAO,GAAG,UAAU,KAAK,KAAK,CAAC;AACzD;AAEO,SAAS,oBACd,YACA,KACA,MACe;AACf,SAAO,IAAI,YAAY,CAAC,OAAO,GAAG,WAAW,KAAK,IAAI,CAAC;AACzD;AAEO,SAAS,mBACd,YACA,KACA,MACe;AACf,SAAO,IAAI,YAAY,CAAC,OAAO,GAAG,UAAU,KAAK,IAAI,CAAC;AACxD;AAEO,SAAS,mBACd,YACA,KACA,MACe;AACf,SAAO,IAAI,YAAY,CAAC,OAAO,GAAG,UAAU,KAAK,IAAI,CAAC;AACxD;"}

package/dist/esm/activities/middleware/types.d.ts

@@ -0,0 +1,118 @@
+import { TokenUsage } from '../../types.js';
+/**
+ * The activity an observability event describes.
+ *
+ * Mirrors the public surface a caller reaches for: `'chat'` for `chat()`, and
+ * the media kinds for the `generate*` activities. `'tts'` matches the speech
+ * adapter's kind (the public discriminator avoids inventing a parallel
+ * `'speech'`/`'text'` vocabulary). `otelMiddleware` maps each to its
+ * `gen_ai.operation.name`.
+ */
+export type GenerationActivity = 'chat' | 'image' | 'video' | 'audio' | 'tts' | 'transcription';
+/**
+ * Stable context passed to every {@link GenerationMiddleware} hook. Created
+ * once per activity call and shared across the hooks of that call.
+ *
+ * Carries only fields every activity can honor. `ChatMiddlewareContext`
+ * structurally includes all of these plus chat-only state (messages,
+ * iteration, capabilities, …), which is why a chat middleware that reads those
+ * extra fields is not assignable to `GenerationMiddleware`.
+ */
+export interface GenerationMiddlewareContext<TContext = unknown> {
+    /**
+     * Stable id correlating the `onStart` / `onFinish` / `onError` / `onAbort`
+     * hooks of a single activity call.
+     */
+    requestId: string;
+    /** Which activity this call is. Discriminates media from chat. */
+    activity: GenerationActivity;
+    /** Provider/adapter name (e.g. `"openai"`). Emitted as `gen_ai.system`. */
+    provider: string;
+    /** Model id. Emitted as `gen_ai.request.model`. */
+    model: string;
+    /**
+     * Provider-specific options passed to the activity, if any. Typed `unknown`
+     * because each activity's options are strongly typed per model; a supertype
+     * of `ChatMiddlewareContext`'s `modelOptions`.
+     */
+    modelOptions?: unknown;
+    /** Where the call originates. Always `'server'` for media activities. */
+    source: 'client' | 'server';
+    /** Generate a unique id with the given prefix. */
+    createId: (prefix: string) => string;
+    /** Runtime context provided by the activity options, if any. */
+    context: TContext;
+}
+/**
+ * Token usage passed to {@link GenerationMiddleware.onUsage}. Kept as an
+ * interface extending `TokenUsage` to preserve declaration merging for this
+ * publicly exported type.
+ */
+export interface GenerationUsageInfo extends TokenUsage {
+}
+/** Information passed to {@link GenerationMiddleware.onFinish}. */
+export interface GenerationFinishInfo {
+    /** Wall-clock duration of the activity call, in milliseconds. */
+    duration: number;
+    /** Unified usage, when the provider reported it. */
+    usage?: TokenUsage | undefined;
+}
+/** Information passed to {@link GenerationMiddleware.onAbort}. */
+export interface GenerationAbortInfo {
+    /** The reason for the abort, if provided. */
+    reason?: string;
+    /** Wall-clock duration until the abort, in milliseconds. */
+    duration: number;
+}
+/** Information passed to {@link GenerationMiddleware.onError}. */
+export interface GenerationErrorInfo {
+    /** The thrown value (typically an `Error`). */
+    error: unknown;
+    /** Wall-clock duration until the failure, in milliseconds. */
+    duration: number;
+}
+/**
+ * Activity-agnostic, observe-only middleware.
+ *
+ * A thin lifecycle observer registerable on any activity via its `middleware`
+ * option. Unlike `ChatMiddleware` (which can also rewrite config, chunks, and
+ * tool calls), these hooks only observe — the right fit for the single
+ * request → response shape of media activities. Pass `otelMiddleware()` for
+ * OpenTelemetry, or implement the hooks directly for a custom backend.
+ *
+ * Hooks are awaited in registration order. A hook that throws PROPAGATES and
+ * fails the activity — matching `chat()` middleware semantics. Keep them cheap;
+ * they run inline with the request.
+ *
+ * Exactly one of `onFinish` / `onAbort` / `onError` fires per call.
+ *
+ * @example
+ * ```ts
+ * import { generateImage } from '@tanstack/ai'
+ * import { otelMiddleware } from '@tanstack/ai/middlewares/otel'
+ * import { openaiImage } from '@tanstack/ai-openai'
+ * import { trace } from '@opentelemetry/api'
+ *
+ * await generateImage({
+ *   adapter: openaiImage('gpt-image-1'),
+ *   prompt: 'A serene mountain landscape at sunset',
+ *   middleware: [otelMiddleware({ tracer: trace.getTracer('my-app') })],
+ * })
+ * ```
+ */
+export interface GenerationMiddleware<TContext = unknown> {
+    /** Optional name, surfaced in diagnostics. */
+    name?: string;
+    /** Called before the adapter request begins. */
+    onStart?: (ctx: GenerationMiddlewareContext<TContext>) => void | Promise<void>;
+    /** Called when the provider reports usage, before `onFinish`. */
+    onUsage?: (ctx: GenerationMiddlewareContext<TContext>, usage: GenerationUsageInfo) => void | Promise<void>;
+    /** Called after the activity completes successfully. */
+    onFinish?: (ctx: GenerationMiddlewareContext<TContext>, info: GenerationFinishInfo) => void | Promise<void>;
+    /** Called when the activity is aborted (e.g. an abandoned stream). */
+    onAbort?: (ctx: GenerationMiddlewareContext<TContext>, info: GenerationAbortInfo) => void | Promise<void>;
+    /** Called when the activity throws before completing. */
+    onError?: (ctx: GenerationMiddlewareContext<TContext>, info: GenerationErrorInfo) => void | Promise<void>;
+}
+/** A `GenerationMiddleware` with a permissive context — for use as a constraint. */
+export type AnyGenerationMiddleware = GenerationMiddleware<any>;

package/dist/esm/activities/stream-generation-result.d.ts

@@ -0,0 +1,15 @@
+import { StreamChunk } from '../types.js';
+/**
+ * Wrap a one-shot generation result as a StreamChunk async iterable.
+ *
+ * This allows non-streaming activities (image, speech, transcription, summarize)
+ * to be sent over the same streaming transport as chat.
+ *
+ * @param generator - An async function that performs the generation and returns the result
+ * @param options - Optional configuration (runId, threadId)
+ * @returns An AsyncIterable of StreamChunks with RUN_STARTED, CUSTOM(generation:result), and RUN_FINISHED events on success, or RUN_STARTED and RUN_ERROR on failure
+ */
+export declare function streamGenerationResult<TResult>(generator: () => Promise<TResult>, options?: {
+    runId?: string;
+    threadId?: string;
+}): AsyncIterable<StreamChunk>;

package/dist/esm/activities/stream-generation-result.js

@@ -0,0 +1,49 @@
+import { EventType } from "@ag-ui/core";
+import { toRunErrorPayload } from "./error-payload.js";
+function createId(prefix) {
+  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+}
+async function* streamGenerationResult(generator, options) {
+  const runId = createId("run");
+  const threadId = createId("thread");
+  yield {
+    type: EventType.RUN_STARTED,
+    runId,
+    threadId,
+    timestamp: Date.now()
+  };
+  try {
+    const result = await generator();
+    yield {
+      type: EventType.CUSTOM,
+      name: "generation:result",
+      value: result,
+      timestamp: Date.now()
+    };
+    yield {
+      type: EventType.RUN_FINISHED,
+      runId,
+      threadId,
+      finishReason: "stop",
+      timestamp: Date.now()
+    };
+  } catch (error) {
+    const payload = toRunErrorPayload(error, "Generation failed");
+    const codeFields = payload.code !== void 0 ? { code: payload.code } : void 0;
+    yield {
+      type: EventType.RUN_ERROR,
+      message: payload.message,
+      ...codeFields,
+      // Deprecated nested form for backward compatibility
+      error: {
+        message: payload.message,
+        ...codeFields
+      },
+      timestamp: Date.now()
+    };
+  }
+}
+export {
+  streamGenerationResult
+};
+//# sourceMappingURL=stream-generation-result.js.map

package/dist/esm/activities/stream-generation-result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-generation-result.js","sources":["../../../src/activities/stream-generation-result.ts"],"sourcesContent":["/**\n * Internal helper for wrapping one-shot generation results as StreamChunk\n * async iterables. NOT exported from the package — used only by activity\n * implementations to support `stream: true`.\n */\n\nimport { EventType } from '@ag-ui/core'\nimport { toRunErrorPayload } from './error-payload'\nimport type { StreamChunk } from '../types'\n\nfunction createId(prefix: string): string {\n  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`\n}\n\n/**\n * Wrap a one-shot generation result as a StreamChunk async iterable.\n *\n * This allows non-streaming activities (image, speech, transcription, summarize)\n * to be sent over the same streaming transport as chat.\n *\n * @param generator - An async function that performs the generation and returns the result\n * @param options - Optional configuration (runId, threadId)\n * @returns An AsyncIterable of StreamChunks with RUN_STARTED, CUSTOM(generation:result), and RUN_FINISHED events on success, or RUN_STARTED and RUN_ERROR on failure\n */\nexport async function* streamGenerationResult<TResult>(\n  generator: () => Promise<TResult>,\n  options?: { runId?: string; threadId?: string },\n): AsyncIterable<StreamChunk> {\n  const runId = options?.runId ?? createId('run')\n  const threadId = options?.threadId ?? createId('thread')\n\n  yield {\n    type: EventType.RUN_STARTED,\n    runId,\n    threadId,\n    timestamp: Date.now(),\n  }\n\n  try {\n    const result = await generator()\n\n    yield {\n      type: EventType.CUSTOM,\n      name: 'generation:result',\n      value: result as unknown,\n      timestamp: Date.now(),\n    }\n\n    yield {\n      type: EventType.RUN_FINISHED,\n      runId,\n      threadId,\n      finishReason: 'stop',\n      timestamp: Date.now(),\n    }\n  } catch (error: unknown) {\n    const payload = toRunErrorPayload(error, 'Generation failed')\n    // `code` is omitted entirely when undefined so the event matches the\n    // AG-UI `code?: string` shape under `exactOptionalPropertyTypes`. The\n    // deprecated nested `error` form preserves the same conditional\n    // structure for backward compatibility.\n    const codeFields =\n      payload.code !== undefined ? { code: payload.code } : undefined\n    yield {\n      type: EventType.RUN_ERROR,\n      message: payload.message,\n      ...codeFields,\n      // Deprecated nested form for backward compatibility\n      error: {\n        message: payload.message,\n        ...codeFields,\n      },\n      timestamp: Date.now(),\n    }\n  }\n}\n"],"names":[],"mappings":";;AAUA,SAAS,SAAS,QAAwB;AACxC,SAAO,GAAG,MAAM,IAAI,KAAK,IAAA,CAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,MAAM,GAAG,CAAC,CAAC;AAC1E;AAYA,gBAAuB,uBACrB,WACA,SAC4B;AAC5B,QAAM,QAA0B,SAAS,KAAK;AAC9C,QAAM,WAAgC,SAAS,QAAQ;AAEvD,QAAM;AAAA,IACJ,MAAM,UAAU;AAAA,IAChB;AAAA,IACA;AAAA,IACA,WAAW,KAAK,IAAA;AAAA,EAAI;AAGtB,MAAI;AACF,UAAM,SAAS,MAAM,UAAA;AAErB,UAAM;AAAA,MACJ,MAAM,UAAU;AAAA,MAChB,MAAM;AAAA,MACN,OAAO;AAAA,MACP,WAAW,KAAK,IAAA;AAAA,IAAI;AAGtB,UAAM;AAAA,MACJ,MAAM,UAAU;AAAA,MAChB;AAAA,MACA;AAAA,MACA,cAAc;AAAA,MACd,WAAW,KAAK,IAAA;AAAA,IAAI;AAAA,EAExB,SAAS,OAAgB;AACvB,UAAM,UAAU,kBAAkB,OAAO,mBAAmB;AAK5D,UAAM,aACJ,QAAQ,SAAS,SAAY,EAAE,MAAM,QAAQ,SAAS;AACxD,UAAM;AAAA,MACJ,MAAM,UAAU;AAAA,MAChB,SAAS,QAAQ;AAAA,MACjB,GAAG;AAAA;AAAA,MAEH,OAAO;AAAA,QACL,SAAS,QAAQ;AAAA,QACjB,GAAG;AAAA,MAAA;AAAA,MAEL,WAAW,KAAK,IAAA;AAAA,IAAI;AAAA,EAExB;AACF;"}

package/dist/esm/activities/summarize/adapter.d.ts

@@ -0,0 +1,74 @@
+import { StreamChunk, SummarizationOptions, SummarizationResult } from '../../types.js';
+/**
+ * Configuration for summarize adapter instances
+ */
+export interface SummarizeAdapterConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+    maxRetries?: number;
+    headers?: Record<string, string>;
+}
+/**
+ * Summarize 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., 'gpt-4o')
+ * - TProviderOptions: Provider-specific options (already resolved)
+ */
+export interface SummarizeAdapter<TModel extends string = string, TProviderOptions extends object = Record<string, unknown>> {
+    /** Discriminator for adapter kind - used by generate() to determine API shape */
+    readonly kind: 'summarize';
+    /** 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;
+    };
+    /**
+     * Summarize the given text
+     */
+    summarize: (options: SummarizationOptions<TProviderOptions>) => Promise<SummarizationResult>;
+    /**
+     * Stream summarization of the given text.
+     * Optional - if not implemented, the activity layer will fall back to
+     * non-streaming summarize and yield the result as a single chunk.
+     */
+    summarizeStream?: (options: SummarizationOptions<TProviderOptions>) => AsyncIterable<StreamChunk>;
+}
+/**
+ * A SummarizeAdapter with any/unknown type parameters.
+ * Useful as a constraint in generic functions and interfaces.
+ */
+export type AnySummarizeAdapter = SummarizeAdapter<any, any>;
+/**
+ * Abstract base class for summarize adapters.
+ * Extend this class to implement a summarize adapter for a specific provider.
+ *
+ * Generic parameters match SummarizeAdapter - all pre-resolved by the provider function.
+ */
+export declare abstract class BaseSummarizeAdapter<TModel extends string = string, TProviderOptions extends object = Record<string, unknown>> implements SummarizeAdapter<TModel, TProviderOptions> {
+    readonly kind: "summarize";
+    abstract readonly name: string;
+    readonly model: TModel;
+    '~types': {
+        providerOptions: TProviderOptions;
+    };
+    protected config: SummarizeAdapterConfig;
+    constructor(config: SummarizeAdapterConfig | undefined, model: TModel);
+    abstract summarize(options: SummarizationOptions<TProviderOptions>): Promise<SummarizationResult>;
+    /**
+     * Stream summarization of the given text.
+     * Override this method in concrete implementations to enable streaming.
+     * If not overridden, the activity layer will fall back to non-streaming.
+     */
+    summarizeStream?(options: SummarizationOptions<TProviderOptions>): AsyncIterable<StreamChunk>;
+    protected generateId(): string;
+}

package/dist/esm/activities/summarize/adapter.js

@@ -0,0 +1,16 @@
+class BaseSummarizeAdapter {
+  kind = "summarize";
+  model;
+  config;
+  constructor(config = {}, model) {
+    this.config = config;
+    this.model = model;
+  }
+  generateId() {
+    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+  }
+}
+export {
+  BaseSummarizeAdapter
+};
+//# sourceMappingURL=adapter.js.map

package/dist/esm/activities/summarize/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sources":["../../../../src/activities/summarize/adapter.ts"],"sourcesContent":["import type {\n  StreamChunk,\n  SummarizationOptions,\n  SummarizationResult,\n} from '../../types'\n\n/**\n * Configuration for summarize adapter instances\n */\nexport interface SummarizeAdapterConfig {\n  apiKey?: string\n  baseUrl?: string\n  timeout?: number\n  maxRetries?: number\n  headers?: Record<string, string>\n}\n\n/**\n * Summarize adapter interface with pre-resolved generics.\n *\n * An adapter is created by a provider function: `provider('model')` → `adapter`\n * All type resolution happens at the provider call site, not in this interface.\n *\n * Generic parameters:\n * - TModel: The specific model name (e.g., 'gpt-4o')\n * - TProviderOptions: Provider-specific options (already resolved)\n */\nexport interface SummarizeAdapter<\n  TModel extends string = string,\n  TProviderOptions extends object = Record<string, unknown>,\n> {\n  /** Discriminator for adapter kind - used by generate() to determine API shape */\n  readonly kind: 'summarize'\n  /** Adapter name identifier */\n  readonly name: string\n  /** The model this adapter is configured for */\n  readonly model: TModel\n\n  /**\n   * @internal Type-only properties for inference. Not assigned at runtime.\n   */\n  '~types': {\n    providerOptions: TProviderOptions\n  }\n\n  /**\n   * Summarize the given text\n   */\n  summarize: (\n    options: SummarizationOptions<TProviderOptions>,\n  ) => Promise<SummarizationResult>\n\n  /**\n   * Stream summarization of the given text.\n   * Optional - if not implemented, the activity layer will fall back to\n   * non-streaming summarize and yield the result as a single chunk.\n   */\n  summarizeStream?: (\n    options: SummarizationOptions<TProviderOptions>,\n  ) => AsyncIterable<StreamChunk>\n}\n\n/**\n * A SummarizeAdapter with any/unknown type parameters.\n * Useful as a constraint in generic functions and interfaces.\n */\nexport type AnySummarizeAdapter = SummarizeAdapter<any, any>\n\n/**\n * Abstract base class for summarize adapters.\n * Extend this class to implement a summarize adapter for a specific provider.\n *\n * Generic parameters match SummarizeAdapter - all pre-resolved by the provider function.\n */\nexport abstract class BaseSummarizeAdapter<\n  TModel extends string = string,\n  TProviderOptions extends object = Record<string, unknown>,\n> implements SummarizeAdapter<TModel, TProviderOptions> {\n  readonly kind = 'summarize' as const\n  abstract readonly name: string\n  readonly model: TModel\n\n  // Type-only property - never assigned at runtime\n  declare '~types': {\n    providerOptions: TProviderOptions\n  }\n\n  protected config: SummarizeAdapterConfig\n\n  constructor(config: SummarizeAdapterConfig = {}, model: TModel) {\n    this.config = config\n    this.model = model\n  }\n\n  abstract summarize(\n    options: SummarizationOptions<TProviderOptions>,\n  ): Promise<SummarizationResult>\n\n  /**\n   * Stream summarization of the given text.\n   * Override this method in concrete implementations to enable streaming.\n   * If not overridden, the activity layer will fall back to non-streaming.\n   */\n  summarizeStream?(\n    options: SummarizationOptions<TProviderOptions>,\n  ): AsyncIterable<StreamChunk>\n\n  protected generateId(): string {\n    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`\n  }\n}\n"],"names":[],"mappings":"AA0EO,MAAe,qBAGkC;AAAA,EAC7C,OAAO;AAAA,EAEP;AAAA,EAOC;AAAA,EAEV,YAAY,SAAiC,CAAA,GAAI,OAAe;AAC9D,SAAK,SAAS;AACd,SAAK,QAAQ;AAAA,EACf;AAAA,EAeU,aAAqB;AAC7B,WAAO,GAAG,KAAK,IAAI,IAAI,KAAK,KAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,UAAU,CAAC,CAAC;AAAA,EAC9E;AACF;"}

package/dist/esm/activities/summarize/chat-stream-summarize.d.ts

@@ -0,0 +1,45 @@
+import { BaseSummarizeAdapter } from './adapter.js';
+import { StreamChunk, SummarizationOptions, SummarizationResult, TextOptions } from '../../types.js';
+/**
+ * Minimal contract for a text adapter that supports `chatStream`. Lets
+ * `ChatStreamSummarizeAdapter` work with any text adapter without coupling
+ * to a specific implementation.
+ *
+ * The provider-options shape is intentionally `any` here — the wrapper only
+ * forwards `modelOptions` straight through, so a text adapter with a richer
+ * per-model options type (e.g. `ResolveProviderOptions<TModel>`) is still
+ * acceptable. Summarize-level type safety is enforced via
+ * `SummarizationOptions<TProviderOptions>` on the wrapper itself.
+ */
+export interface ChatStreamCapable {
+    chatStream: (options: TextOptions<any>) => AsyncIterable<StreamChunk>;
+}
+/**
+ * Extract the per-model `modelOptions` type a text adapter accepts. Used by
+ * provider summarize factories so their `modelOptions` IntelliSense matches
+ * what the underlying text adapter actually understands.
+ */
+export type InferTextProviderOptions<TAdapter> = TAdapter extends {
+    '~types': {
+        providerOptions: infer P;
+    };
+} ? P extends object ? P : object : object;
+/**
+ * Summarize adapter that wraps any `ChatStreamCapable` text adapter and
+ * prompts it for summarization. Not tied to any wire format.
+ */
+export declare class ChatStreamSummarizeAdapter<TModel extends string, TProviderOptions extends object = Record<string, unknown>> extends BaseSummarizeAdapter<TModel, TProviderOptions> {
+    readonly name: string;
+    private readonly textAdapter;
+    constructor(textAdapter: ChatStreamCapable, model: TModel, name?: string);
+    summarize(options: SummarizationOptions<TProviderOptions>): Promise<SummarizationResult>;
+    summarizeStream(options: SummarizationOptions<TProviderOptions>): AsyncIterable<StreamChunk>;
+    /**
+     * Build the TextOptions passed to the underlying chatStream. Provider
+     * `modelOptions` from the summarize call are forwarded as-is so knobs like
+     * Anthropic cache headers, Gemini safety settings, or Ollama tuning params
+     * still reach the wire layer.
+     */
+    protected buildTextOptions(options: SummarizationOptions<TProviderOptions>, systemPrompt: string): TextOptions<TProviderOptions>;
+    protected buildSummarizationPrompt(options: SummarizationOptions<TProviderOptions>): string;
+}