@tanstack/ai 0.31.0 → 0.33.0

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

@@ -54,6 +54,13 @@ export interface ChatMiddlewareContext<TContext = unknown> {
      * after the terminal hook (onFinish/onAbort/onError).
      */
     defer: (promise: Promise<unknown>) => void;
+    /**
+     * Which activity this context describes — always `'chat'`. Present so the
+     * chat context structurally satisfies the base `GenerationMiddlewareContext`,
+     * letting an observe-only middleware authored against the base (e.g.
+     * `otelMiddleware`) run on both chat and media activities.
+     */
+    activity: 'chat';
     /** Provider name (e.g., 'openai', 'anthropic') */
     provider: string;
     /** Model identifier (e.g., 'gpt-4o') */

package/dist/esm/activities/chat/tools/lazy-tool-manager.d.ts

@@ -1,4 +1,12 @@
-import { Tool } from '../../../types.js';
+import { AnyTool, Tool } from '../../../types.js';
+/**
+ * Name of the synthetic tool the LLM calls to discover lazy tools.
+ *
+ * Exported so callers building custom message-compaction / history-trimming
+ * logic can reference the discovery tool by constant instead of hard-coding
+ * the string (which is an internal contract that could change).
+ */
+export declare const DISCOVERY_TOOL_NAME = "__lazy__tool__discovery__";
 /**
  * Manages lazy tool discovery for the chat agent loop.
  *
@@ -31,6 +39,22 @@ export declare class LazyToolManager {
      * Resets the hasNewDiscoveries flag.
      */
     getActiveTools(): Array<Tool>;
+    /**
+     * Returns the tools that should be available for *execution* this turn.
+     *
+     * This is the advertised set (`getActiveTools()`, passed in as `activeTools`)
+     * plus the discovery tool when a pending call references it but it is no
+     * longer advertised. Once every lazy tool has been discovered the discovery
+     * tool is dropped from the advertised set, but a model may still re-request
+     * discovery (long context / hallucination); keeping it executable lets that
+     * call return the schemas again instead of failing with "Unknown tool".
+     *
+     * The advertised set is intentionally left unchanged — only execution lookup
+     * is widened. Operates on the already-built `activeTools`: it must NOT call
+     * `getActiveTools()`, which would reset `hasNewDiscoveries` before the
+     * post-execution refresh check in the agent loop.
+     */
+    getExecutableTools(activeTools: ReadonlyArray<AnyTool>, pendingToolCallNames: ReadonlyArray<string>): ReadonlyArray<AnyTool>;
     /**
      * Returns whether new tools have been discovered since the last getActiveTools() call.
      */

package/dist/esm/activities/chat/tools/lazy-tool-manager.js

@@ -45,6 +45,27 @@ class LazyToolManager {
     }
     return active;
   }
+  /**
+   * Returns the tools that should be available for *execution* this turn.
+   *
+   * This is the advertised set (`getActiveTools()`, passed in as `activeTools`)
+   * plus the discovery tool when a pending call references it but it is no
+   * longer advertised. Once every lazy tool has been discovered the discovery
+   * tool is dropped from the advertised set, but a model may still re-request
+   * discovery (long context / hallucination); keeping it executable lets that
+   * call return the schemas again instead of failing with "Unknown tool".
+   *
+   * The advertised set is intentionally left unchanged — only execution lookup
+   * is widened. Operates on the already-built `activeTools`: it must NOT call
+   * `getActiveTools()`, which would reset `hasNewDiscoveries` before the
+   * post-execution refresh check in the agent loop.
+   */
+  getExecutableTools(activeTools, pendingToolCallNames) {
+    if (this.discoveryTool && pendingToolCallNames.includes(DISCOVERY_TOOL_NAME) && !activeTools.some((t) => t.name === DISCOVERY_TOOL_NAME)) {
+      return [...activeTools, this.discoveryTool];
+    }
+    return activeTools;
+  }
   /**
    * Returns whether new tools have been discovered since the last getActiveTools() call.
    */
