[JS] OpenAI Responses API support in @genkit-ai/compat-oai (tracking)

[cabljac]

Tracking issue for Responses API support in @genkit-ai/compat-oai. Follows the direction discussed in #5236 (see RFC discussion there; #5345 tracks the Go side).

Approach

Per-model routing inside the existing openAI() plugin - one namespace, no sibling plugin:

• Responses-only models (gpt-5-pro, gpt-5-codex, o1-pro, o3-pro, ...) register on /v1/responses. They are unreachable via compat-oai today, so this is purely additive.
• Dual-transport models opt in explicitly: openAI.responsesModel('gpt-5'). Existing model references are unchanged - same wire protocol, same raw shape, same config.
• Default behavior is stateless: store: false pinned, encrypted reasoning items round-tripped via part metadata (include: ['reasoning.encrypted_content']), with previousResponseId + store exposed as opt-in config for server-side threading.
• Built-in tools (web_search_preview, file_search, code_interpreter) go through the existing config.tools passthrough - no new wrapper fields. Citations surface raw as metadata.annotations on text parts, matching the google-genai Interactions handling.

Deferred, out of scope here: flipping the default transport for gpt-5*/o3/o4-mini (breaking, needs its own proposal), and deep-research / computer-use models (long-running, need background-model actions; background mode also requires store: true).

Example

// After #6003 (PR #6006): Responses-only models work by name
await ai.generate({ model: openAI.model('gpt-5-pro'), prompt });

// After #6005: opt a dual-transport model onto Responses explicitly,
// with built-in tools via the existing config.tools passthrough
await ai.generate({
  model: openAI.responsesModel('gpt-5'),
  prompt: 'What changed in the news today?',
  config: { tools: [{ type: 'web_search_preview' }] },
});

Work items

One PR per item, in order:

• [JS] compat-oai: transport boundary + non-streaming Responses runner #6003 transport boundary + non-streaming Responses runner
• [JS] compat-oai: Responses streaming, tool calling, reasoning round-trip #6004 streaming, tool calling, encrypted reasoning round-trip
• [JS] compat-oai: responsesModel() opt-in, discovery, docs #6005 responsesModel() opt-in surface, discovery, docs

[cabljac]

Design notes: Responses API in compat-oai

Context for #6006 and the follow-up slices. Expands on the direction discussed in #5236.

Why per-model routing inside openAI() (not a sibling plugin)

google-genai already routes by model name inside one plugin for the Interactions API (googleai/index.ts dispatching to deep-research.ts / antigravity.ts). A sibling plugin or second namespace doubles what a user has to know and leaves a namespace to deprecate when Chat Completions eventually goes away. One deliberate extension beyond that precedent: google-genai's families are name-prefix-disjoint, OpenAI's are not (gpt-4o vs gpt-5-pro), so the boundary is an explicit hand-curated const (RESPONSES_ONLY_MODELS) from which both the runtime predicate and the type union derive, rather than a name-pattern.

Why opt-in first (no default flip)

Thirteen shipping models (gpt-5*, o3*, o4-mini) work on both transports. Flipping their default breaks six ways, five silently (raw shape, passthrough config 400s, response_format, stream protocol, finishReason mapping) - and compat-oai versions lockstep with genkit core, so there is no major release to stage that through. Phase 1 is therefore purely additive: Responses-only models register there because they have nowhere else to go; a later responsesModel('gpt-5') accessor (the shape proposed in #5236) opts dual-transport models in explicitly. A default flip remains a separate, explicitly breaking proposal with its own preconditions.

Why stateless by default (store: false)

The Responses API defaults to retaining requests/responses server-side (store: true). Pinning store: false keeps this transport's retention posture identical to Chat Completions - turning retention on stays an explicit act. The cost is that reasoning context must be round-tripped client-side (include: ['reasoning.encrypted_content'], carried on part metadata, mirroring how google-genai round-trips thoughtSignature); that lands with the tool-calling slice, and until then requests that would silently degrade are rejected loudly. previousResponseId + store will be exposed as opt-in config for server-side threading, matching previousInteractionId in google-genai.

Why built-in tools go through config.tools (no wrapper fields)

The plugin already merges raw config.tools objects with converted genkit tools on the Chat Completions path; reusing it adds zero new config surface. Wrapper fields (webSearch: true) insulate users from provider renames but cost a translation layer that drifts (see the three spellings of google-search config accumulated in gemini.ts). Citations will surface raw as metadata.annotations on text parts, matching the Interactions API handling.

Deferred

• Default-transport flip for dual-transport models (preconditions: production mileage on this path, the reasoning round-trip shipped, and a release vehicle for a breaking change)
• deep-research / computer-use models: long-running, need background-model actions (as google-genai registers deep-research), and background mode requires store: true
• Streaming event mapping, tool calling, reasoning round-trip: [JS] compat-oai: Responses streaming, tool calling, reasoning round-trip #6004. Opt-in accessor, discovery, docs: [JS] compat-oai: responsesModel() opt-in, discovery, docs #6005.