@ai-sdk/open-responses: allow explicit codecs for documented bare extension types

[me2seeks]

Description

@ai-sdk/open-responses@2.0.35 added the experimental extension codec registry from #18899 / #18900. The registry safely solves request encoding, response and event decoding, and history replay for normative namespaced Open Responses extensions.

Some public Responses-compatible implementations expose documented implementation extensions using legacy OpenAI-style bare discriminators instead of <implementor>:<type>. Examples include hosted-search and custom-tool families such as:

• request tools: web_search, custom
• output/input items: web_search_call, custom_tool_call, custom_tool_call_output
• streaming events: response.web_search_call.*, response.custom_tool_call_input.*

These types are not Open Responses core types and should not become portable defaults. However, an application also cannot explicitly register their wire semantics today: OpenResponsesNamespacedType requires ${string}:${string}, and registry validation requires the wire namespace to match the extension ID namespace.

As a result, the safe codec seam exists, but documented Responses-compatible extensions using bare discriminators still require a provider fork or a request/response-mutating fetch wrapper.

Expected behavior

Would you be open to an explicit opt-in mechanism for codecs to register exact bare tool, item, and event discriminators?

The API shape is open, but it should preserve the current safety properties:

1. Registration remains explicit and package-local.
2. Every accepted bare discriminator is exactly allowlisted by a codec.
3. Unknown tool, item, and event types remain unsupported; there is no arbitrary JSON passthrough.
4. Duplicate registrations and ambiguous ownership are rejected.
5. The same codec continues to own request encoding, non-streaming decoding, streaming decoding, and lossless history replay.
6. Namespaced extensions remain the default and retain their current namespace validation.

Possible shapes include an explicit allowBareTypes capability on an extension, separate bareToolType / bareItemTypes / bareEventTypes fields, or another API that makes the non-portable opt-in visible.

Why this is distinct from existing requests

• @ai-sdk/open-responses: support registered namespaced tool and item extensions #18899 / feat(open-responses): support experimental extension codecs #18900 added the codec authority but intentionally constrained it to normative namespaced extensions. This request is a narrow follow-up for explicitly registered legacy implementation extensions.
• Feature Request: Support Upcoming Provider-Defined Tools Instead of Throwing warning unsupported-tool #10771 asks to pass unknown provider-defined tools through to providers. This request does not ask for unknown passthrough: unregistered values must continue to fail closed.
• A dedicated provider remains appropriate when an implementation needs broad provider-specific behavior. This request only concerns implementations that otherwise use the generic Open Responses request, response, streaming, and replay model.

Reproduction

A codec whose provider-tool ID is acme.web_search cannot register the implementation wire type web_search:

const extension: Experimental_OpenResponsesExtension = {
  id: "acme.web_search",
  toolType: "web_search", // rejected by the public type
  itemTypes: ["web_search_call"], // rejected by the public type
  eventTypes: ["response.web_search_call.completed"], // rejected by the public type
  encodeTool: () => ({}),
  decodeItem: () => [],
  decodeEvent: () => [],
};

Casting around the TypeScript constraint still fails registry validation at runtime because each wire type lacks the required acme: namespace.

Non-goals

• Do not classify bare web_search, custom, or related item names as Open Responses core types.
• Do not add vendor/model capability detection to @ai-sdk/open-responses.
• Do not pass through arbitrary unknown JSON.
• Do not weaken validation for existing namespaced registrations.

AI SDK Version

• @ai-sdk/open-responses: 2.0.35
• Related implementation: feat(open-responses): support experimental extension codecs #18900

Code of Conduct

• I agree to follow this project's Code of Conduct

[ai-sdk-factory]

Identify issue type

Identified as Feature
Confidence: High

Rationale

This is an API capability enhancement for legacy bare discriminators, not a failure of documented existing behavior; the current namespaced restriction is acknowledged as intentional.

Evidence

• The current registry intentionally accepts only namespaced extension types and validates their namespace.
• The issue requests a new explicit opt-in API for registering allowlisted bare tool, item, and event discriminators.
• The requested behavior is framed as a narrow expansion while preserving existing validation and fail-closed behavior.

[ai-sdk-factory]

Feature Analysis

Feature is not available.

Feature Description

• Allow an explicitly registered Open Responses extension codec to own exact non-namespaced tool, item, and event discriminators while preserving duplicate rejection, fail-closed handling, request encoding, response and stream decoding, and lossless history replay.
• The public Experimental_OpenResponsesExtension fields toolType, itemTypes, and eventTypes remain typed as ${string}:${string}, and createOpenResponsesExtensionRegistry requires every wire type to use the namespace derived from the extension ID.
• The retained issue-19933-probe.ts produces TS2322 errors for all example bare discriminators and, when type checks are bypassed, createOpenResponses throws that web_search must use the acme: namespace; the focused Open Responses suite passes 102 existing namespaced-codec tests.