@@ -135,8 +156,10 @@ class LazyToolManager {
         for (const name of args.toolNames) {
           const tool = lazyToolMap.get(name);
           if (tool) {
-            manager.discoveredTools.add(name);
-            manager.hasNewDiscoveries = true;
+            if (!manager.discoveredTools.has(name)) {
+              manager.discoveredTools.add(name);
+              manager.hasNewDiscoveries = true;
+            }
             const jsonSchema = tool.inputSchema ? convertSchemaToJsonSchema(tool.inputSchema) : void 0;
             tools.push({
               name: tool.name,
@@ -159,6 +182,7 @@ class LazyToolManager {
   }
 }
 export {
+  DISCOVERY_TOOL_NAME,
   LazyToolManager
 };
 //# sourceMappingURL=lazy-tool-manager.js.map

package/dist/esm/activities/chat/tools/lazy-tool-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"lazy-tool-manager.js","sources":["../../../../../src/activities/chat/tools/lazy-tool-manager.ts"],"sourcesContent":["import { convertSchemaToJsonSchema } from './schema-converter'\nimport type { Tool } from '../../../types'\n\nconst DISCOVERY_TOOL_NAME = '__lazy__tool__discovery__'\n\n/**\n * Manages lazy tool discovery for the chat agent loop.\n *\n * Lazy tools are not sent to the LLM initially. Instead, a synthetic\n * \"discovery tool\" is provided that lets the LLM discover lazy tools\n * by name, receiving their full descriptions and schemas on demand.\n */\nexport class LazyToolManager {\n  private readonly eagerTools: ReadonlyArray<Tool>\n  private readonly lazyToolMap: Map<string, Tool>\n  private readonly discoveredTools: Set<string>\n  private hasNewDiscoveries: boolean\n  private readonly discoveryTool: Tool | null\n\n  constructor(\n    tools: ReadonlyArray<Tool>,\n    messages: ReadonlyArray<{\n      role: string\n      content?: any\n      toolCalls?: Array<{\n        id: string\n        type: string\n        function: { name: string; arguments: string }\n      }>\n      toolCallId?: string\n    }>,\n  ) {\n    const eager: Array<Tool> = []\n    this.lazyToolMap = new Map()\n    this.discoveredTools = new Set()\n    this.hasNewDiscoveries = false\n\n    // Separate tools into eager and lazy\n    for (const tool of tools) {\n      if (tool.lazy) {\n        this.lazyToolMap.set(tool.name, tool)\n      } else {\n        eager.push(tool)\n      }\n    }\n    this.eagerTools = eager\n\n    // If no lazy tools, no discovery tool needed\n    if (this.lazyToolMap.size === 0) {\n      this.discoveryTool = null\n      return\n    }\n\n    // Scan message history to pre-populate discoveredTools\n    this.scanMessageHistory(messages)\n\n    // Create the synthetic discovery tool\n    this.discoveryTool = this.createDiscoveryTool()\n  }\n\n  /**\n   * Returns the set of tools that should be sent to the LLM:\n   * eager tools + discovered lazy tools + discovery tool (if undiscovered tools remain).\n   * Resets the hasNewDiscoveries flag.\n   */\n  getActiveTools(): Array<Tool> {\n    this.hasNewDiscoveries = false\n\n    const active: Array<Tool> = [...this.eagerTools]\n\n    // Add discovered lazy tools\n    for (const name of this.discoveredTools) {\n      const tool = this.lazyToolMap.get(name)\n      if (tool) {\n        active.push(tool)\n      }\n    }\n\n    // Add discovery tool if there are still undiscovered lazy tools\n    if (\n      this.discoveryTool &&\n      this.discoveredTools.size < this.lazyToolMap.size\n    ) {\n      active.push(this.discoveryTool)\n    }\n\n    return active\n  }\n\n  /**\n   * Returns whether new tools have been discovered since the last getActiveTools() call.\n   */\n  hasNewlyDiscoveredTools(): boolean {\n    return this.hasNewDiscoveries\n  }\n\n  /**\n   * Returns true if the given name is a lazy tool that has not yet been discovered.\n   */\n  isUndiscoveredLazyTool(name: string): boolean {\n    return this.lazyToolMap.has(name) && !this.discoveredTools.has(name)\n  }\n\n  /**\n   * Returns a helpful error message for when an undiscovered lazy tool is called.\n   */\n  getUndiscoveredToolError(name: string): string {\n    return `Error: Tool '${name}' must be discovered first. Call ${DISCOVERY_TOOL_NAME} with toolNames: ['${name}'] to discover it.`\n  }\n\n  /**\n   * Scans message history to find previously discovered lazy tools.\n   * Looks for assistant messages with discovery tool calls and their\n   * corresponding tool result messages.\n   */\n  private scanMessageHistory(\n    messages: ReadonlyArray<{\n      role: string\n      content?: any\n      toolCalls?: Array<{\n        id: string\n        type: string\n        function: { name: string; arguments: string }\n      }>\n      toolCallId?: string\n    }>,\n  ): void {\n    // Collect tool call IDs for discovery tool invocations\n    const discoveryCallIds = new Set<string>()\n\n    for (const msg of messages) {\n      if (msg.role === 'assistant' && msg.toolCalls) {\n        for (const tc of msg.toolCalls) {\n          if (tc.function.name === DISCOVERY_TOOL_NAME) {\n            discoveryCallIds.add(tc.id)\n          }\n        }\n      }\n    }\n\n    if (discoveryCallIds.size === 0) return\n\n    // Find corresponding tool result messages\n    for (const msg of messages) {\n      if (\n        msg.role === 'tool' &&\n        msg.toolCallId &&\n        discoveryCallIds.has(msg.toolCallId)\n      ) {\n        try {\n          const content =\n            typeof msg.content === 'string'\n              ? msg.content\n              : JSON.stringify(msg.content)\n          const parsed = JSON.parse(content)\n          if (parsed && Array.isArray(parsed.tools)) {\n            for (const tool of parsed.tools) {\n              if (\n                tool &&\n                typeof tool.name === 'string' &&\n                this.lazyToolMap.has(tool.name)\n              ) {\n                this.discoveredTools.add(tool.name)\n              }\n            }\n          }\n        } catch {\n          // Malformed JSON — skip gracefully\n        }\n      }\n    }\n  }\n\n  /**\n   * Creates the synthetic discovery tool that the LLM can call\n   * to discover lazy tools' descriptions and schemas.\n   */\n  private createDiscoveryTool(): Tool {\n    const undiscoveredNames = (): Array<string> => {\n      const names: Array<string> = []\n      for (const [name] of this.lazyToolMap) {\n        if (!this.discoveredTools.has(name)) {\n          names.push(name)\n        }\n      }\n      return names\n    }\n\n    const lazyToolMap = this.lazyToolMap\n\n    // Build the static description with all lazy tool names\n    const allLazyNames = Array.from(this.lazyToolMap.keys())\n    const description = `You have access to additional tools that can be discovered. Available tools: [${allLazyNames.join(', ')}]. Call this tool with a list of tool names to discover their full descriptions and argument schemas before using them.`\n\n    // Use the arrow function to capture `this` context\n    const manager = this\n\n    return {\n      name: DISCOVERY_TOOL_NAME,\n      description,\n      inputSchema: {\n        type: 'object',\n        properties: {\n          toolNames: {\n            type: 'array',\n            items: { type: 'string' },\n            description:\n              'List of tool names to discover. Each name must match one of the available tools.',\n          },\n        },\n        required: ['toolNames'],\n      },\n      execute: (args: { toolNames: Array<string> }) => {\n        const tools: Array<{\n          name: string\n          description: string\n          inputSchema?: any\n        }> = []\n        const errors: Array<string> = []\n\n        for (const name of args.toolNames) {\n          const tool = lazyToolMap.get(name)\n          if (tool) {\n            manager.discoveredTools.add(name)\n            manager.hasNewDiscoveries = true\n            const jsonSchema = tool.inputSchema\n              ? convertSchemaToJsonSchema(tool.inputSchema)\n              : undefined\n            tools.push({\n              name: tool.name,\n              description: tool.description,\n              ...(jsonSchema ? { inputSchema: jsonSchema } : {}),\n            })\n          } else {\n            errors.push(\n              `Unknown tool: '${name}'. Available tools: [${undiscoveredNames().join(', ')}]`,\n            )\n          }\n        }\n\n        const result: {\n          tools: typeof tools\n          errors?: Array<string>\n        } = { tools }\n\n        if (errors.length > 0) {\n          result.errors = errors\n        }\n\n        return result\n      },\n    }\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"lazy-tool-manager.js","sources":["../../../../../src/activities/chat/tools/lazy-tool-manager.ts"],"sourcesContent":["import { convertSchemaToJsonSchema } from './schema-converter'\nimport type { AnyTool, Tool } from '../../../types'\n\n/**\n * Name of the synthetic tool the LLM calls to discover lazy tools.\n *\n * Exported so callers building custom message-compaction / history-trimming\n * logic can reference the discovery tool by constant instead of hard-coding\n * the string (which is an internal contract that could change).\n */\nexport const DISCOVERY_TOOL_NAME = '__lazy__tool__discovery__'\n\n/**\n * Manages lazy tool discovery for the chat agent loop.\n *\n * Lazy tools are not sent to the LLM initially. Instead, a synthetic\n * \"discovery tool\" is provided that lets the LLM discover lazy tools\n * by name, receiving their full descriptions and schemas on demand.\n */\nexport class LazyToolManager {\n  private readonly eagerTools: ReadonlyArray<Tool>\n  private readonly lazyToolMap: Map<string, Tool>\n  private readonly discoveredTools: Set<string>\n  private hasNewDiscoveries: boolean\n  private readonly discoveryTool: Tool | null\n\n  constructor(\n    tools: ReadonlyArray<Tool>,\n    messages: ReadonlyArray<{\n      role: string\n      content?: any\n      toolCalls?: Array<{\n        id: string\n        type: string\n        function: { name: string; arguments: string }\n      }>\n      toolCallId?: string\n    }>,\n  ) {\n    const eager: Array<Tool> = []\n    this.lazyToolMap = new Map()\n    this.discoveredTools = new Set()\n    this.hasNewDiscoveries = false\n\n    // Separate tools into eager and lazy\n    for (const tool of tools) {\n      if (tool.lazy) {\n        this.lazyToolMap.set(tool.name, tool)\n      } else {\n        eager.push(tool)\n      }\n    }\n    this.eagerTools = eager\n\n    // If no lazy tools, no discovery tool needed\n    if (this.lazyToolMap.size === 0) {\n      this.discoveryTool = null\n      return\n    }\n\n    // Scan message history to pre-populate discoveredTools\n    this.scanMessageHistory(messages)\n\n    // Create the synthetic discovery tool\n    this.discoveryTool = this.createDiscoveryTool()\n  }\n\n  /**\n   * Returns the set of tools that should be sent to the LLM:\n   * eager tools + discovered lazy tools + discovery tool (if undiscovered tools remain).\n   * Resets the hasNewDiscoveries flag.\n   */\n  getActiveTools(): Array<Tool> {\n    this.hasNewDiscoveries = false\n\n    const active: Array<Tool> = [...this.eagerTools]\n\n    // Add discovered lazy tools\n    for (const name of this.discoveredTools) {\n      const tool = this.lazyToolMap.get(name)\n      if (tool) {\n        active.push(tool)\n      }\n    }\n\n    // Add discovery tool if there are still undiscovered lazy tools\n    if (\n      this.discoveryTool &&\n      this.discoveredTools.size < this.lazyToolMap.size\n    ) {\n      active.push(this.discoveryTool)\n    }\n\n    return active\n  }\n\n  /**\n   * Returns the tools that should be available for *execution* this turn.\n   *\n   * This is the advertised set (`getActiveTools()`, passed in as `activeTools`)\n   * plus the discovery tool when a pending call references it but it is no\n   * longer advertised. Once every lazy tool has been discovered the discovery\n   * tool is dropped from the advertised set, but a model may still re-request\n   * discovery (long context / hallucination); keeping it executable lets that\n   * call return the schemas again instead of failing with \"Unknown tool\".\n   *\n   * The advertised set is intentionally left unchanged — only execution lookup\n   * is widened. Operates on the already-built `activeTools`: it must NOT call\n   * `getActiveTools()`, which would reset `hasNewDiscoveries` before the\n   * post-execution refresh check in the agent loop.\n   */\n  getExecutableTools(\n    activeTools: ReadonlyArray<AnyTool>,\n    pendingToolCallNames: ReadonlyArray<string>,\n  ): ReadonlyArray<AnyTool> {\n    if (\n      this.discoveryTool &&\n      pendingToolCallNames.includes(DISCOVERY_TOOL_NAME) &&\n      !activeTools.some((t) => t.name === DISCOVERY_TOOL_NAME)\n    ) {\n      return [...activeTools, this.discoveryTool]\n    }\n    return activeTools\n  }\n\n  /**\n   * Returns whether new tools have been discovered since the last getActiveTools() call.\n   */\n  hasNewlyDiscoveredTools(): boolean {\n    return this.hasNewDiscoveries\n  }\n\n  /**\n   * Returns true if the given name is a lazy tool that has not yet been discovered.\n   */\n  isUndiscoveredLazyTool(name: string): boolean {\n    return this.lazyToolMap.has(name) && !this.discoveredTools.has(name)\n  }\n\n  /**\n   * Returns a helpful error message for when an undiscovered lazy tool is called.\n   */\n  getUndiscoveredToolError(name: string): string {\n    return `Error: Tool '${name}' must be discovered first. Call ${DISCOVERY_TOOL_NAME} with toolNames: ['${name}'] to discover it.`\n  }\n\n  /**\n   * Scans message history to find previously discovered lazy tools.\n   * Looks for assistant messages with discovery tool calls and their\n   * corresponding tool result messages.\n   */\n  private scanMessageHistory(\n    messages: ReadonlyArray<{\n      role: string\n      content?: any\n      toolCalls?: Array<{\n        id: string\n        type: string\n        function: { name: string; arguments: string }\n      }>\n      toolCallId?: string\n    }>,\n  ): void {\n    // Collect tool call IDs for discovery tool invocations\n    const discoveryCallIds = new Set<string>()\n\n    for (const msg of messages) {\n      if (msg.role === 'assistant' && msg.toolCalls) {\n        for (const tc of msg.toolCalls) {\n          if (tc.function.name === DISCOVERY_TOOL_NAME) {\n            discoveryCallIds.add(tc.id)\n          }\n        }\n      }\n    }\n\n    if (discoveryCallIds.size === 0) return\n\n    // Find corresponding tool result messages\n    for (const msg of messages) {\n      if (\n        msg.role === 'tool' &&\n        msg.toolCallId &&\n        discoveryCallIds.has(msg.toolCallId)\n      ) {\n        try {\n          const content =\n            typeof msg.content === 'string'\n              ? msg.content\n              : JSON.stringify(msg.content)\n          const parsed = JSON.parse(content)\n          if (parsed && Array.isArray(parsed.tools)) {\n            for (const tool of parsed.tools) {\n              if (\n                tool &&\n                typeof tool.name === 'string' &&\n                this.lazyToolMap.has(tool.name)\n              ) {\n                this.discoveredTools.add(tool.name)\n              }\n            }\n          }\n        } catch {\n          // Malformed JSON — skip gracefully\n        }\n      }\n    }\n  }\n\n  /**\n   * Creates the synthetic discovery tool that the LLM can call\n   * to discover lazy tools' descriptions and schemas.\n   */\n  private createDiscoveryTool(): Tool {\n    const undiscoveredNames = (): Array<string> => {\n      const names: Array<string> = []\n      for (const [name] of this.lazyToolMap) {\n        if (!this.discoveredTools.has(name)) {\n          names.push(name)\n        }\n      }\n      return names\n    }\n\n    const lazyToolMap = this.lazyToolMap\n\n    // Build the static description with all lazy tool names\n    const allLazyNames = Array.from(this.lazyToolMap.keys())\n    const description = `You have access to additional tools that can be discovered. Available tools: [${allLazyNames.join(', ')}]. Call this tool with a list of tool names to discover their full descriptions and argument schemas before using them.`\n\n    // Use the arrow function to capture `this` context\n    const manager = this\n\n    return {\n      name: DISCOVERY_TOOL_NAME,\n      description,\n      inputSchema: {\n        type: 'object',\n        properties: {\n          toolNames: {\n            type: 'array',\n            items: { type: 'string' },\n            description:\n              'List of tool names to discover. Each name must match one of the available tools.',\n          },\n        },\n        required: ['toolNames'],\n      },\n      execute: (args: { toolNames: Array<string> }) => {\n        const tools: Array<{\n          name: string\n          description: string\n          inputSchema?: any\n        }> = []\n        const errors: Array<string> = []\n\n        for (const name of args.toolNames) {\n          const tool = lazyToolMap.get(name)\n          if (tool) {\n            // Only flag a refresh for genuinely new discoveries. Re-requesting\n            // an already-discovered tool still returns its schema below (the\n            // model asked for it), but must not trigger a redundant tool-list\n            // refresh + continue in the agent loop.\n            if (!manager.discoveredTools.has(name)) {\n              manager.discoveredTools.add(name)\n              manager.hasNewDiscoveries = true\n            }\n            const jsonSchema = tool.inputSchema\n              ? convertSchemaToJsonSchema(tool.inputSchema)\n              : undefined\n            tools.push({\n              name: tool.name,\n              description: tool.description,\n              ...(jsonSchema ? { inputSchema: jsonSchema } : {}),\n            })\n          } else {\n            errors.push(\n              `Unknown tool: '${name}'. Available tools: [${undiscoveredNames().join(', ')}]`,\n            )\n          }\n        }\n\n        const result: {\n          tools: typeof tools\n          errors?: Array<string>\n        } = { tools }\n\n        if (errors.length > 0) {\n          result.errors = errors\n        }\n\n        return result\n      },\n    }\n  }\n}\n"],"names":[],"mappings":"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"}

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

@@ -1,4 +1,5 @@
 import { DebugOption } from '../../logger/types.js';
+import { GenerationMiddleware } from '../middleware.js';
 import { AudioAdapter } from './adapter.js';
 import { AudioGenerationResult, StreamChunk } from '../../types.js';
 /** The adapter kind this activity handles */
@@ -43,6 +44,12 @@ export interface AudioActivityOptions<TAdapter extends AudioAdapter<string, Audi
      * control and/or a custom `Logger`.
      */
     debug?: DebugOption;
+    /**
+     * Observe-only middleware notified on start, usage, success, and error. Pass
+     * `otelMiddleware()` to emit OpenTelemetry spans, or implement the
+     * `GenerationMiddleware` contract for a custom backend.
+     */
+    middleware?: Array<GenerationMiddleware>;
 }
 /**
  * Result type for the audio generation activity.

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

@@ -1,6 +1,7 @@
 import { aiEventClient } from "@tanstack/ai-event-client";
 import { streamGenerationResult } from "../stream-generation-result.js";
 import { resolveDebugOption } from "../../logger/resolve.js";
+import { createGenerationContext, runGenerationStart, runGenerationUsage, runGenerationFinish, runGenerationError } from "../middleware/run.js";
 const kind = "audio";
 function createId(prefix) {
   return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
@@ -14,12 +15,27 @@ function generateAudio(options) {
   return runGenerateAudio(options);
 }
 async function runGenerateAudio(options) {
-  const { adapter, stream: _stream, debug: _debug, ...rest } = options;
+  const {
+    adapter,
+    stream: _stream,
+    debug: _debug,
+    middleware,
+    ...rest
+  } = options;
   const model = adapter.model;
   const requestId = createId("audio");
   const startTime = Date.now();
   const logger = resolveDebugOption(options.debug);
   const providerName = adapter.provider ?? adapter.name ?? "unknown";
+  const mwCtx = createGenerationContext({
+    requestId,
+    activity: "audio",
+    provider: adapter.name,
+    model,
+    modelOptions: rest.modelOptions,
+    createId
+  });
+  await runGenerationStart(middleware, mwCtx);
   aiEventClient.emit("audio:request:started", {
     requestId,
     provider: adapter.name,
@@ -58,6 +74,11 @@ async function runGenerateAudio(options) {
       contentType: result.audio.contentType,
       audioDuration: result.audio.duration
     });
+    if (result.usage) await runGenerationUsage(middleware, mwCtx, result.usage);
+    await runGenerationFinish(middleware, mwCtx, {
+      duration: elapsedMs,
+      usage: result.usage
+    });
     return result;
   } catch (error) {
     const elapsedMs = Date.now() - startTime;
@@ -71,6 +92,10 @@ async function runGenerateAudio(options) {
       modelOptions: rest.modelOptions,
       timestamp: Date.now()
     });
+    await runGenerationError(middleware, mwCtx, {
+      error,
+      duration: elapsedMs
+    });
     logger.errors("generateAudio activity failed", {
       error,
       source: "generateAudio"

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../../src/activities/generateAudio/index.ts"],"sourcesContent":["/**\n * Audio Generation Activity\n *\n * Generates audio (music, sound effects, etc.) from text prompts.\n * This is a self-contained module with implementation, types, and JSDoc.\n */\n\nimport { aiEventClient } from '@tanstack/ai-event-client'\nimport { streamGenerationResult } from '../stream-generation-result.js'\nimport { resolveDebugOption } from '../../logger/resolve'\nimport type { InternalLogger } from '../../logger/internal-logger'\nimport type { DebugOption } from '../../logger/types'\nimport type { AudioAdapter } from './adapter'\nimport type { AudioGenerationResult, StreamChunk } from '../../types'\n\n// ===========================\n// Activity Kind\n// ===========================\n\n/** The adapter kind this activity handles */\nexport const kind = 'audio' as const\n\n// ===========================\n// Type Extraction Helpers\n// ===========================\n\n/**\n * Extract provider options from an AudioAdapter via ~types.\n */\nexport type AudioProviderOptions<TAdapter> = TAdapter extends {\n  '~types': { providerOptions: infer P extends object }\n}\n  ? P\n  : object\n\n// ===========================\n// Activity Options Type\n// ===========================\n\n/**\n * Options for the audio generation activity.\n * The model is extracted from the adapter's model property.\n *\n * @template TAdapter - The audio adapter type\n * @template TStream - Whether to stream the output\n */\nexport interface AudioActivityOptions<\n  TAdapter extends AudioAdapter<string, AudioProviderOptions<TAdapter>>,\n  TStream extends boolean = false,\n> {\n  /** The audio adapter to use (must be created with a model) */\n  adapter: TAdapter & { kind: typeof kind }\n  /** Text description of the desired audio */\n  prompt: string\n  /** Desired duration in seconds */\n  duration?: number\n  /** Provider-specific options for audio generation */\n  modelOptions?: AudioProviderOptions<TAdapter>\n  /**\n   * Whether to stream the generation result.\n   * When true, returns an AsyncIterable<StreamChunk> for streaming transport.\n   * When false or not provided, returns a Promise<AudioGenerationResult>.\n   *\n   * @default false\n   */\n  stream?: TStream\n  /**\n   * Enable debug logging. Pass `true` to enable all categories, `false` to\n   * silence everything including errors, or a `DebugConfig` object for granular\n   * control and/or a custom `Logger`.\n   */\n  debug?: DebugOption\n}\n\n// ===========================\n// Activity Result Type\n// ===========================\n\n/**\n * Result type for the audio generation activity.\n * - If stream is true: AsyncIterable<StreamChunk>\n * - Otherwise: Promise<AudioGenerationResult>\n */\nexport type AudioActivityResult<TStream extends boolean = false> =\n  TStream extends true\n    ? AsyncIterable<StreamChunk>\n    : Promise<AudioGenerationResult>\n\nfunction createId(prefix: string): string {\n  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`\n}\n\n// ===========================\n// Activity Implementation\n// ===========================\n\n/**\n * Audio generation activity - generates audio from text prompts.\n *\n * Uses AI models to create music, sound effects, and other audio content.\n *\n * @example Generate music from a prompt\n * ```ts\n * import { generateAudio } from '@tanstack/ai'\n * import { falAudio } from '@tanstack/ai-fal'\n *\n * const result = await generateAudio({\n *   adapter: falAudio('fal-ai/diffrhythm'),\n *   prompt: 'An upbeat electronic track with synths',\n *   duration: 10\n * })\n *\n * console.log(result.audio.url) // URL to generated audio\n * ```\n */\nexport function generateAudio<\n  TAdapter extends AudioAdapter<string, AudioProviderOptions<TAdapter>>,\n  TStream extends boolean = false,\n>(\n  options: AudioActivityOptions<TAdapter, TStream>,\n): AudioActivityResult<TStream> {\n  if (options.stream) {\n    return streamGenerationResult(() =>\n      runGenerateAudio(options),\n    ) as AudioActivityResult<TStream>\n  }\n  return runGenerateAudio(options) as AudioActivityResult<TStream>\n}\n\n/**\n * Run the core audio generation logic (non-streaming).\n */\nasync function runGenerateAudio<\n  TAdapter extends AudioAdapter<string, AudioProviderOptions<TAdapter>>,\n>(\n  options: AudioActivityOptions<TAdapter, boolean>,\n): Promise<AudioGenerationResult> {\n  const { adapter, stream: _stream, debug: _debug, ...rest } = options\n  const model = adapter.model\n  const requestId = createId('audio')\n  const startTime = Date.now()\n  const logger: InternalLogger = resolveDebugOption(options.debug)\n  const providerName =\n    (adapter as { name?: string; provider?: string }).provider ??\n    (adapter as { name?: string }).name ??\n    'unknown'\n\n  aiEventClient.emit('audio:request:started', {\n    requestId,\n    provider: adapter.name,\n    model,\n    prompt: rest.prompt,\n    duration: rest.duration,\n    modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n    timestamp: startTime,\n  })\n\n  logger.request(`activity=generateAudio provider=${providerName}`, {\n    provider: providerName,\n    model,\n  })\n\n  try {\n    const result = await adapter.generateAudio({ ...rest, model, logger })\n    const elapsedMs = Date.now() - startTime\n\n    aiEventClient.emit('audio:request:completed', {\n      requestId,\n      provider: adapter.name,\n      model,\n      audio: result.audio,\n      duration: elapsedMs,\n      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n      timestamp: Date.now(),\n    })\n\n    if (result.usage) {\n      aiEventClient.emit('audio:usage', {\n        requestId,\n        model,\n        usage: result.usage,\n        modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n        timestamp: Date.now(),\n      })\n    }\n\n    logger.output(`activity=generateAudio provider=${providerName}`, {\n      contentType: result.audio.contentType,\n      audioDuration: result.audio.duration,\n    })\n\n    return result\n  } catch (error) {\n    const elapsedMs = Date.now() - startTime\n    const err = error as Error\n    aiEventClient.emit('audio:request:error', {\n      requestId,\n      provider: adapter.name,\n      model,\n      error: { message: err.message, name: err.name },\n      duration: elapsedMs,\n      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n      timestamp: Date.now(),\n    })\n    logger.errors('generateAudio activity failed', {\n      error,\n      source: 'generateAudio',\n    })\n    throw error\n  }\n}\n\n// ===========================\n// Options Factory\n// ===========================\n\n/**\n * Create typed options for the generateAudio() function without executing.\n */\nexport function createAudioOptions<\n  TAdapter extends AudioAdapter<string, AudioProviderOptions<TAdapter>>,\n  TStream extends boolean = false,\n>(\n  options: AudioActivityOptions<TAdapter, TStream>,\n): AudioActivityOptions<TAdapter, TStream> {\n  return options\n}\n\n// Re-export adapter types\nexport type {\n  AudioAdapter,\n  AudioAdapterConfig,\n  AnyAudioAdapter,\n} from './adapter'\nexport { BaseAudioAdapter } from './adapter'\n"],"names":[],"mappings":";;;AAoBO,MAAM,OAAO;AAoEpB,SAAS,SAAS,QAAwB;AACxC,SAAO,GAAG,MAAM,IAAI,KAAK,IAAA,CAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,MAAM,GAAG,CAAC,CAAC;AAC1E;AAyBO,SAAS,cAId,SAC8B;AAC9B,MAAI,QAAQ,QAAQ;AAClB,WAAO;AAAA,MAAuB,MAC5B,iBAAiB,OAAO;AAAA,IAAA;AAAA,EAE5B;AACA,SAAO,iBAAiB,OAAO;AACjC;AAKA,eAAe,iBAGb,SACgC;AAChC,QAAM,EAAE,SAAS,QAAQ,SAAS,OAAO,QAAQ,GAAG,SAAS;AAC7D,QAAM,QAAQ,QAAQ;AACtB,QAAM,YAAY,SAAS,OAAO;AAClC,QAAM,YAAY,KAAK,IAAA;AACvB,QAAM,SAAyB,mBAAmB,QAAQ,KAAK;AAC/D,QAAM,eACH,QAAiD,YACjD,QAA8B,QAC/B;AAEF,gBAAc,KAAK,yBAAyB;AAAA,IAC1C;AAAA,IACA,UAAU,QAAQ;AAAA,IAClB;AAAA,IACA,QAAQ,KAAK;AAAA,IACb,UAAU,KAAK;AAAA,IACf,cAAc,KAAK;AAAA,IACnB,WAAW;AAAA,EAAA,CACZ;AAED,SAAO,QAAQ,mCAAmC,YAAY,IAAI;AAAA,IAChE,UAAU;AAAA,IACV;AAAA,EAAA,CACD;AAED,MAAI;AACF,UAAM,SAAS,MAAM,QAAQ,cAAc,EAAE,GAAG,MAAM,OAAO,QAAQ;AACrE,UAAM,YAAY,KAAK,IAAA,IAAQ;AAE/B,kBAAc,KAAK,2BAA2B;AAAA,MAC5C;AAAA,MACA,UAAU,QAAQ;AAAA,MAClB;AAAA,MACA,OAAO,OAAO;AAAA,MACd,UAAU;AAAA,MACV,cAAc,KAAK;AAAA,MACnB,WAAW,KAAK,IAAA;AAAA,IAAI,CACrB;AAED,QAAI,OAAO,OAAO;AAChB,oBAAc,KAAK,eAAe;AAAA,QAChC;AAAA,QACA;AAAA,QACA,OAAO,OAAO;AAAA,QACd,cAAc,KAAK;AAAA,QACnB,WAAW,KAAK,IAAA;AAAA,MAAI,CACrB;AAAA,IACH;AAEA,WAAO,OAAO,mCAAmC,YAAY,IAAI;AAAA,MAC/D,aAAa,OAAO,MAAM;AAAA,MAC1B,eAAe,OAAO,MAAM;AAAA,IAAA,CAC7B;AAED,WAAO;AAAA,EACT,SAAS,OAAO;AACd,UAAM,YAAY,KAAK,IAAA,IAAQ;AAC/B,UAAM,MAAM;AACZ,kBAAc,KAAK,uBAAuB;AAAA,MACxC;AAAA,MACA,UAAU,QAAQ;AAAA,MAClB;AAAA,MACA,OAAO,EAAE,SAAS,IAAI,SAAS,MAAM,IAAI,KAAA;AAAA,MACzC,UAAU;AAAA,MACV,cAAc,KAAK;AAAA,MACnB,WAAW,KAAK,IAAA;AAAA,IAAI,CACrB;AACD,WAAO,OAAO,iCAAiC;AAAA,MAC7C;AAAA,MACA,QAAQ;AAAA,IAAA,CACT;AACD,UAAM;AAAA,EACR;AACF;AASO,SAAS,mBAId,SACyC;AACzC,SAAO;AACT;"}
+{"version":3,"file":"index.js","sources":["../../../../src/activities/generateAudio/index.ts"],"sourcesContent":["/**\n * Audio Generation Activity\n *\n * Generates audio (music, sound effects, etc.) from text prompts.\n * This is a self-contained module with implementation, types, and JSDoc.\n */\n\nimport { aiEventClient } from '@tanstack/ai-event-client'\nimport { streamGenerationResult } from '../stream-generation-result.js'\nimport { resolveDebugOption } from '../../logger/resolve'\nimport {\n  createGenerationContext,\n  runGenerationError,\n  runGenerationFinish,\n  runGenerationStart,\n  runGenerationUsage,\n} from '../middleware'\nimport type { InternalLogger } from '../../logger/internal-logger'\nimport type { DebugOption } from '../../logger/types'\nimport type { GenerationMiddleware } from '../middleware'\nimport type { AudioAdapter } from './adapter'\nimport type { AudioGenerationResult, StreamChunk } from '../../types'\n\n// ===========================\n// Activity Kind\n// ===========================\n\n/** The adapter kind this activity handles */\nexport const kind = 'audio' as const\n\n// ===========================\n// Type Extraction Helpers\n// ===========================\n\n/**\n * Extract provider options from an AudioAdapter via ~types.\n */\nexport type AudioProviderOptions<TAdapter> = TAdapter extends {\n  '~types': { providerOptions: infer P extends object }\n}\n  ? P\n  : object\n\n// ===========================\n// Activity Options Type\n// ===========================\n\n/**\n * Options for the audio generation activity.\n * The model is extracted from the adapter's model property.\n *\n * @template TAdapter - The audio adapter type\n * @template TStream - Whether to stream the output\n */\nexport interface AudioActivityOptions<\n  TAdapter extends AudioAdapter<string, AudioProviderOptions<TAdapter>>,\n  TStream extends boolean = false,\n> {\n  /** The audio adapter to use (must be created with a model) */\n  adapter: TAdapter & { kind: typeof kind }\n  /** Text description of the desired audio */\n  prompt: string\n  /** Desired duration in seconds */\n  duration?: number\n  /** Provider-specific options for audio generation */\n  modelOptions?: AudioProviderOptions<TAdapter>\n  /**\n   * Whether to stream the generation result.\n   * When true, returns an AsyncIterable<StreamChunk> for streaming transport.\n   * When false or not provided, returns a Promise<AudioGenerationResult>.\n   *\n   * @default false\n   */\n  stream?: TStream\n  /**\n   * Enable debug logging. Pass `true` to enable all categories, `false` to\n   * silence everything including errors, or a `DebugConfig` object for granular\n   * control and/or a custom `Logger`.\n   */\n  debug?: DebugOption\n  /**\n   * Observe-only middleware notified on start, usage, success, and error. Pass\n   * `otelMiddleware()` to emit OpenTelemetry spans, or implement the\n   * `GenerationMiddleware` contract for a custom backend.\n   */\n  middleware?: Array<GenerationMiddleware>\n}\n\n// ===========================\n// Activity Result Type\n// ===========================\n\n/**\n * Result type for the audio generation activity.\n * - If stream is true: AsyncIterable<StreamChunk>\n * - Otherwise: Promise<AudioGenerationResult>\n */\nexport type AudioActivityResult<TStream extends boolean = false> =\n  TStream extends true\n    ? AsyncIterable<StreamChunk>\n    : Promise<AudioGenerationResult>\n\nfunction createId(prefix: string): string {\n  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`\n}\n\n// ===========================\n// Activity Implementation\n// ===========================\n\n/**\n * Audio generation activity - generates audio from text prompts.\n *\n * Uses AI models to create music, sound effects, and other audio content.\n *\n * @example Generate music from a prompt\n * ```ts\n * import { generateAudio } from '@tanstack/ai'\n * import { falAudio } from '@tanstack/ai-fal'\n *\n * const result = await generateAudio({\n *   adapter: falAudio('fal-ai/diffrhythm'),\n *   prompt: 'An upbeat electronic track with synths',\n *   duration: 10\n * })\n *\n * console.log(result.audio.url) // URL to generated audio\n * ```\n */\nexport function generateAudio<\n  TAdapter extends AudioAdapter<string, AudioProviderOptions<TAdapter>>,\n  TStream extends boolean = false,\n>(\n  options: AudioActivityOptions<TAdapter, TStream>,\n): AudioActivityResult<TStream> {\n  if (options.stream) {\n    return streamGenerationResult(() =>\n      runGenerateAudio(options),\n    ) as AudioActivityResult<TStream>\n  }\n  return runGenerateAudio(options) as AudioActivityResult<TStream>\n}\n\n/**\n * Run the core audio generation logic (non-streaming).\n */\nasync function runGenerateAudio<\n  TAdapter extends AudioAdapter<string, AudioProviderOptions<TAdapter>>,\n>(\n  options: AudioActivityOptions<TAdapter, boolean>,\n): Promise<AudioGenerationResult> {\n  const {\n    adapter,\n    stream: _stream,\n    debug: _debug,\n    middleware,\n    ...rest\n  } = options\n  const model = adapter.model\n  const requestId = createId('audio')\n  const startTime = Date.now()\n  const logger: InternalLogger = resolveDebugOption(options.debug)\n  const providerName =\n    (adapter as { name?: string; provider?: string }).provider ??\n    (adapter as { name?: string }).name ??\n    'unknown'\n\n  const mwCtx = createGenerationContext({\n    requestId,\n    activity: 'audio',\n    provider: adapter.name,\n    model,\n    modelOptions: rest.modelOptions,\n    createId,\n  })\n\n  await runGenerationStart(middleware, mwCtx)\n\n  aiEventClient.emit('audio:request:started', {\n    requestId,\n    provider: adapter.name,\n    model,\n    prompt: rest.prompt,\n    duration: rest.duration,\n    modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n    timestamp: startTime,\n  })\n\n  logger.request(`activity=generateAudio provider=${providerName}`, {\n    provider: providerName,\n    model,\n  })\n\n  try {\n    const result = await adapter.generateAudio({ ...rest, model, logger })\n    const elapsedMs = Date.now() - startTime\n\n    aiEventClient.emit('audio:request:completed', {\n      requestId,\n      provider: adapter.name,\n      model,\n      audio: result.audio,\n      duration: elapsedMs,\n      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n      timestamp: Date.now(),\n    })\n\n    if (result.usage) {\n      aiEventClient.emit('audio:usage', {\n        requestId,\n        model,\n        usage: result.usage,\n        modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n        timestamp: Date.now(),\n      })\n    }\n\n    logger.output(`activity=generateAudio provider=${providerName}`, {\n      contentType: result.audio.contentType,\n      audioDuration: result.audio.duration,\n    })\n\n    if (result.usage) await runGenerationUsage(middleware, mwCtx, result.usage)\n    await runGenerationFinish(middleware, mwCtx, {\n      duration: elapsedMs,\n      usage: result.usage,\n    })\n\n    return result\n  } catch (error) {\n    const elapsedMs = Date.now() - startTime\n    const err = error as Error\n    aiEventClient.emit('audio:request:error', {\n      requestId,\n      provider: adapter.name,\n      model,\n      error: { message: err.message, name: err.name },\n      duration: elapsedMs,\n      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n      timestamp: Date.now(),\n    })\n    await runGenerationError(middleware, mwCtx, {\n      error,\n      duration: elapsedMs,\n    })\n    logger.errors('generateAudio activity failed', {\n      error,\n      source: 'generateAudio',\n    })\n    throw error\n  }\n}\n\n// ===========================\n// Options Factory\n// ===========================\n\n/**\n * Create typed options for the generateAudio() function without executing.\n */\nexport function createAudioOptions<\n  TAdapter extends AudioAdapter<string, AudioProviderOptions<TAdapter>>,\n  TStream extends boolean = false,\n>(\n  options: AudioActivityOptions<TAdapter, TStream>,\n): AudioActivityOptions<TAdapter, TStream> {\n  return options\n}\n\n// Re-export adapter types\nexport type {\n  AudioAdapter,\n  AudioAdapterConfig,\n  AnyAudioAdapter,\n} from './adapter'\nexport { BaseAudioAdapter } from './adapter'\n"],"names":[],"mappings":"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"}

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

@@ -1,4 +1,4 @@
-import { ImageGenerationOptions, ImageGenerationResult } from '../../types.js';
+import { ImageGenerationOptions, ImageGenerationResult, ModelInputModalitiesByName } from '../../types.js';
 /**
  * Resolve the size type for a model from the model-size map.
  * If the map has an index signature (i.e. no explicit keys), falls back to string.
@@ -26,8 +26,10 @@ export interface ImageAdapterConfig {
  * - TProviderOptions: Base provider-specific options (already resolved)
  * - TModelProviderOptionsByName: Map from model name to its specific provider options
  * - TModelSizeByName: Map from model name to its supported sizes
+ * - TModelInputModalitiesByName: Map from model name to the non-text prompt
+ *   modalities it accepts (constrains the `prompt` part types at compile time)
  */
-export interface ImageAdapter<TModel extends string = string, TProviderOptions extends object = Record<string, unknown>, TModelProviderOptionsByName extends Record<string, any> = Record<string, any>, TModelSizeByName extends Record<string, string | undefined> = Record<string, string>> {
+export interface ImageAdapter<TModel extends string = string, TProviderOptions extends object = Record<string, unknown>, TModelProviderOptionsByName extends Record<string, any> = Record<string, any>, TModelSizeByName extends Record<string, string | undefined> = Record<string, string>, TModelInputModalitiesByName extends ModelInputModalitiesByName = ModelInputModalitiesByName> {
     /** Discriminator for adapter kind - used by generate() to determine API shape */
     readonly kind: 'image';
     /** Adapter name identifier */
@@ -41,6 +43,7 @@ export interface ImageAdapter<TModel extends string = string, TProviderOptions e
         providerOptions: TProviderOptions;
         modelProviderOptionsByName: TModelProviderOptionsByName;
         modelSizeByName: TModelSizeByName;
+        modelInputModalitiesByName: TModelInputModalitiesByName;
     };
     /**
      * Generate images from a prompt
@@ -51,14 +54,14 @@ export interface ImageAdapter<TModel extends string = string, TProviderOptions e
  * An ImageAdapter with any/unknown type parameters.
  * Useful as a constraint in generic functions and interfaces.
  */
-export type AnyImageAdapter = ImageAdapter<any, any, any, any>;
+export type AnyImageAdapter = ImageAdapter<any, any, any, any, any>;
 /**
  * Abstract base class for image generation adapters.
  * Extend this class to implement an image adapter for a specific provider.
  *
  * Generic parameters match ImageAdapter - all pre-resolved by the provider function.
  */
-export declare abstract class BaseImageAdapter<TModel extends string = string, TProviderOptions extends object = Record<string, unknown>, TModelProviderOptionsByName extends Record<string, any> = Record<string, any>, TModelSizeByName extends Record<string, string | undefined> = Record<string, string>> implements ImageAdapter<TModel, TProviderOptions, TModelProviderOptionsByName, TModelSizeByName> {
+export declare abstract class BaseImageAdapter<TModel extends string = string, TProviderOptions extends object = Record<string, unknown>, TModelProviderOptionsByName extends Record<string, any> = Record<string, any>, TModelSizeByName extends Record<string, string | undefined> = Record<string, string>, TModelInputModalitiesByName extends ModelInputModalitiesByName = ModelInputModalitiesByName> implements ImageAdapter<TModel, TProviderOptions, TModelProviderOptionsByName, TModelSizeByName, TModelInputModalitiesByName> {
     readonly kind: "image";
     abstract readonly name: string;
     readonly model: TModel;
@@ -66,6 +69,7 @@ export declare abstract class BaseImageAdapter<TModel extends string = string, T
         providerOptions: TProviderOptions;
         modelProviderOptionsByName: TModelProviderOptionsByName;
         modelSizeByName: TModelSizeByName;
+        modelInputModalitiesByName: TModelInputModalitiesByName;
     };
     protected config: ImageAdapterConfig;
     constructor(model: TModel, config?: ImageAdapterConfig);

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

@@ -1 +1 @@
-{"version":3,"file":"adapter.js","sources":["../../../../src/activities/generateImage/adapter.ts"],"sourcesContent":["import type { ImageGenerationOptions, ImageGenerationResult } from '../../types'\n\n/**\n * Resolve the size type for a model from the model-size map.\n * If the map has an index signature (i.e. no explicit keys), falls back to string.\n * If the model is an explicit key, uses its mapped size type.\n * Otherwise falls back to string.\n */\n\n/**\n * Configuration for image adapter instances\n */\nexport interface ImageAdapterConfig {\n  apiKey?: string\n  baseUrl?: string\n  timeout?: number\n  maxRetries?: number\n  headers?: Record<string, string>\n}\n\n/**\n * Image 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., 'dall-e-3')\n * - TProviderOptions: Base provider-specific options (already resolved)\n * - TModelProviderOptionsByName: Map from model name to its specific provider options\n * - TModelSizeByName: Map from model name to its supported sizes\n */\nexport interface ImageAdapter<\n  TModel extends string = string,\n  TProviderOptions extends object = Record<string, unknown>,\n  TModelProviderOptionsByName extends Record<string, any> = Record<string, any>,\n  TModelSizeByName extends Record<string, string | undefined> = Record<\n    string,\n    string\n  >,\n> {\n  /** Discriminator for adapter kind - used by generate() to determine API shape */\n  readonly kind: 'image'\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    modelProviderOptionsByName: TModelProviderOptionsByName\n    modelSizeByName: TModelSizeByName\n  }\n\n  /**\n   * Generate images from a prompt\n   */\n  generateImages: (\n    options: ImageGenerationOptions<TProviderOptions, TModelSizeByName[TModel]>,\n  ) => Promise<ImageGenerationResult>\n}\n\n/**\n * An ImageAdapter with any/unknown type parameters.\n * Useful as a constraint in generic functions and interfaces.\n */\nexport type AnyImageAdapter = ImageAdapter<any, any, any, any>\n\n/**\n * Abstract base class for image generation adapters.\n * Extend this class to implement an image adapter for a specific provider.\n *\n * Generic parameters match ImageAdapter - all pre-resolved by the provider function.\n */\nexport abstract class BaseImageAdapter<\n  TModel extends string = string,\n  TProviderOptions extends object = Record<string, unknown>,\n  TModelProviderOptionsByName extends Record<string, any> = Record<string, any>,\n  TModelSizeByName extends Record<string, string | undefined> = Record<\n    string,\n    string\n  >,\n> implements ImageAdapter<\n  TModel,\n  TProviderOptions,\n  TModelProviderOptionsByName,\n  TModelSizeByName\n> {\n  readonly kind = 'image' 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    modelProviderOptionsByName: TModelProviderOptionsByName\n    modelSizeByName: TModelSizeByName\n  }\n\n  protected config: ImageAdapterConfig\n\n  constructor(model: TModel, config: ImageAdapterConfig = {}) {\n    this.config = config\n    this.model = model\n  }\n\n  abstract generateImages(\n    options: ImageGenerationOptions<TProviderOptions, TModelSizeByName[TModel]>,\n  ): Promise<ImageGenerationResult>\n\n  protected generateId(): string {\n    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`\n  }\n}\n"],"names":[],"mappings":"AA6EO,MAAe,iBAapB;AAAA,EACS,OAAO;AAAA,EAEP;AAAA,EASC;AAAA,EAEV,YAAY,OAAe,SAA6B,IAAI;AAC1D,SAAK,SAAS;AACd,SAAK,QAAQ;AAAA,EACf;AAAA,EAMU,aAAqB;AAC7B,WAAO,GAAG,KAAK,IAAI,IAAI,KAAK,KAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,UAAU,CAAC,CAAC;AAAA,EAC9E;AACF;"}
+{"version":3,"file":"adapter.js","sources":["../../../../src/activities/generateImage/adapter.ts"],"sourcesContent":["import type {\n  ImageGenerationOptions,\n  ImageGenerationResult,\n  ModelInputModalitiesByName,\n} from '../../types'\n\n/**\n * Resolve the size type for a model from the model-size map.\n * If the map has an index signature (i.e. no explicit keys), falls back to string.\n * If the model is an explicit key, uses its mapped size type.\n * Otherwise falls back to string.\n */\n\n/**\n * Configuration for image adapter instances\n */\nexport interface ImageAdapterConfig {\n  apiKey?: string\n  baseUrl?: string\n  timeout?: number\n  maxRetries?: number\n  headers?: Record<string, string>\n}\n\n/**\n * Image 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., 'dall-e-3')\n * - TProviderOptions: Base provider-specific options (already resolved)\n * - TModelProviderOptionsByName: Map from model name to its specific provider options\n * - TModelSizeByName: Map from model name to its supported sizes\n * - TModelInputModalitiesByName: Map from model name to the non-text prompt\n *   modalities it accepts (constrains the `prompt` part types at compile time)\n */\nexport interface ImageAdapter<\n  TModel extends string = string,\n  TProviderOptions extends object = Record<string, unknown>,\n  TModelProviderOptionsByName extends Record<string, any> = Record<string, any>,\n  TModelSizeByName extends Record<string, string | undefined> = Record<\n    string,\n    string\n  >,\n  TModelInputModalitiesByName extends ModelInputModalitiesByName =\n    ModelInputModalitiesByName,\n> {\n  /** Discriminator for adapter kind - used by generate() to determine API shape */\n  readonly kind: 'image'\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    modelProviderOptionsByName: TModelProviderOptionsByName\n    modelSizeByName: TModelSizeByName\n    modelInputModalitiesByName: TModelInputModalitiesByName\n  }\n\n  /**\n   * Generate images from a prompt\n   */\n  generateImages: (\n    options: ImageGenerationOptions<TProviderOptions, TModelSizeByName[TModel]>,\n  ) => Promise<ImageGenerationResult>\n}\n\n/**\n * An ImageAdapter with any/unknown type parameters.\n * Useful as a constraint in generic functions and interfaces.\n */\nexport type AnyImageAdapter = ImageAdapter<any, any, any, any, any>\n\n/**\n * Abstract base class for image generation adapters.\n * Extend this class to implement an image adapter for a specific provider.\n *\n * Generic parameters match ImageAdapter - all pre-resolved by the provider function.\n */\nexport abstract class BaseImageAdapter<\n  TModel extends string = string,\n  TProviderOptions extends object = Record<string, unknown>,\n  TModelProviderOptionsByName extends Record<string, any> = Record<string, any>,\n  TModelSizeByName extends Record<string, string | undefined> = Record<\n    string,\n    string\n  >,\n  TModelInputModalitiesByName extends ModelInputModalitiesByName =\n    ModelInputModalitiesByName,\n> implements ImageAdapter<\n  TModel,\n  TProviderOptions,\n  TModelProviderOptionsByName,\n  TModelSizeByName,\n  TModelInputModalitiesByName\n> {\n  readonly kind = 'image' 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    modelProviderOptionsByName: TModelProviderOptionsByName\n    modelSizeByName: TModelSizeByName\n    modelInputModalitiesByName: TModelInputModalitiesByName\n  }\n\n  protected config: ImageAdapterConfig\n\n  constructor(model: TModel, config: ImageAdapterConfig = {}) {\n    this.config = config\n    this.model = model\n  }\n\n  abstract generateImages(\n    options: ImageGenerationOptions<TProviderOptions, TModelSizeByName[TModel]>,\n  ): Promise<ImageGenerationResult>\n\n  protected generateId(): string {\n    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`\n  }\n}\n"],"names":[],"mappings":"AAsFO,MAAe,iBAgBpB;AAAA,EACS,OAAO;AAAA,EAEP;AAAA,EAUC;AAAA,EAEV,YAAY,OAAe,SAA6B,IAAI;AAC1D,SAAK,SAAS;AACd,SAAK,QAAQ;AAAA,EACf;AAAA,EAMU,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/generateImage/index.d.ts

@@ -1,6 +1,7 @@
 import { DebugOption } from '../../logger/types.js';
+import { GenerationMiddleware } from '../middleware.js';
 import { ImageAdapter } from './adapter.js';
-import { ImageGenerationResult, StreamChunk } from '../../types.js';
+import { ImageGenerationResult, MediaPrompt, MediaPromptFor, StreamChunk } from '../../types.js';
 /** The adapter kind this activity handles */
 export declare const kind: "image";
 /**
@@ -14,6 +15,14 @@ export type ImageProviderOptionsForModel<TAdapter, TModel extends string> = TAda
  * If the model has specific sizes defined, use those; otherwise fall back to string.
  */
 export type ImageSizeForModel<TAdapter, TModel extends string> = TAdapter extends ImageAdapter<any, any, any, infer SizeByName> ? string extends keyof SizeByName ? string : TModel extends keyof SizeByName ? SizeByName[TModel] : string : string;
+/**
+ * Extract the prompt type a model accepts from an ImageAdapter via ~types.
+ * Adapters declare a per-model input-modality map; models in the map get a
+ * `prompt` narrowed to text + their supported part types (text-only models
+ * accept `string | Array<TextPart>`), so unsupported media parts fail at
+ * compile time. Adapters without a map fall back to the full MediaPrompt.
+ */
+export type ImagePromptForModel<TAdapter, TModel extends string> = TAdapter extends ImageAdapter<any, any, any, any, infer ModsByName> ? string extends keyof ModsByName ? MediaPrompt : TModel extends keyof ModsByName ? MediaPromptFor<ModsByName[TModel][number]> : MediaPrompt : MediaPrompt;
 /**
  * Options for the image activity.
  * The model is extracted from the adapter's model property.
@@ -26,8 +35,16 @@ export type ImageActivityOptions<TAdapter extends ImageAdapter<string, any, any,
     adapter: TAdapter & {
         kind: typeof kind;
     };
-    /** Text description of the desired image(s) */
-    prompt: string;
+    /**
+     * Description of the desired image(s). Either a plain string, or — for
+     * models that support image-conditioned generation — an ordered array of
+     * content parts interleaving text with image inputs (image-to-image,
+     * reference-guided, edit, multi-reference). Media parts may carry
+     * `metadata.role` (`'reference' | 'mask' | 'control' | 'character'`) to
+     * disambiguate intent. The accepted part types are narrowed per model via
+     * the adapter's input-modality map.
+     */
+    prompt: ImagePromptForModel<TAdapter, TAdapter['model']>;
     /** Number of images to generate (default: 1) */
     numberOfImages?: number;
     /** Image size in WIDTHxHEIGHT format (e.g., "1024x1024") */
@@ -46,6 +63,12 @@ export type ImageActivityOptions<TAdapter extends ImageAdapter<string, any, any,
      * control and/or a custom `Logger`.
      */
     debug?: DebugOption;
+    /**
+     * Observe-only middleware notified on start, usage, success, and error. Pass
+     * `otelMiddleware()` to emit OpenTelemetry spans, or implement the
+     * `GenerationMiddleware` contract for a custom backend.
+     */
+    middleware?: Array<GenerationMiddleware>;
 } & ({} extends ImageProviderOptionsForModel<TAdapter, TAdapter['model']> ? {
     /** Provider-specific options for image generation */ modelOptions?: ImageProviderOptionsForModel<TAdapter, TAdapter['model']>;
 } : {

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

@@ -1,6 +1,8 @@
 import { aiEventClient } from "@tanstack/ai-event-client";
 import { streamGenerationResult } from "../stream-generation-result.js";
 import { resolveDebugOption } from "../../logger/resolve.js";
+import { resolveMediaPrompt } from "../../utilities/media-prompt.js";
+import { createGenerationContext, runGenerationStart, runGenerationUsage, runGenerationFinish, runGenerationError } from "../middleware/run.js";
 const kind = "image";
 function createId(prefix) {
   return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
@@ -14,18 +16,43 @@ function generateImage(options) {
   return runGenerateImage(options);
 }
 async function runGenerateImage(options) {
-  const { adapter, stream: _stream, debug: _debug, ...rest } = options;
+  const {
+    adapter,
+    stream: _stream,
+    debug: _debug,
+    middleware,
+    ...rest
+  } = options;
   const model = adapter.model;
   const requestId = createId("image");
   const startTime = Date.now();
   const logger = resolveDebugOption(options.debug);
+  const mwCtx = createGenerationContext({
+    requestId,
+    activity: "image",
+    provider: adapter.name,
+    model,
+    modelOptions: rest.modelOptions,
+    createId
+  });
+  await runGenerationStart(middleware, mwCtx);
+  const resolved = resolveMediaPrompt(rest.prompt);
   aiEventClient.emit("image:request:started", {
     requestId,
     provider: adapter.name,
     model,
-    prompt: rest.prompt,
+    prompt: resolved.text,
     numberOfImages: rest.numberOfImages,
     size: rest.size,
+    ...resolved.images.length > 0 && {
+      imageInputCount: resolved.images.length
+    },
+    ...resolved.videos.length > 0 && {
+      videoInputCount: resolved.videos.length
+    },
+    ...resolved.audios.length > 0 && {
+      audioInputCount: resolved.audios.length
+    },
     modelOptions: rest.modelOptions,
     timestamp: startTime
   });
@@ -65,8 +92,17 @@ async function runGenerateImage(options) {
     logger.output(`activity=generateImage count=${result.images.length}`, {
       count: result.images.length
     });
+    if (result.usage) await runGenerationUsage(middleware, mwCtx, result.usage);
+    await runGenerationFinish(middleware, mwCtx, {
+      duration,
+      usage: result.usage
+    });
     return result;
   } catch (error) {
+    await runGenerationError(middleware, mwCtx, {
+      error,
+      duration: Date.now() - startTime
+    });
     logger.errors("generateImage activity failed", {
       error,
       source: "generateImage"

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../../src/activities/generateImage/index.ts"],"sourcesContent":["/**\n * Image Activity\n *\n * Generates images from text prompts.\n * This is a self-contained module with implementation, types, and JSDoc.\n */\n\nimport { aiEventClient } from '@tanstack/ai-event-client'\nimport { streamGenerationResult } from '../stream-generation-result.js'\nimport { resolveDebugOption } from '../../logger/resolve'\nimport type { InternalLogger } from '../../logger/internal-logger'\nimport type { DebugOption } from '../../logger/types'\nimport type { ImageAdapter } from './adapter'\nimport type { ImageGenerationResult, StreamChunk } from '../../types'\n\n// ===========================\n// Activity Kind\n// ===========================\n\n/** The adapter kind this activity handles */\nexport const kind = 'image' as const\n\n// ===========================\n// Type Extraction Helpers\n// ===========================\n\n/**\n * Extract model-specific provider options from an ImageAdapter via ~types.\n * If the model has specific options defined in ModelProviderOptions (and not just via index signature),\n * use those; otherwise fall back to base provider options.\n */\nexport type ImageProviderOptionsForModel<TAdapter, TModel extends string> =\n  TAdapter extends ImageAdapter<any, infer BaseOptions, infer ModelOptions, any>\n    ? string extends keyof ModelOptions\n      ? // ModelOptions is Record<string, unknown> or has index signature - use BaseOptions\n        BaseOptions\n      : // ModelOptions has explicit keys - check if TModel is one of them\n        TModel extends keyof ModelOptions\n        ? ModelOptions[TModel]\n        : BaseOptions\n    : object\n\n/**\n * Extract model-specific size options from an ImageAdapter via ~types.\n * If the model has specific sizes defined, use those; otherwise fall back to string.\n */\nexport type ImageSizeForModel<TAdapter, TModel extends string> =\n  TAdapter extends ImageAdapter<any, any, any, infer SizeByName>\n    ? string extends keyof SizeByName\n      ? // SizeByName has index signature - fall back to string\n        string\n      : // SizeByName has explicit keys - check if TModel is one of them\n        TModel extends keyof SizeByName\n        ? SizeByName[TModel]\n        : string\n    : string\n\n// ===========================\n// Activity Options Type\n// ===========================\n\n/**\n * Options for the image activity.\n * The model is extracted from the adapter's model property.\n *\n * @template TAdapter - The image adapter type\n * @template TStream - Whether to stream the output\n */\nexport type ImageActivityOptions<\n  TAdapter extends ImageAdapter<string, any, any, any>,\n  TStream extends boolean = false,\n> = {\n  /** The image adapter to use (must be created with a model) */\n  adapter: TAdapter & { kind: typeof kind }\n  /** Text description of the desired image(s) */\n  prompt: string\n  /** Number of images to generate (default: 1) */\n  numberOfImages?: number\n  /** Image size in WIDTHxHEIGHT format (e.g., \"1024x1024\") */\n  size?: ImageSizeForModel<TAdapter, TAdapter['model']>\n  /**\n   * Whether to stream the image generation result.\n   * When true, returns an AsyncIterable<StreamChunk> for streaming transport.\n   * When false or not provided, returns a Promise<ImageGenerationResult>.\n   *\n   * @default false\n   */\n  stream?: TStream\n  /**\n   * Enable debug logging. Pass `true` to enable all categories, `false` to\n   * silence everything including errors, or a `DebugConfig` object for granular\n   * control and/or a custom `Logger`.\n   */\n  debug?: DebugOption\n} & ({} extends ImageProviderOptionsForModel<TAdapter, TAdapter['model']>\n  ? {\n      /** Provider-specific options for image generation */ modelOptions?: ImageProviderOptionsForModel<\n        TAdapter,\n        TAdapter['model']\n      >\n    }\n  : {\n      /** Provider-specific options for image generation */ modelOptions: ImageProviderOptionsForModel<\n        TAdapter,\n        TAdapter['model']\n      >\n    })\n\n// ===========================\n// Activity Result Type\n// ===========================\n\n/**\n * Result type for the image activity.\n * - If stream is true: AsyncIterable<StreamChunk>\n * - Otherwise: Promise<ImageGenerationResult>\n */\nexport type ImageActivityResult<TStream extends boolean = false> =\n  TStream extends true\n    ? AsyncIterable<StreamChunk>\n    : Promise<ImageGenerationResult>\n\nfunction createId(prefix: string): string {\n  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`\n}\n\n// ===========================\n// Activity Implementation\n// ===========================\n\n/**\n * Image activity - generates images from text prompts.\n *\n * Uses AI image generation models to create images based on natural language descriptions.\n *\n * @example Generate a single image\n * ```ts\n * import { generateImage } from '@tanstack/ai'\n * import { openaiImage } from '@tanstack/ai-openai'\n *\n * const result = await generateImage({\n *   adapter: openaiImage('dall-e-3'),\n *   prompt: 'A serene mountain landscape at sunset'\n * })\n *\n * console.log(result.images[0].url)\n * ```\n *\n * @example Generate multiple images\n * ```ts\n * const result = await generateImage({\n *   adapter: openaiImage('dall-e-2'),\n *   prompt: 'A cute robot mascot',\n *   numberOfImages: 4,\n *   size: '512x512'\n * })\n *\n * result.images.forEach((image, i) => {\n *   console.log(`Image ${i + 1}: ${image.url}`)\n * })\n * ```\n *\n * @example With provider-specific options\n * ```ts\n * const result = await generateImage({\n *   adapter: openaiImage('dall-e-3'),\n *   prompt: 'A professional headshot photo',\n *   size: '1024x1024',\n *   modelOptions: {\n *     quality: 'hd',\n *     style: 'natural'\n *   }\n * })\n * ```\n */\nexport function generateImage<\n  TAdapter extends ImageAdapter<string, any, any, any>,\n  TStream extends boolean = false,\n>(\n  options: ImageActivityOptions<TAdapter, TStream>,\n): ImageActivityResult<TStream> {\n  if (options.stream) {\n    return streamGenerationResult(() =>\n      runGenerateImage(options),\n    ) as ImageActivityResult<TStream>\n  }\n\n  return runGenerateImage(options) as ImageActivityResult<TStream>\n}\n\n/**\n * Internal implementation of image generation (always non-streaming).\n * Contains all devtools event emission logic.\n */\nasync function runGenerateImage<\n  TAdapter extends ImageAdapter<string, any, any, any>,\n>(\n  options: ImageActivityOptions<TAdapter, boolean>,\n): Promise<ImageGenerationResult> {\n  const { adapter, stream: _stream, debug: _debug, ...rest } = options\n  const model = adapter.model\n  const requestId = createId('image')\n  const startTime = Date.now()\n  const logger: InternalLogger = resolveDebugOption(options.debug)\n\n  aiEventClient.emit('image:request:started', {\n    requestId,\n    provider: adapter.name,\n    model,\n    prompt: rest.prompt,\n    numberOfImages: rest.numberOfImages,\n    size: rest.size,\n    modelOptions: rest.modelOptions,\n    timestamp: startTime,\n  })\n\n  logger.request(`activity=generateImage provider=${adapter.name}`, {\n    provider: adapter.name,\n    model,\n  })\n\n  try {\n    const result = await adapter.generateImages({ ...rest, model, logger })\n    const duration = Date.now() - startTime\n\n    aiEventClient.emit('image:request:completed', {\n      requestId,\n      provider: adapter.name,\n      model,\n      // GeneratedImage is a discriminated `{ url } | { b64Json }` union, but the\n      // wire shape on the devtools event is a plain optional pair. Use\n      // conditional spreads so the emitted record only sets the field actually\n      // present — `exactOptionalPropertyTypes` rejects `field: undefined`\n      // against `field?: string` targets.\n      images: result.images.map((image) => ({\n        url: image.url,\n        b64Json: image.b64Json,\n      })),\n      duration,\n      modelOptions: rest.modelOptions,\n      timestamp: Date.now(),\n    })\n\n    if (result.usage) {\n      aiEventClient.emit('image:usage', {\n        requestId,\n        model,\n        usage: result.usage,\n        modelOptions: rest.modelOptions,\n        timestamp: Date.now(),\n      })\n    }\n\n    logger.output(`activity=generateImage count=${result.images.length}`, {\n      count: result.images.length,\n    })\n\n    return result\n  } catch (error) {\n    logger.errors('generateImage activity failed', {\n      error,\n      source: 'generateImage',\n    })\n    throw error\n  }\n}\n\n// ===========================\n// Options Factory\n// ===========================\n\n/**\n * Create typed options for the generateImage() function without executing.\n */\nexport function createImageOptions<\n  TAdapter extends ImageAdapter<string, any, any, any>,\n  TStream extends boolean = false,\n>(\n  options: ImageActivityOptions<TAdapter, TStream>,\n): ImageActivityOptions<TAdapter, TStream> {\n  return options\n}\n\n// Re-export adapter types\nexport type {\n  ImageAdapter,\n  ImageAdapterConfig,\n  AnyImageAdapter,\n} from './adapter'\nexport { BaseImageAdapter } from './adapter'\n"],"names":[],"mappings":";;;AAoBO,MAAM,OAAO;AAsGpB,SAAS,SAAS,QAAwB;AACxC,SAAO,GAAG,MAAM,IAAI,KAAK,IAAA,CAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,MAAM,GAAG,CAAC,CAAC;AAC1E;AAmDO,SAAS,cAId,SAC8B;AAC9B,MAAI,QAAQ,QAAQ;AAClB,WAAO;AAAA,MAAuB,MAC5B,iBAAiB,OAAO;AAAA,IAAA;AAAA,EAE5B;AAEA,SAAO,iBAAiB,OAAO;AACjC;AAMA,eAAe,iBAGb,SACgC;AAChC,QAAM,EAAE,SAAS,QAAQ,SAAS,OAAO,QAAQ,GAAG,SAAS;AAC7D,QAAM,QAAQ,QAAQ;AACtB,QAAM,YAAY,SAAS,OAAO;AAClC,QAAM,YAAY,KAAK,IAAA;AACvB,QAAM,SAAyB,mBAAmB,QAAQ,KAAK;AAE/D,gBAAc,KAAK,yBAAyB;AAAA,IAC1C;AAAA,IACA,UAAU,QAAQ;AAAA,IAClB;AAAA,IACA,QAAQ,KAAK;AAAA,IACb,gBAAgB,KAAK;AAAA,IACrB,MAAM,KAAK;AAAA,IACX,cAAc,KAAK;AAAA,IACnB,WAAW;AAAA,EAAA,CACZ;AAED,SAAO,QAAQ,mCAAmC,QAAQ,IAAI,IAAI;AAAA,IAChE,UAAU,QAAQ;AAAA,IAClB;AAAA,EAAA,CACD;AAED,MAAI;AACF,UAAM,SAAS,MAAM,QAAQ,eAAe,EAAE,GAAG,MAAM,OAAO,QAAQ;AACtE,UAAM,WAAW,KAAK,IAAA,IAAQ;AAE9B,kBAAc,KAAK,2BAA2B;AAAA,MAC5C;AAAA,MACA,UAAU,QAAQ;AAAA,MAClB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,MAMA,QAAQ,OAAO,OAAO,IAAI,CAAC,WAAW;AAAA,QACpC,KAAK,MAAM;AAAA,QACX,SAAS,MAAM;AAAA,MAAA,EACf;AAAA,MACF;AAAA,MACA,cAAc,KAAK;AAAA,MACnB,WAAW,KAAK,IAAA;AAAA,IAAI,CACrB;AAED,QAAI,OAAO,OAAO;AAChB,oBAAc,KAAK,eAAe;AAAA,QAChC;AAAA,QACA;AAAA,QACA,OAAO,OAAO;AAAA,QACd,cAAc,KAAK;AAAA,QACnB,WAAW,KAAK,IAAA;AAAA,MAAI,CACrB;AAAA,IACH;AAEA,WAAO,OAAO,gCAAgC,OAAO,OAAO,MAAM,IAAI;AAAA,MACpE,OAAO,OAAO,OAAO;AAAA,IAAA,CACtB;AAED,WAAO;AAAA,EACT,SAAS,OAAO;AACd,WAAO,OAAO,iCAAiC;AAAA,MAC7C;AAAA,MACA,QAAQ;AAAA,IAAA,CACT;AACD,UAAM;AAAA,EACR;AACF;AASO,SAAS,mBAId,SACyC;AACzC,SAAO;AACT;"}
+{"version":3,"file":"index.js","sources":["../../../../src/activities/generateImage/index.ts"],"sourcesContent":["/**\n * Image Activity\n *\n * Generates images from text prompts.\n * This is a self-contained module with implementation, types, and JSDoc.\n */\n\nimport { aiEventClient } from '@tanstack/ai-event-client'\nimport { streamGenerationResult } from '../stream-generation-result.js'\nimport { resolveDebugOption } from '../../logger/resolve'\nimport {\n  createGenerationContext,\n  runGenerationError,\n  runGenerationFinish,\n  runGenerationStart,\n  runGenerationUsage,\n} from '../middleware'\nimport { resolveMediaPrompt } from '../../utilities/media-prompt'\nimport type { InternalLogger } from '../../logger/internal-logger'\nimport type { DebugOption } from '../../logger/types'\nimport type { GenerationMiddleware } from '../middleware'\nimport type { ImageAdapter } from './adapter'\nimport type {\n  ImageGenerationResult,\n  MediaPrompt,\n  MediaPromptFor,\n  StreamChunk,\n} from '../../types'\n\n// ===========================\n// Activity Kind\n// ===========================\n\n/** The adapter kind this activity handles */\nexport const kind = 'image' as const\n\n// ===========================\n// Type Extraction Helpers\n// ===========================\n\n/**\n * Extract model-specific provider options from an ImageAdapter via ~types.\n * If the model has specific options defined in ModelProviderOptions (and not just via index signature),\n * use those; otherwise fall back to base provider options.\n */\nexport type ImageProviderOptionsForModel<TAdapter, TModel extends string> =\n  TAdapter extends ImageAdapter<any, infer BaseOptions, infer ModelOptions, any>\n    ? string extends keyof ModelOptions\n      ? // ModelOptions is Record<string, unknown> or has index signature - use BaseOptions\n        BaseOptions\n      : // ModelOptions has explicit keys - check if TModel is one of them\n        TModel extends keyof ModelOptions\n        ? ModelOptions[TModel]\n        : BaseOptions\n    : object\n\n/**\n * Extract model-specific size options from an ImageAdapter via ~types.\n * If the model has specific sizes defined, use those; otherwise fall back to string.\n */\nexport type ImageSizeForModel<TAdapter, TModel extends string> =\n  TAdapter extends ImageAdapter<any, any, any, infer SizeByName>\n    ? string extends keyof SizeByName\n      ? // SizeByName has index signature - fall back to string\n        string\n      : // SizeByName has explicit keys - check if TModel is one of them\n        TModel extends keyof SizeByName\n        ? SizeByName[TModel]\n        : string\n    : string\n\n/**\n * Extract the prompt type a model accepts from an ImageAdapter via ~types.\n * Adapters declare a per-model input-modality map; models in the map get a\n * `prompt` narrowed to text + their supported part types (text-only models\n * accept `string | Array<TextPart>`), so unsupported media parts fail at\n * compile time. Adapters without a map fall back to the full MediaPrompt.\n */\nexport type ImagePromptForModel<TAdapter, TModel extends string> =\n  TAdapter extends ImageAdapter<any, any, any, any, infer ModsByName>\n    ? string extends keyof ModsByName\n      ? // No explicit map - accept the full union\n        MediaPrompt\n      : TModel extends keyof ModsByName\n        ? MediaPromptFor<ModsByName[TModel][number]>\n        : MediaPrompt\n    : MediaPrompt\n\n// ===========================\n// Activity Options Type\n// ===========================\n\n/**\n * Options for the image activity.\n * The model is extracted from the adapter's model property.\n *\n * @template TAdapter - The image adapter type\n * @template TStream - Whether to stream the output\n */\nexport type ImageActivityOptions<\n  TAdapter extends ImageAdapter<string, any, any, any>,\n  TStream extends boolean = false,\n> = {\n  /** The image adapter to use (must be created with a model) */\n  adapter: TAdapter & { kind: typeof kind }\n  /**\n   * Description of the desired image(s). Either a plain string, or — for\n   * models that support image-conditioned generation — an ordered array of\n   * content parts interleaving text with image inputs (image-to-image,\n   * reference-guided, edit, multi-reference). Media parts may carry\n   * `metadata.role` (`'reference' | 'mask' | 'control' | 'character'`) to\n   * disambiguate intent. The accepted part types are narrowed per model via\n   * the adapter's input-modality map.\n   */\n  prompt: ImagePromptForModel<TAdapter, TAdapter['model']>\n  /** Number of images to generate (default: 1) */\n  numberOfImages?: number\n  /** Image size in WIDTHxHEIGHT format (e.g., \"1024x1024\") */\n  size?: ImageSizeForModel<TAdapter, TAdapter['model']>\n  /**\n   * Whether to stream the image generation result.\n   * When true, returns an AsyncIterable<StreamChunk> for streaming transport.\n   * When false or not provided, returns a Promise<ImageGenerationResult>.\n   *\n   * @default false\n   */\n  stream?: TStream\n  /**\n   * Enable debug logging. Pass `true` to enable all categories, `false` to\n   * silence everything including errors, or a `DebugConfig` object for granular\n   * control and/or a custom `Logger`.\n   */\n  debug?: DebugOption\n  /**\n   * Observe-only middleware notified on start, usage, success, and error. Pass\n   * `otelMiddleware()` to emit OpenTelemetry spans, or implement the\n   * `GenerationMiddleware` contract for a custom backend.\n   */\n  middleware?: Array<GenerationMiddleware>\n} & ({} extends ImageProviderOptionsForModel<TAdapter, TAdapter['model']>\n  ? {\n      /** Provider-specific options for image generation */ modelOptions?: ImageProviderOptionsForModel<\n        TAdapter,\n        TAdapter['model']\n      >\n    }\n  : {\n      /** Provider-specific options for image generation */ modelOptions: ImageProviderOptionsForModel<\n        TAdapter,\n        TAdapter['model']\n      >\n    })\n\n// ===========================\n// Activity Result Type\n// ===========================\n\n/**\n * Result type for the image activity.\n * - If stream is true: AsyncIterable<StreamChunk>\n * - Otherwise: Promise<ImageGenerationResult>\n */\nexport type ImageActivityResult<TStream extends boolean = false> =\n  TStream extends true\n    ? AsyncIterable<StreamChunk>\n    : Promise<ImageGenerationResult>\n\nfunction createId(prefix: string): string {\n  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`\n}\n\n// ===========================\n// Activity Implementation\n// ===========================\n\n/**\n * Image activity - generates images from text prompts.\n *\n * Uses AI image generation models to create images based on natural language descriptions.\n *\n * @example Generate a single image\n * ```ts\n * import { generateImage } from '@tanstack/ai'\n * import { openaiImage } from '@tanstack/ai-openai'\n *\n * const result = await generateImage({\n *   adapter: openaiImage('dall-e-3'),\n *   prompt: 'A serene mountain landscape at sunset'\n * })\n *\n * console.log(result.images[0].url)\n * ```\n *\n * @example Generate multiple images\n * ```ts\n * const result = await generateImage({\n *   adapter: openaiImage('dall-e-2'),\n *   prompt: 'A cute robot mascot',\n *   numberOfImages: 4,\n *   size: '512x512'\n * })\n *\n * result.images.forEach((image, i) => {\n *   console.log(`Image ${i + 1}: ${image.url}`)\n * })\n * ```\n *\n * @example With provider-specific options\n * ```ts\n * const result = await generateImage({\n *   adapter: openaiImage('dall-e-3'),\n *   prompt: 'A professional headshot photo',\n *   size: '1024x1024',\n *   modelOptions: {\n *     quality: 'hd',\n *     style: 'natural'\n *   }\n * })\n * ```\n */\nexport function generateImage<\n  TAdapter extends ImageAdapter<string, any, any, any>,\n  TStream extends boolean = false,\n>(\n  options: ImageActivityOptions<TAdapter, TStream>,\n): ImageActivityResult<TStream> {\n  if (options.stream) {\n    return streamGenerationResult(() =>\n      runGenerateImage(options),\n    ) as ImageActivityResult<TStream>\n  }\n\n  return runGenerateImage(options) as ImageActivityResult<TStream>\n}\n\n/**\n * Internal implementation of image generation (always non-streaming).\n * Contains all devtools event emission logic.\n */\nasync function runGenerateImage<\n  TAdapter extends ImageAdapter<string, any, any, any>,\n>(\n  options: ImageActivityOptions<TAdapter, boolean>,\n): Promise<ImageGenerationResult> {\n  const {\n    adapter,\n    stream: _stream,\n    debug: _debug,\n    middleware,\n    ...rest\n  } = options\n  const model = adapter.model\n  const requestId = createId('image')\n  const startTime = Date.now()\n  const logger: InternalLogger = resolveDebugOption(options.debug)\n\n  const mwCtx = createGenerationContext({\n    requestId,\n    activity: 'image',\n    provider: adapter.name,\n    model,\n    modelOptions: rest.modelOptions,\n    createId,\n  })\n\n  await runGenerationStart(middleware, mwCtx)\n\n  // Devtools events carry the flattened prompt text plus media-part counts —\n  // the wire payload stays `prompt: string` regardless of the prompt shape.\n  const resolved = resolveMediaPrompt(rest.prompt)\n\n  aiEventClient.emit('image:request:started', {\n    requestId,\n    provider: adapter.name,\n    model,\n    prompt: resolved.text,\n    numberOfImages: rest.numberOfImages,\n    size: rest.size,\n    ...(resolved.images.length > 0 && {\n      imageInputCount: resolved.images.length,\n    }),\n    ...(resolved.videos.length > 0 && {\n      videoInputCount: resolved.videos.length,\n    }),\n    ...(resolved.audios.length > 0 && {\n      audioInputCount: resolved.audios.length,\n    }),\n    modelOptions: rest.modelOptions,\n    timestamp: startTime,\n  })\n\n  logger.request(`activity=generateImage provider=${adapter.name}`, {\n    provider: adapter.name,\n    model,\n  })\n\n  try {\n    const result = await adapter.generateImages({ ...rest, model, logger })\n    const duration = Date.now() - startTime\n\n    aiEventClient.emit('image:request:completed', {\n      requestId,\n      provider: adapter.name,\n      model,\n      // GeneratedImage is a discriminated `{ url } | { b64Json }` union, but the\n      // wire shape on the devtools event is a plain optional pair. Use\n      // conditional spreads so the emitted record only sets the field actually\n      // present — `exactOptionalPropertyTypes` rejects `field: undefined`\n      // against `field?: string` targets.\n      images: result.images.map((image) => ({\n        url: image.url,\n        b64Json: image.b64Json,\n      })),\n      duration,\n      modelOptions: rest.modelOptions,\n      timestamp: Date.now(),\n    })\n\n    if (result.usage) {\n      aiEventClient.emit('image:usage', {\n        requestId,\n        model,\n        usage: result.usage,\n        modelOptions: rest.modelOptions,\n        timestamp: Date.now(),\n      })\n    }\n\n    logger.output(`activity=generateImage count=${result.images.length}`, {\n      count: result.images.length,\n    })\n\n    if (result.usage) await runGenerationUsage(middleware, mwCtx, result.usage)\n    await runGenerationFinish(middleware, mwCtx, {\n      duration,\n      usage: result.usage,\n    })\n\n    return result\n  } catch (error) {\n    await runGenerationError(middleware, mwCtx, {\n      error,\n      duration: Date.now() - startTime,\n    })\n    logger.errors('generateImage activity failed', {\n      error,\n      source: 'generateImage',\n    })\n    throw error\n  }\n}\n\n// ===========================\n// Options Factory\n// ===========================\n\n/**\n * Create typed options for the generateImage() function without executing.\n */\nexport function createImageOptions<\n  TAdapter extends ImageAdapter<string, any, any, any>,\n  TStream extends boolean = false,\n>(\n  options: ImageActivityOptions<TAdapter, TStream>,\n): ImageActivityOptions<TAdapter, TStream> {\n  return options\n}\n\n// Re-export adapter types\nexport type {\n  ImageAdapter,\n  ImageAdapterConfig,\n  AnyImageAdapter,\n} from './adapter'\nexport { BaseImageAdapter } from './adapter'\n"],"names":[],"mappings":"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"}

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

@@ -1,4 +1,5 @@
 import { DebugOption } from '../../logger/types.js';
+import { GenerationMiddleware } from '../middleware.js';
 import { TTSAdapter } from './adapter.js';
 import { StreamChunk, TTSResult } from '../../types.js';
 /** The adapter kind this activity handles */
@@ -43,6 +44,12 @@ export interface TTSActivityOptions<TAdapter extends TTSAdapter<string, TTSProvi
      * control and/or a custom `Logger`.
      */
     debug?: DebugOption;
+    /**
+     * Observe-only middleware notified on start, usage, success, and error. Pass
+     * `otelMiddleware()` to emit OpenTelemetry spans, or implement the
+     * `GenerationMiddleware` contract for a custom backend.
+     */
+    middleware?: Array<GenerationMiddleware>;
 }
 /**
  * Result type for the TTS activity.