@ai-sdk/open-responses 2.0.31 → 2.0.35

package/docs/06-open-responses.mdx

@@ -239,10 +239,124 @@ file's media type. Provider file references, such as OpenAI file IDs, and
 file data in `{ type: 'text', text: '...' }` format are not supported by this
 provider.
 
+## Experimental Extensions
+
+Open Responses implementations can add namespaced tools, items, and streaming
+events. Use `Experimental_OpenResponsesExtension` to encode and decode an
+implementation's extension wire formats. Unregistered provider tools are
+omitted from requests with an `unsupported` warning.
+
+This API is experimental and may change in a future release.
+
+The AI SDK provider-tool ID uses dot notation (`acme.document_search`), while
+Open Responses wire types use colon notation (`acme:document_search`). The
+namespace in `id` must match the namespace in every registered wire type.
+
+```ts
+import {
+  createOpenResponses,
+  type Experimental_OpenResponsesExtension,
+} from '@ai-sdk/open-responses';
+import { generateText, tool } from 'ai';
+import { z } from 'zod';
+
+const documentSearchExtension: Experimental_OpenResponsesExtension = {
+  id: 'acme.document_search',
+  toolType: 'acme:document_search',
+  itemTypes: ['acme:document_search_receipt'],
+  encodeTool: ({ name, args }) => ({
+    name,
+    index: args.index as string,
+  }),
+
+  decodeItem: ({ item }) => [
+    {
+      type: 'tool-call',
+      toolCallId: item.call_id as string,
+      toolName: item.name as string,
+      input: JSON.stringify(item.query),
+      providerExecuted: true,
+    },
+    {
+      type: 'tool-result',
+      toolCallId: item.call_id as string,
+      toolName: item.name as string,
+      result: item.result!,
+    },
+  ],
+};
+
+const acme = createOpenResponses({
+  name: 'acme',
+  url: 'https://api.acme.example/v1/responses',
+  experimental_extensions: [documentSearchExtension],
+});
+
+const documentSearch = tool({
+  type: 'provider',
+  id: 'acme.document_search',
+  args: { index: 'documentation' },
+  isProviderExecuted: true,
+  inputSchema: z.object({ text: z.string() }),
+  outputSchema: z.object({
+    documents: z.array(
+      z.object({
+        id: z.string(),
+        title: z.string(),
+      }),
+    ),
+  }),
+});
+
+const result = await generateText({
+  model: acme('your-model-id'),
+  prompt: 'Find the extension documentation.',
+  tools: { documentSearch },
+});
+```
+
+Set `providerExecuted` on each decoded `tool-call` or `tool-input-start` part.
+It can vary by item or event.
+
+An extension codec can define:
+
+- `encodeTool`: Encodes a provider tool. Returning `undefined` omits the tool
+  with an `unsupported` warning. A `toolChoice` that selects the omitted tool is
+  also omitted.
+- `encodeToolChoice`: Encodes a specific `toolChoice`. The default is
+  `{ type: toolType }`.
+- `decodeItem`: Maps a completed item to AI SDK content parts. `mode` is either
+  `'generate'` or `'stream'`.
+- `encodeInputItem`: Encodes tool-call or tool-result history when the original
+  wire item is unavailable. Returned items must include `id`, `status`, and a
+  registered namespaced `type`.
+- `decodeEvent`: Maps a streaming event to AI SDK stream parts. Its `state` map
+  lasts for one response stream.
+
+Tool, item, and event capabilities are independent. An item-only extension, for
+example, defines `itemTypes` and `decodeItem` without `toolType` or `encodeTool`.
+Capability fields must be provided in pairs.
+
+Each decoded item adds an `open-responses.extension-replay` custom part that
+stores the original JSON in provider metadata. Other decoded parts reference
+that custom part instead of copying the item. Passing `result.response.messages`
+to a later call replays the original item once, including opaque fields. This
+also preserves items that decode only to response-only source parts.
+
+The adapter validates only the extension discriminator fields. Validate other
+item and event fields in the codec before returning AI SDK parts. The original
+item is stored in provider metadata and may appear in persisted messages,
+telemetry, logs, or UI payloads.
+
+Extension callbacks cannot be serialized across workflow step boundaries.
+Create the provider inside the workflow step. Serializing a model configured
+with extensions throws a `SerializationError`.
+
 ## Limitations
 
 - Stop sequences, `topK`, and `seed` are not supported and are ignored with warnings.
 - The provider supports language models only. It does not provide embedding or
   image generation models.