AI SDK Fit

• The capability fits the existing experimental, package-local extension registry and provider-adapter architecture because applications would still supply explicit codecs rather than adding non-portable types to AI SDK Core.
• Open Responses requires implementation extensions to use implementor-prefixed types, so namespaced registration should remain the portable default and bare registration should be clearly identified as an explicit compatibility mode for documented implementation supersets.
• Tool, item, and event handling are coverage dimensions of one codec ownership and replay contract; splitting them would create surprising partial support across request, response, streaming, and history paths.

Implications / Considerations

• Production changes appear limited to @ai-sdk/open-responses, primarily its exported experimental extension types, registry validation and indexes, API wire types, language-model dispatch, input conversion, and replay validation; other providers and shared provider abstractions should not require changes.
• The public experimental API needs an explicit bare-type opt-in, such as separate bare discriminator fields or a visible capability flag, without widening existing namespaced fields into an unrestricted string passthrough.
• Registry construction must accept only exact declared values, preserve namespace checks for normal registrations, reject duplicate or ambiguous ownership, and define collision rules for core discriminators and bare names that may become standardized later.
• Request tool and tool-choice encoding, non-streaming item decoding, streaming extension-event dispatch, streamed output-item decoding, encodeInputItem validation, and replay restoration must all recognize the same registered bare values.
• Streaming dispatch must test exact registry ownership before consuming an event; merely broadening the current event predicate to any string discriminator would intercept ordinary core response events.
• No Open Responses specification update is appropriate because the specification requires implementor prefixes, and no stable public API change in the ai or @ai-sdk/provider packages appears necessary; the change can remain additive within the experimental @ai-sdk/open-responses API.
• No direct AI SDK UI or framework type changes are expected because codecs already emit existing language-model content and stream parts, although replay through UI conversions should retain the existing custom carrier and provider metadata behavior.
• Tests should cover TypeScript acceptance, rejection without opt-in, namespace preservation, duplicate and core-type collisions, tool and tool-choice encoding, generate and stream decoding, unknown-value handling, replay and fallback history encoding, callback failures, and both Node and Edge runtimes.
• The Open Responses provider example and documentation should demonstrate a non-portable bare extension and explicitly distinguish it from normative namespaced extensions and from the dedicated OpenAI provider.
• Security and privacy behavior must remain fail-closed: codecs must validate fields beyond the discriminator, unknown JSON must not pass through, and documentation must retain the warning that opaque replay items can enter persisted messages, telemetry, logs, and UI payloads.
• Material design uncertainties are the exact opt-in API shape, the reserved core discriminator set, and how registrations should behave if a currently bare implementation type later becomes part of the Open Responses core specification.

Relevant Documentation

• Open Responses Provider
• Open Responses Specification
• Create a model response

[ai-sdk-factory]

Feature implementation

Created feature implementation and opened PR: #19939

Summary

Added bareToolType, bareItemTypes, and bareEventTypes to the experimental extension API, with exact registry dispatch, core-type collision protection, duplicate rejection, request encoding, response and stream decoding, and history replay support.

Testing

Added runtime and compile-time coverage for bare registration, validation, tool and tool-choice encoding, generation and streaming decoding, unknown-type rejection, and lossless and fallback history replay.

End-to-end Validation

• Added and successfully ran the bare-extension Open Responses example.
• Verified encoded bare tools, decoded calls, and lossless replay through a mocked Responses-compatible endpoint.

Documentation

Updated the Open Responses provider documentation with the bare registration fields, non-portability guidance, validation rules, fail-closed behavior, and a consumer example.

[ai-sdk-factory]

Feature implementation updated

Updated PR: #19939

Update

Refactored the extension API into discriminated namespaced and bare variants. Namespaced callbacks retain namespaced discriminator types, while allowBareTypes: true enables string discriminators and is validated against bare registrations.

Testing

Added compile-time coverage for existing namespaced callback types and runtime coverage for missing or unused bare-type opt-in. Node and Edge suites each passed 113 tests.

Documentation

Updated the provider documentation, runnable example, and changeset to include the explicit allowBareTypes: true compatibility opt-in.

[ai-sdk-factory]

Feature implementation updated

Updated PR: #19939

Update

Restored Experimental_OpenResponsesExtension as the extendable namespaced interface and introduced Experimental_OpenResponsesBareExtension for explicitly opted-in bare registrations. Provider settings and internal registries accept both shapes without changing runtime dispatch behavior.

Testing

Added compile-time regression coverage for interfaces extending and classes implementing Experimental_OpenResponsesExtension. The focused Node and Edge suites each passed all 113 tests.

Documentation

Updated the provider documentation and runnable example to use Experimental_OpenResponsesBareExtension for non-portable bare codecs and clarified that Experimental_OpenResponsesExtension remains the namespaced interface.