-- AI SDK function tools are supported. Provider-specific built-in tools and
-  options require a dedicated provider implementation.
+- AI SDK function tools and registered Open Responses extensions are supported.
+  Other provider-specific tools and options require a dedicated provider
+  implementation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/open-responses",
-  "version": "2.0.31",
+  "version": "2.0.35",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -30,7 +30,7 @@
   },
   "dependencies": {
     "@ai-sdk/provider": "4.0.8",
-    "@ai-sdk/provider-utils": "5.0.30"
+    "@ai-sdk/provider-utils": "5.0.33"
   },
   "devDependencies": {
     "@ai-sdk/test-server": "2.0.1",

package/src/index.ts

@@ -4,6 +4,16 @@ export type {
   OpenResponsesProvider,
   OpenResponsesProviderSettings,
 } from './open-responses-provider';
+export type {
+  OpenResponsesExtension as Experimental_OpenResponsesExtension,
+  OpenResponsesExtensionContentPart as Experimental_OpenResponsesExtensionContentPart,
+  OpenResponsesExtensionEvent as Experimental_OpenResponsesExtensionEvent,
+  OpenResponsesExtensionInputPart as Experimental_OpenResponsesExtensionInputPart,
+  OpenResponsesExtensionItem as Experimental_OpenResponsesExtensionItem,
+  OpenResponsesExtensionRecord as Experimental_OpenResponsesExtensionRecord,
+  OpenResponsesExtensionStreamPart as Experimental_OpenResponsesExtensionStreamPart,
+  OpenResponsesNamespacedType as Experimental_OpenResponsesNamespacedType,
+} from './open-responses-extension';
 export type {
   OpenResponsesLanguageModelOptions,
   /** @deprecated Use `OpenResponsesLanguageModelOptions` instead. */

package/src/open-responses-extension.ts

@@ -0,0 +1,387 @@
+import type {
+  JSONObject,
+  LanguageModelV4Content,
+  LanguageModelV4ProviderTool,
+  LanguageModelV4StreamPart,
+  LanguageModelV4ToolCallPart,
+  LanguageModelV4ToolResultPart,
+} from '@ai-sdk/provider';
+import type { MaybePromiseLike } from '@ai-sdk/provider-utils';
+
+export type OpenResponsesNamespacedType = `${string}:${string}`;
+
+export type OpenResponsesExtensionRecord = JSONObject & {
+  type: OpenResponsesNamespacedType;
+};
+
+export type OpenResponsesExtensionItem = OpenResponsesExtensionRecord & {
+  id: string;
+  status: string;
+};
+
+export type OpenResponsesExtensionEvent = OpenResponsesExtensionRecord & {
+  sequence_number: number;
+};
+
+export type OpenResponsesExtensionInputPart =
+  | LanguageModelV4ToolCallPart
+  | LanguageModelV4ToolResultPart;
+
+export type OpenResponsesExtensionContentPart = Extract<
+  LanguageModelV4Content,
+  LanguageModelV4StreamPart
+>;
+
+export type OpenResponsesExtensionStreamPart = Exclude<
+  LanguageModelV4StreamPart,
+  {
+    type: 'error' | 'finish' | 'raw' | 'response-metadata' | 'stream-start';
+  }
+>;
+
+/**
+ * Defines how the provider encodes and decodes an Open Responses extension.
+ *
+ * Tool, item, and event codecs can be registered independently.
+ */
+export interface OpenResponsesExtension {
+  /**
+   * Extension ID in `<implementor>.<extension>` format. For extensions that
+   * encode a provider tool, this is also the AI SDK provider-tool ID.
+   */
+  id: LanguageModelV4ProviderTool['id'];
+
+  /**
+   * Namespaced Open Responses tool type, in `<implementor>:<tool>` format.
+   * Must be provided together with `encodeTool`.
+   */
+  toolType?: OpenResponsesNamespacedType;
+
+  /**
+   * Namespaced item types decoded by this extension. Must be provided together
+   * with `decodeItem`.
+   */
+  itemTypes?: readonly OpenResponsesNamespacedType[];
+
+  /**
+   * Namespaced streaming event types decoded by this extension. Must be
+   * provided together with `decodeEvent`.
+   */
+  eventTypes?: readonly OpenResponsesNamespacedType[];
+
+  /**
+   * Encodes an AI SDK provider tool. Return `undefined` when its arguments
+   * cannot be encoded. The adapter adds `toolType` and omits a specific tool
+   * choice that selects the omitted tool.
+   */
+  encodeTool?(options: {
+    name: string;
+    args: Record<string, unknown>;
+  }): MaybePromiseLike<JSONObject | undefined>;
+
+  /**
+   * Encodes a specific `toolChoice`. The adapter adds `toolType`. The default
+   * is an object containing only `toolType`.
+   */
+  encodeToolChoice?(options: {
+    name: string;
+    args: Record<string, unknown>;
+  }): MaybePromiseLike<JSONObject | undefined>;
+
+  /**
+   * Decodes a completed namespaced item into AI SDK content parts. The adapter
+   * adds a custom replay part containing the original item and reference
+   * metadata to the returned parts.
+   */
+  decodeItem?(options: {
+    item: OpenResponsesExtensionItem;
+    mode: 'generate' | 'stream';
+  }): MaybePromiseLike<OpenResponsesExtensionContentPart[] | undefined>;
+
+  /**
+   * Encodes an AI SDK history part when no original wire item is available.
+   * Every returned item must use one of `itemTypes`.
+   */
+  encodeInputItem?(options: {
+    part: OpenResponsesExtensionInputPart;
+    tool: LanguageModelV4ProviderTool;
+  }): MaybePromiseLike<
+    OpenResponsesExtensionItem | OpenResponsesExtensionItem[] | undefined
+  >;
+
+  /**
+   * Decodes a namespaced streaming event.
+   *
+   * `state` persists for the lifetime of one response stream.
+   */
+  decodeEvent?(options: {
+    event: OpenResponsesExtensionEvent;
+    state: Map<string, unknown>;
+  }): MaybePromiseLike<OpenResponsesExtensionStreamPart[] | undefined>;
+}
+
+export type OpenResponsesExtensionRegistry = {
+  byEventType: Map<OpenResponsesNamespacedType, OpenResponsesEventExtension>;
+  byExtensionId: Map<LanguageModelV4ProviderTool['id'], OpenResponsesExtension>;
+  byItemType: Map<OpenResponsesNamespacedType, OpenResponsesItemExtension>;
+  byProviderToolId: Map<
+    LanguageModelV4ProviderTool['id'],
+    OpenResponsesToolExtension
+  >;
+  byToolType: Map<OpenResponsesNamespacedType, OpenResponsesToolExtension>;
+};
+
+type OpenResponsesToolExtension = OpenResponsesExtension & {
+  toolType: OpenResponsesNamespacedType;
+  encodeTool: NonNullable<OpenResponsesExtension['encodeTool']>;
+};
+
+type OpenResponsesItemExtension = OpenResponsesExtension & {
+  itemTypes: readonly OpenResponsesNamespacedType[];
+  decodeItem: NonNullable<OpenResponsesExtension['decodeItem']>;
+};
+
+type OpenResponsesEventExtension = OpenResponsesExtension & {
+  eventTypes: readonly OpenResponsesNamespacedType[];
+  decodeEvent: NonNullable<OpenResponsesExtension['decodeEvent']>;
+};
+
+export function createOpenResponsesExtensionRegistry(
+  extensions?: readonly OpenResponsesExtension[],
+): OpenResponsesExtensionRegistry {
+  const registry: OpenResponsesExtensionRegistry = {
+    byEventType: new Map(),
+    byExtensionId: new Map(),
+    byItemType: new Map(),
+    byProviderToolId: new Map(),
+    byToolType: new Map(),
+  };
+
+  for (const extension of extensions ?? []) {
+    const namespaceSeparatorIndex = extension.id.indexOf('.');
+    if (namespaceSeparatorIndex <= 0) {
+      throw new Error(
+        `Open Responses extension ID ${extension.id} must use <implementor>.<extension> format.`,
+      );
+    }
+    const namespace = extension.id.slice(0, namespaceSeparatorIndex);
+
+    registerUnique({
+      map: registry.byExtensionId,
+      key: extension.id,
+      extension,
+      field: 'id',
+    });
+
+    const hasToolType = extension.toolType != null;
+    const hasToolEncoder = extension.encodeTool != null;
+    if (hasToolType !== hasToolEncoder) {
+      throw new Error(
+        `Open Responses extension ${extension.id} must provide toolType and encodeTool together.`,
+      );
+    }
+
+    if (extension.encodeToolChoice != null && !hasToolEncoder) {
+      throw new Error(
+        `Open Responses extension ${extension.id} cannot provide encodeToolChoice without toolType and encodeTool.`,
+      );
+    }
+
+    if (hasToolType && hasToolEncoder) {
+      const toolExtension = extension as OpenResponsesToolExtension;
+      assertNamespacedType({
+        extensionId: extension.id,
+        namespace,
+        type: toolExtension.toolType,
+        field: 'toolType',
+      });
+      registerUnique({
+        map: registry.byProviderToolId,
+        key: extension.id,
+        extension: toolExtension,
+        field: 'provider-tool id',
+      });
+      registerUnique({
+        map: registry.byToolType,
+        key: toolExtension.toolType,
+        extension: toolExtension,
+        field: 'toolType',
+      });
+    }
+
+    const hasItemTypes = extension.itemTypes != null;
+    const hasItemDecoder = extension.decodeItem != null;
+    if (hasItemTypes !== hasItemDecoder) {
+      throw new Error(
+        `Open Responses extension ${extension.id} must provide itemTypes and decodeItem together.`,
+      );
+    }
+
+    if (extension.encodeInputItem != null && !hasItemDecoder) {
+      throw new Error(
+        `Open Responses extension ${extension.id} cannot provide encodeInputItem without itemTypes and decodeItem.`,
+      );
+    }
+
+    if (hasItemTypes && hasItemDecoder) {
+      const itemExtension = extension as OpenResponsesItemExtension;
+      if (itemExtension.itemTypes.length === 0) {
+        throw new Error(
+          `Open Responses extension ${extension.id} must register at least one item type.`,
+        );
+      }
+      for (const itemType of itemExtension.itemTypes) {
+        assertNamespacedType({
+          extensionId: extension.id,
+          namespace,
+          type: itemType,
+          field: 'itemTypes',
+        });
+        registerUnique({
+          map: registry.byItemType,
+          key: itemType,
+          extension: itemExtension,
+          field: 'item type',
+        });
+      }
+    }
+
+    const hasEventTypes = extension.eventTypes != null;
+    const hasEventDecoder = extension.decodeEvent != null;
+    if (hasEventTypes !== hasEventDecoder) {
+      throw new Error(
+        `Open Responses extension ${extension.id} must provide eventTypes and decodeEvent together.`,
+      );
+    }
+
+    if (hasEventTypes && hasEventDecoder) {
+      const eventExtension = extension as OpenResponsesEventExtension;
+      if (eventExtension.eventTypes.length === 0) {
+        throw new Error(
+          `Open Responses extension ${extension.id} must register at least one event type.`,
+        );
+      }
+      for (const eventType of eventExtension.eventTypes) {
+        assertNamespacedType({
+          extensionId: extension.id,
+          namespace,
+          type: eventType,
+          field: 'eventTypes',
+        });
+        registerUnique({
+          map: registry.byEventType,
+          key: eventType,
+          extension: eventExtension,
+          field: 'event type',
+        });
+      }
+    }
+
+    if (!hasToolEncoder && !hasItemDecoder && !hasEventDecoder) {
+      throw new Error(
+        `Open Responses extension ${extension.id} must register a tool, item, or event capability.`,
+      );
+    }
+  }
+
+  return registry;
+}
+
+function assertNamespacedType({
+  extensionId,
+  namespace,
+  type,
+  field,
+}: {
+  extensionId: string;
+  namespace: string;
+  type: string;
+  field: string;
+}) {
+  if (!type.includes(':') || type.slice(0, type.indexOf(':')) !== namespace) {
+    throw new Error(
+      `Open Responses extension ${extensionId} has invalid ${field} value ${type}. Extension wire types must use the ${namespace}: namespace.`,
+    );
+  }
+}
+
+function registerUnique<K, Extension extends OpenResponsesExtension>({
+  map,
+  key,
+  extension,
+  field,
+}: {
+  map: Map<K, Extension>;
+  key: K;
+  extension: Extension;
+  field: string;
+}) {
+  const existing = map.get(key);
+  if (existing != null) {
+    throw new Error(
+      `Open Responses extension ${extension.id} cannot register ${field} ${String(key)} because it is already registered by ${existing.id}.`,
+    );
+  }
+  map.set(key, extension);
+}
+
+export function isOpenResponsesNamespacedType(
+  value: unknown,
+): value is OpenResponsesNamespacedType {
+  return typeof value === 'string' && value.includes(':');
+}
+
+export function isOpenResponsesExtensionRecord(
+  value: unknown,
+): value is OpenResponsesExtensionRecord {
+  return (
+    isOpenResponsesJSONObject(value) &&
+    isOpenResponsesNamespacedType((value as { type?: unknown }).type)
+  );
+}
+
+export function isOpenResponsesJSONObject(value: unknown): value is JSONObject {
+  return (
+    value != null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    Object.getPrototypeOf(value) === Object.prototype &&
+    Object.values(value).every(isOpenResponsesJSONValue)
+  );
+}
+
+export function isOpenResponsesExtensionItem(
+  value: unknown,
+): value is OpenResponsesExtensionItem {
+  return (
+    isOpenResponsesExtensionRecord(value) &&
+    typeof value.id === 'string' &&
+    typeof value.status === 'string'
+  );
+}
+
+export function isOpenResponsesExtensionEvent(
+  value: unknown,
+): value is OpenResponsesExtensionEvent {
+  return (
+    isOpenResponsesExtensionRecord(value) &&
+    typeof value.sequence_number === 'number'
+  );
+}
+
+function isOpenResponsesJSONValue(value: unknown): boolean {
+  if (
+    value == null ||
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  ) {
+    return true;
+  }
+
+  if (Array.isArray(value)) {
+    return value.every(isOpenResponsesJSONValue);
+  }
+
+  return isOpenResponsesJSONObject(value);
+}

package/src/open-responses-provider.ts

@@ -8,6 +8,10 @@ import {
   withUserAgentSuffix,
   type FetchFunction,
 } from '@ai-sdk/provider-utils';
+import {
+  createOpenResponsesExtensionRegistry,
+  type OpenResponsesExtension,
+} from './open-responses-extension';
 import { OpenResponsesLanguageModel } from './responses/open-responses-language-model';
 import { VERSION } from './version';
 
@@ -41,12 +45,22 @@ export interface OpenResponsesProviderSettings {
    * or to provide a custom fetch implementation for e.g. testing.
    */
   fetch?: FetchFunction;
+
+  /**
+   * Codecs for Open Responses extension tools, items, and streaming events.
+   *
+   * @experimental This API may change in a future release.
+   */
+  experimental_extensions?: readonly OpenResponsesExtension[];
 }
 
 export function createOpenResponses(
   options: OpenResponsesProviderSettings,
 ): OpenResponsesProvider {
   const providerName = options.name;
+  const extensionRegistry = createOpenResponsesExtensionRegistry(
+    options.experimental_extensions,
+  );
 
   const getHeaders = () =>
     withUserAgentSuffix(
@@ -69,6 +83,7 @@ export function createOpenResponses(
       url: options.url,
       fetch: options.fetch,
       generateId: () => generateId(),
+      extensionRegistry,
     });
   };