@molecule/api-ai-openai 1.2.0 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
3
3
  Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
4
4
  Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
5
5
  To change this document, edit the module-level JSDoc in src/index.ts.
6
- Generated: 2026-08-04T01:47:34.951Z
6
+ Generated: 2026-09-24T07:06:51.312Z
7
7
  -->
8
8
 
9
9
  # @molecule/api-ai-openai
@@ -44,6 +44,13 @@ interface OpenaiConfig {
44
44
  baseUrl?: string
45
45
  /** Called on each rate-limited/overloaded upstream response, before any retry sleep. */
46
46
  onRateLimit?: AiRateLimitCallback
47
+ /**
48
+ * Which OpenAI endpoint to call. Defaults to `'responses'` (`/v1/responses`)
49
+ * when the base URL is OpenAI's own API, and to `'chat-completions'`
50
+ * (`/v1/chat/completions`) for any other base URL, since OpenAI-compatible
51
+ * servers generally implement only chat/completions.
52
+ */
53
+ api?: OpenaiApi
47
54
  }
48
55
  ```
49
56
 
@@ -60,6 +67,16 @@ interface ProcessEnv {
60
67
  }
61
68
  ```
62
69
 
70
+ ### Types
71
+
72
+ #### `OpenaiApi`
73
+
74
+ The OpenAI endpoint a provider instance calls.
75
+
76
+ ```typescript
77
+ type OpenaiApi = 'responses' | 'chat-completions'
78
+ ```
79
+
63
80
  ### Classes
64
81
 
65
82
  #### `OpenaiAIProvider`
@@ -140,6 +157,16 @@ Peer dependencies:
140
157
 
141
158
  Config: `OPENAI_API_KEY` (SERVER-side only) plus an optional default model id/base URL.
142
159
 
160
+ **Endpoint**: on OpenAI's own API (`https://api.openai.com`, the default) the provider calls
161
+ the Responses API (`/v1/responses`); on any other `baseUrl` it calls `/v1/chat/completions`,
162
+ the endpoint OpenAI-compatible servers (Ollama, LM Studio, gateways) implement. Override
163
+ with `api: 'responses' | 'chat-completions'`. Current OpenAI reasoning models only accept
164
+ function tools together with reasoning on `/v1/responses` (gpt-6-astra rejects every
165
+ tool-carrying request on chat/completions), and only Responses carries OpenAI's server-side
166
+ tools (`serverTools`, e.g. `{ type: 'web_search', name: 'web_search' }`); chat/completions
167
+ ignores `serverTools`. `extraBody` is merged into whichever endpoint's body is sent, so its
168
+ keys must be that endpoint's params (e.g. `reasoning`, not `reasoning_effort`, on Responses).
169
+
143
170
  **Missing `OPENAI_API_KEY` fails fast**: the provider throws naming the exact env var on
144
171
  first use (the exported `provider` is a lazy proxy, so this fires on the first `chat()` call,
145
172
  not at bond/module-load time) — it never silently sends an empty key.
package/dist/index.d.ts CHANGED
@@ -4,6 +4,16 @@
4
4
  * @remarks
5
5
  * Config: `OPENAI_API_KEY` (SERVER-side only) plus an optional default model id/base URL.
6
6
  *
7
+ * **Endpoint**: on OpenAI's own API (`https://api.openai.com`, the default) the provider calls
8
+ * the Responses API (`/v1/responses`); on any other `baseUrl` it calls `/v1/chat/completions`,
9
+ * the endpoint OpenAI-compatible servers (Ollama, LM Studio, gateways) implement. Override
10
+ * with `api: 'responses' | 'chat-completions'`. Current OpenAI reasoning models only accept
11
+ * function tools together with reasoning on `/v1/responses` (gpt-6-astra rejects every
12
+ * tool-carrying request on chat/completions), and only Responses carries OpenAI's server-side
13
+ * tools (`serverTools`, e.g. `{ type: 'web_search', name: 'web_search' }`); chat/completions
14
+ * ignores `serverTools`. `extraBody` is merged into whichever endpoint's body is sent, so its
15
+ * keys must be that endpoint's params (e.g. `reasoning`, not `reasoning_effort`, on Responses).
16
+ *
7
17
  * **Missing `OPENAI_API_KEY` fails fast**: the provider throws naming the exact env var on
8
18
  * first use (the exported `provider` is a lazy proxy, so this fires on the first `chat()` call,
9
19
  * not at bond/module-load time) — it never silently sends an empty key.
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,cAAc,oBAAoB,CAAA;AAClC,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAChE,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAE1B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAMlD,mCAAmC;AACnC,eAAO,MAAM,QAAQ,EAAE,UAUrB,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,cAAc,oBAAoB,CAAA;AAClC,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAChE,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAE1B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAMlD,mCAAmC;AACnC,eAAO,MAAM,QAAQ,EAAE,UAUrB,CAAA"}
package/dist/index.js CHANGED
@@ -4,6 +4,16 @@
4
4
  * @remarks
5
5
  * Config: `OPENAI_API_KEY` (SERVER-side only) plus an optional default model id/base URL.
6
6
  *
7
+ * **Endpoint**: on OpenAI's own API (`https://api.openai.com`, the default) the provider calls
8
+ * the Responses API (`/v1/responses`); on any other `baseUrl` it calls `/v1/chat/completions`,
9
+ * the endpoint OpenAI-compatible servers (Ollama, LM Studio, gateways) implement. Override
10
+ * with `api: 'responses' | 'chat-completions'`. Current OpenAI reasoning models only accept
11
+ * function tools together with reasoning on `/v1/responses` (gpt-6-astra rejects every
12
+ * tool-carrying request on chat/completions), and only Responses carries OpenAI's server-side
13
+ * tools (`serverTools`, e.g. `{ type: 'web_search', name: 'web_search' }`); chat/completions
14
+ * ignores `serverTools`. `extraBody` is merged into whichever endpoint's body is sent, so its
15
+ * keys must be that endpoint's params (e.g. `reasoning`, not `reasoning_effort`, on Responses).
16
+ *
7
17
  * **Missing `OPENAI_API_KEY` fails fast**: the provider throws naming the exact env var on
8
18
  * first use (the exported `provider` is a lazy proxy, so this fires on the first `chat()` call,
9
19
  * not at bond/module-load time) — it never silently sends an empty key.
@@ -1,9 +1,10 @@
1
1
  /**
2
2
  * OpenAI implementation of AIProvider.
3
3
  *
4
- * Uses the OpenAI HTTP API (`/v1/chat/completions`) for streaming chat
5
- * completions. Mirrors the shape of `@molecule/api-ai-anthropic` so the
6
- * same handler code can dispatch to either provider.
4
+ * Calls OpenAI's Responses API (`/v1/responses`, see `responses.ts`) on
5
+ * OpenAI's own endpoint, and `/v1/chat/completions` on any other base URL
6
+ * (OpenAI-compatible servers). Mirrors the shape of `@molecule/api-ai-anthropic`
7
+ * so the same handler code can dispatch to either provider.
7
8
  *
8
9
  * @module
9
10
  */
@@ -20,7 +21,18 @@ export declare class OpenaiAIProvider implements AIProvider {
20
21
  private maxTokens;
21
22
  private baseUrl;
22
23
  private onRateLimit?;
24
+ private api;
23
25
  constructor(config?: OpenaiConfig);
26
+ /**
27
+ * Build the request body for `POST /v1/chat/completions`.
28
+ *
29
+ * @param params - The caller's chat parameters.
30
+ * @param model - The resolved model id.
31
+ * @param maxTokens - The resolved output-token limit.
32
+ * @param useStream - Whether to request an SSE stream.
33
+ * @returns The JSON request body.
34
+ */
35
+ private buildChatCompletionsBody;
24
36
  /**
25
37
  * Send a chat request and yield streamed `ChatEvent`s.
26
38
  *
@@ -1 +1 @@
1
- {"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,cAAc,CAAA;AAErB,OAAO,KAAK,EACV,UAAU,EAGV,SAAS,EAET,UAAU,EAEX,MAAM,kBAAkB,CAAA;AAGzB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAc9C;;GAEG;AACH,qBAAa,gBAAiB,YAAW,UAAU;IACjD,QAAQ,CAAC,IAAI,YAAW;IACxB,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,YAAY,CAAQ;IAC5B,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,WAAW,CAAC,CAAqB;gBAE7B,MAAM,GAAE,YAAiB;IAqBrC;;;;;OAKG;IACI,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,CAAC,SAAS,CAAC;IA2KzD;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,cAAc;IA+DtB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IA6BnB,uEAAuE;IACvE,OAAO,CAAC,WAAW;IAWnB;;;;;OAKG;IACH,OAAO,CAAE,yBAAyB;IA8ClC;;;;;OAKG;YACY,sBAAsB;IA4ErC;;;;;;OAMG;IACH,OAAO,CAAE,eAAe;CA0EzB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,UAAU,CAEhE"}
1
+ {"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,cAAc,CAAA;AAErB,OAAO,KAAK,EACV,UAAU,EAGV,SAAS,EAET,UAAU,EAEX,MAAM,kBAAkB,CAAA;AAQzB,OAAO,KAAK,EAAa,YAAY,EAAE,MAAM,YAAY,CAAA;AAkCzD;;GAEG;AACH,qBAAa,gBAAiB,YAAW,UAAU;IACjD,QAAQ,CAAC,IAAI,YAAW;IACxB,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,YAAY,CAAQ;IAC5B,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,WAAW,CAAC,CAAqB;IACzC,OAAO,CAAC,GAAG,CAAW;gBAEV,MAAM,GAAE,YAAiB;IAsBrC;;;;;;;;OAQG;IACH,OAAO,CAAC,wBAAwB;IAgEhC;;;;;OAKG;IACI,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,CAAC,SAAS,CAAC;IAyHzD;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,cAAc;IA+DtB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IA6BnB,uEAAuE;IACvE,OAAO,CAAC,WAAW;IAWnB;;;;;OAKG;IACH,OAAO,CAAE,yBAAyB;IA8ClC;;;;;OAKG;YACY,sBAAsB;IA4ErC;;;;;;OAMG;IACH,OAAO,CAAE,eAAe;CAqEzB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,UAAU,CAEhE"}
package/dist/provider.js CHANGED
@@ -1,9 +1,10 @@
1
1
  /**
2
2
  * OpenAI implementation of AIProvider.
3
3
  *
4
- * Uses the OpenAI HTTP API (`/v1/chat/completions`) for streaming chat
5
- * completions. Mirrors the shape of `@molecule/api-ai-anthropic` so the
6
- * same handler code can dispatch to either provider.
4
+ * Calls OpenAI's Responses API (`/v1/responses`, see `responses.ts`) on
5
+ * OpenAI's own endpoint, and `/v1/chat/completions` on any other base URL
6
+ * (OpenAI-compatible servers). Mirrors the shape of `@molecule/api-ai-anthropic`
7
+ * so the same handler code can dispatch to either provider.
7
8
  *
8
9
  * @module
9
10
  */
@@ -12,7 +13,27 @@
12
13
  // (not through the package barrel).
13
14
  import './secrets.js';
14
15
  import { getLogger } from '@molecule/api-bond';
16
+ import { buildResponsesBody, parseResponsesNonStreaming, parseResponsesStream, } from './responses.js';
17
+ import { streamErrorEvent } from './utilities.js';
15
18
  const logger = getLogger();
19
+ /** OpenAI's own API host — the only one assumed to serve `/v1/responses`. */
20
+ const OPENAI_API_HOST = 'api.openai.com';
21
+ /**
22
+ * Pick the default endpoint for a base URL: Responses for OpenAI's own API,
23
+ * chat/completions for anything else.
24
+ *
25
+ * @param baseUrl - The configured base URL.
26
+ * @returns The endpoint to use.
27
+ */
28
+ function defaultApiFor(baseUrl) {
29
+ try {
30
+ return new URL(baseUrl).host === OPENAI_API_HOST ? 'responses' : 'chat-completions';
31
+ }
32
+ catch (_error) {
33
+ // An unparseable base URL is not OpenAI's; the request itself will report it.
34
+ return 'chat-completions';
35
+ }
36
+ }
16
37
  /**
17
38
  * OpenAI Chat Completions provider implementing the `AIProvider` interface.
18
39
  */
@@ -23,12 +44,14 @@ export class OpenaiAIProvider {
23
44
  maxTokens;
24
45
  baseUrl;
25
46
  onRateLimit;
47
+ api;
26
48
  constructor(config = {}) {
27
49
  this.apiKey = config.apiKey ?? process.env.OPENAI_API_KEY ?? '';
28
50
  this.defaultModel = config.defaultModel ?? 'gpt-6-luna';
29
51
  this.maxTokens = config.maxTokens ?? 4096;
30
52
  this.baseUrl = config.baseUrl ?? process.env.OPENAI_BASE_URL ?? 'https://api.openai.com';
31
53
  this.onRateLimit = config.onRateLimit;
54
+ this.api = config.api ?? defaultApiFor(this.baseUrl);
32
55
  // Fail fast with an actionable local error rather than a cryptic 401 on the
33
56
  // first request. The default `provider` export constructs lazily on first
34
57
  // use (see index.ts), so this surfaces the moment the provider is actually
@@ -41,14 +64,15 @@ export class OpenaiAIProvider {
41
64
  }
42
65
  }
43
66
  /**
44
- * Send a chat request and yield streamed `ChatEvent`s.
67
+ * Build the request body for `POST /v1/chat/completions`.
45
68
  *
46
- * @param params - Chat parameters.
47
- * @yields {ChatEvent}
69
+ * @param params - The caller's chat parameters.
70
+ * @param model - The resolved model id.
71
+ * @param maxTokens - The resolved output-token limit.
72
+ * @param useStream - Whether to request an SSE stream.
73
+ * @returns The JSON request body.
48
74
  */
49
- async *chat(params) {
50
- const model = params.model ?? this.defaultModel;
51
- const maxTokens = params.maxTokens ?? this.maxTokens;
75
+ buildChatCompletionsBody(params, model, maxTokens, useStream) {
52
76
  const messages = this.formatMessages(params.messages, params.system);
53
77
  const body = {
54
78
  // BYO / provider-native tunables (reasoning_effort, enable_thinking, …).
@@ -98,11 +122,27 @@ export class OpenaiAIProvider {
98
122
  body.tool_choice = { type: 'function', function: { name: params.toolChoice.name } };
99
123
  }
100
124
  }
101
- const useStream = params.stream !== false;
102
125
  if (useStream) {
103
126
  body.stream = true;
104
127
  body.stream_options = { include_usage: true };
105
128
  }
129
+ return body;
130
+ }
131
+ /**
132
+ * Send a chat request and yield streamed `ChatEvent`s.
133
+ *
134
+ * @param params - Chat parameters.
135
+ * @yields {ChatEvent}
136
+ */
137
+ async *chat(params) {
138
+ const model = params.model ?? this.defaultModel;
139
+ const maxTokens = params.maxTokens ?? this.maxTokens;
140
+ const useStream = params.stream !== false;
141
+ const isResponses = this.api === 'responses';
142
+ const body = isResponses
143
+ ? buildResponsesBody(params, model, maxTokens, useStream)
144
+ : this.buildChatCompletionsBody(params, model, maxTokens, useStream);
145
+ const path = isResponses ? '/v1/responses' : '/v1/chat/completions';
106
146
  const headers = {
107
147
  'Content-Type': 'application/json',
108
148
  // Omitted for a keyless custom endpoint (a self-hosted / local server).
@@ -113,7 +153,7 @@ export class OpenaiAIProvider {
113
153
  const MAX_RETRIES = 3;
114
154
  let response = null;
115
155
  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
116
- response = await fetch(`${this.baseUrl}/v1/chat/completions`, {
156
+ response = await fetch(`${this.baseUrl}${path}`, {
117
157
  method: 'POST',
118
158
  headers,
119
159
  body: JSON.stringify(body),
@@ -200,10 +240,10 @@ export class OpenaiAIProvider {
200
240
  }
201
241
  if (!useStream) {
202
242
  const data = (await response.json());
203
- yield* this.parseNonStreamingResponse(data);
243
+ yield* isResponses ? parseResponsesNonStreaming(data) : this.parseNonStreamingResponse(data);
204
244
  return;
205
245
  }
206
- yield* this.parseStreamingResponse(response);
246
+ yield* isResponses ? parseResponsesStream(response) : this.parseStreamingResponse(response);
207
247
  }
208
248
  /**
209
249
  * Convert internal `ChatMessage` objects to the OpenAI message format.
@@ -484,12 +524,7 @@ export class OpenaiAIProvider {
484
524
  code: streamError.code,
485
525
  message: streamError.message,
486
526
  });
487
- const clientMessage = /overload|capacity|503|529/i.test(detail)
488
- ? 'AI service is temporarily overloaded. Please try again in a moment.'
489
- : /rate.?limit|429|quota/i.test(detail)
490
- ? 'AI rate limit exceeded. Please try again shortly.'
491
- : 'AI service error. Please try again.';
492
- yield { type: 'error', message: clientMessage, errorKey: 'ai.error.apiError' };
527
+ yield streamErrorEvent(detail);
493
528
  continue;
494
529
  }
495
530
  const choices = event.choices;
@@ -0,0 +1,88 @@
1
+ /**
2
+ * OpenAI Responses API (`/v1/responses`) wire format: request building and
3
+ * response parsing for {@link OpenaiAIProvider}.
4
+ *
5
+ * Why this transport exists alongside `/v1/chat/completions`: on OpenAI's own
6
+ * API, current reasoning models cannot combine function tools with reasoning on
7
+ * chat/completions. gpt-5.6 / gpt-6-sol / gpt-6-luna return 400 for tools plus
8
+ * any `reasoning_effort` other than `'none'`, and gpt-6-astra has no `'none'`
9
+ * at all, so it cannot serve a tool-carrying request there at all. The same
10
+ * requests return 200 on `/v1/responses`, which also carries OpenAI's
11
+ * server-side tools (`web_search`). Verified live 2026-09-24.
12
+ *
13
+ * Requests are stateless (`store: false`): the full conversation is sent each
14
+ * time, as with chat/completions. Prior tool calls are replayed as
15
+ * `function_call` items WITHOUT an item `id` — an id makes the API look for the
16
+ * stored reasoning item that preceded the call, which a stateless request does
17
+ * not have.
18
+ *
19
+ * @module
20
+ */
21
+ import type { AITool, ChatEvent, ChatMessage, ChatParams, ServerTool, TokenUsage } from '@molecule/api-ai';
22
+ /** Usage object as reported on a Responses API `response`. */
23
+ interface ResponsesUsage {
24
+ input_tokens?: number;
25
+ output_tokens?: number;
26
+ input_tokens_details?: {
27
+ cached_tokens?: number;
28
+ cache_write_tokens?: number;
29
+ };
30
+ }
31
+ /**
32
+ * Build the request body for `POST /v1/responses`.
33
+ *
34
+ * @param params - The caller's chat parameters.
35
+ * @param model - The resolved model id.
36
+ * @param maxTokens - The resolved output-token limit.
37
+ * @param useStream - Whether to request an SSE stream.
38
+ * @returns The JSON request body.
39
+ */
40
+ export declare function buildResponsesBody(params: ChatParams, model: string, maxTokens: number, useStream: boolean): Record<string, unknown>;
41
+ /**
42
+ * Convert `ChatMessage`s to Responses API input items. Text and images become
43
+ * message items; `tool_use` blocks become `function_call` items and
44
+ * `tool_result` blocks `function_call_output` items, in block order.
45
+ *
46
+ * @param messages - The conversation.
47
+ * @returns The `input` array.
48
+ */
49
+ export declare function formatResponsesInput(messages: ChatMessage[]): Array<Record<string, unknown>>;
50
+ /**
51
+ * Convert function tools and provider-native server tools to the Responses
52
+ * API `tools` array.
53
+ *
54
+ * Function tools set `strict: false` explicitly: callers' schemas use optional
55
+ * properties and omit `additionalProperties: false`, which strict mode rejects.
56
+ * Server tools are forwarded as `{ type, ...config }`; the abstract `name`
57
+ * field is dropped because OpenAI's built-in tools are identified by `type`.
58
+ *
59
+ * @param tools - Function tools executed by the caller.
60
+ * @param serverTools - Tools the provider executes (e.g. `{ type: 'web_search' }`).
61
+ * @returns The `tools` array.
62
+ */
63
+ export declare function formatResponsesTools(tools: AITool[], serverTools: ServerTool[]): Array<Record<string, unknown>>;
64
+ /**
65
+ * Normalize Responses API usage to `TokenUsage`. `input_tokens` includes the
66
+ * cached and cache-written tokens; they are reported separately (Anthropic
67
+ * semantics) so consumers do not double-count them.
68
+ *
69
+ * @param usage - The `usage` object of a completed response.
70
+ * @returns The normalized usage.
71
+ */
72
+ export declare function responsesUsage(usage: ResponsesUsage | undefined | null, webSearchCalls?: number): TokenUsage;
73
+ /**
74
+ * Parse a non-streaming `/v1/responses` result.
75
+ *
76
+ * @param data - The parsed JSON response body.
77
+ * @yields {ChatEvent} Text, tool-use, and done events.
78
+ */
79
+ export declare function parseResponsesNonStreaming(data: Record<string, unknown>): Iterable<ChatEvent>;
80
+ /**
81
+ * Parse a streaming SSE response from `/v1/responses`.
82
+ *
83
+ * @param response - The fetch Response whose body is an SSE stream.
84
+ * @yields {ChatEvent} Text, tool-call progress, tool-use, keep-alive, and done events.
85
+ */
86
+ export declare function parseResponsesStream(response: Response): AsyncIterable<ChatEvent>;
87
+ export {};
88
+ //# sourceMappingURL=responses.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../src/responses.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EACV,MAAM,EACN,SAAS,EACT,WAAW,EACX,UAAU,EAEV,UAAU,EACV,UAAU,EACX,MAAM,kBAAkB,CAAA;AAOzB,8DAA8D;AAC9D,UAAU,cAAc;IACtB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,oBAAoB,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAC/E;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,OAAO,GACjB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA2BzB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA+C5F;AA6BD;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EAAE,EACf,WAAW,EAAE,UAAU,EAAE,GACxB,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAWhC;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,cAAc,GAAG,SAAS,GAAG,IAAI,EACxC,cAAc,SAAI,GACjB,UAAU,CAUZ;AAiBD;;;;;GAKG;AACH,wBAAiB,0BAA0B,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,QAAQ,CAAC,SAAS,CAAC,CAwB9F;AAED;;;;;GAKG;AACH,wBAAuB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,GAAG,aAAa,CAAC,SAAS,CAAC,CAwJxF"}
@@ -0,0 +1,398 @@
1
+ /**
2
+ * OpenAI Responses API (`/v1/responses`) wire format: request building and
3
+ * response parsing for {@link OpenaiAIProvider}.
4
+ *
5
+ * Why this transport exists alongside `/v1/chat/completions`: on OpenAI's own
6
+ * API, current reasoning models cannot combine function tools with reasoning on
7
+ * chat/completions. gpt-5.6 / gpt-6-sol / gpt-6-luna return 400 for tools plus
8
+ * any `reasoning_effort` other than `'none'`, and gpt-6-astra has no `'none'`
9
+ * at all, so it cannot serve a tool-carrying request there at all. The same
10
+ * requests return 200 on `/v1/responses`, which also carries OpenAI's
11
+ * server-side tools (`web_search`). Verified live 2026-09-24.
12
+ *
13
+ * Requests are stateless (`store: false`): the full conversation is sent each
14
+ * time, as with chat/completions. Prior tool calls are replayed as
15
+ * `function_call` items WITHOUT an item `id` — an id makes the API look for the
16
+ * stored reasoning item that preceded the call, which a stateless request does
17
+ * not have.
18
+ *
19
+ * @module
20
+ */
21
+ import { getLogger } from '@molecule/api-bond';
22
+ import { streamErrorEvent } from './utilities.js';
23
+ const logger = getLogger();
24
+ /**
25
+ * Build the request body for `POST /v1/responses`.
26
+ *
27
+ * @param params - The caller's chat parameters.
28
+ * @param model - The resolved model id.
29
+ * @param maxTokens - The resolved output-token limit.
30
+ * @param useStream - Whether to request an SSE stream.
31
+ * @returns The JSON request body.
32
+ */
33
+ export function buildResponsesBody(params, model, maxTokens, useStream) {
34
+ const body = {
35
+ // Provider-native tunables first, so the structural fields below win.
36
+ // On OpenAI's own endpoint these are Responses-API params (e.g. `text`,
37
+ // `truncation`), not chat/completions ones.
38
+ ...(params.extraBody ?? {}),
39
+ ...(params.endUserId ? { safety_identifier: params.endUserId } : {}),
40
+ model,
41
+ input: formatResponsesInput(params.messages),
42
+ max_output_tokens: maxTokens,
43
+ store: false,
44
+ };
45
+ if (params.system)
46
+ body.instructions = params.system;
47
+ if (params.temperature !== undefined)
48
+ body.temperature = params.temperature;
49
+ if (params.thinking?.effort)
50
+ body.reasoning = { effort: params.thinking.effort };
51
+ const tools = formatResponsesTools(params.tools ?? [], params.serverTools ?? []);
52
+ if (tools.length > 0) {
53
+ body.tools = tools;
54
+ if (params.toolChoice === 'required') {
55
+ body.tool_choice = 'required';
56
+ }
57
+ else if (typeof params.toolChoice === 'object' && params.toolChoice?.type === 'tool') {
58
+ body.tool_choice = { type: 'function', name: params.toolChoice.name };
59
+ }
60
+ }
61
+ if (useStream)
62
+ body.stream = true;
63
+ return body;
64
+ }
65
+ /**
66
+ * Convert `ChatMessage`s to Responses API input items. Text and images become
67
+ * message items; `tool_use` blocks become `function_call` items and
68
+ * `tool_result` blocks `function_call_output` items, in block order.
69
+ *
70
+ * @param messages - The conversation.
71
+ * @returns The `input` array.
72
+ */
73
+ export function formatResponsesInput(messages) {
74
+ const out = [];
75
+ for (const m of messages) {
76
+ if (m.role === 'system') {
77
+ out.push({ role: 'system', content: typeof m.content === 'string' ? m.content : '' });
78
+ continue;
79
+ }
80
+ if (typeof m.content === 'string') {
81
+ out.push({ role: m.role, content: m.content });
82
+ continue;
83
+ }
84
+ // Consecutive content parts collect into one message item; a tool block
85
+ // flushes them first so the item order matches the block order.
86
+ let parts = [];
87
+ const flush = () => {
88
+ if (parts.length === 0)
89
+ return;
90
+ out.push({ role: m.role, content: parts });
91
+ parts = [];
92
+ };
93
+ for (const block of m.content) {
94
+ switch (block.type) {
95
+ case 'tool_use':
96
+ flush();
97
+ out.push({
98
+ type: 'function_call',
99
+ call_id: block.id,
100
+ name: block.name,
101
+ arguments: JSON.stringify(block.input ?? {}),
102
+ });
103
+ break;
104
+ case 'tool_result':
105
+ flush();
106
+ out.push({
107
+ type: 'function_call_output',
108
+ call_id: block.tool_use_id,
109
+ output: typeof block.content === 'string' ? block.content : JSON.stringify(block.content),
110
+ });
111
+ break;
112
+ default:
113
+ parts.push(formatResponsesPart(block, m.role));
114
+ }
115
+ }
116
+ flush();
117
+ }
118
+ return out;
119
+ }
120
+ /**
121
+ * Map a content-part block to a Responses API content part. Assistant text is
122
+ * `output_text`; everything the user sends is an `input_*` part.
123
+ *
124
+ * @param block - A text/image/document/audio/video block.
125
+ * @param role - The role of the message the block belongs to.
126
+ * @returns The content part.
127
+ */
128
+ function formatResponsesPart(block, role) {
129
+ const textType = role === 'assistant' ? 'output_text' : 'input_text';
130
+ switch (block.type) {
131
+ case 'text':
132
+ return { type: textType, text: block.text };
133
+ case 'image':
134
+ return { type: 'input_image', image_url: `data:${block.mediaType};base64,${block.data}` };
135
+ case 'document':
136
+ case 'audio':
137
+ case 'video':
138
+ return {
139
+ type: textType,
140
+ text: `[${block.type[0].toUpperCase()}${block.type.slice(1)} attachment (${block.mediaType}) — not supported by this provider]`,
141
+ };
142
+ default:
143
+ return { type: textType, text: '' };
144
+ }
145
+ }
146
+ /**
147
+ * Convert function tools and provider-native server tools to the Responses
148
+ * API `tools` array.
149
+ *
150
+ * Function tools set `strict: false` explicitly: callers' schemas use optional
151
+ * properties and omit `additionalProperties: false`, which strict mode rejects.
152
+ * Server tools are forwarded as `{ type, ...config }`; the abstract `name`
153
+ * field is dropped because OpenAI's built-in tools are identified by `type`.
154
+ *
155
+ * @param tools - Function tools executed by the caller.
156
+ * @param serverTools - Tools the provider executes (e.g. `{ type: 'web_search' }`).
157
+ * @returns The `tools` array.
158
+ */
159
+ export function formatResponsesTools(tools, serverTools) {
160
+ return [
161
+ ...tools.map((tool) => ({
162
+ type: 'function',
163
+ name: tool.name,
164
+ description: tool.description,
165
+ parameters: tool.parameters,
166
+ strict: false,
167
+ })),
168
+ ...serverTools.map(({ name: _name, ...config }) => config),
169
+ ];
170
+ }
171
+ /**
172
+ * Normalize Responses API usage to `TokenUsage`. `input_tokens` includes the
173
+ * cached and cache-written tokens; they are reported separately (Anthropic
174
+ * semantics) so consumers do not double-count them.
175
+ *
176
+ * @param usage - The `usage` object of a completed response.
177
+ * @returns The normalized usage.
178
+ */
179
+ export function responsesUsage(usage, webSearchCalls = 0) {
180
+ const cached = usage?.input_tokens_details?.cached_tokens ?? 0;
181
+ const written = usage?.input_tokens_details?.cache_write_tokens ?? 0;
182
+ return {
183
+ inputTokens: Math.max(0, (usage?.input_tokens ?? 0) - cached - written),
184
+ outputTokens: usage?.output_tokens ?? 0,
185
+ cacheReadInputTokens: cached,
186
+ ...(written > 0 ? { cacheCreationInputTokens: written } : {}),
187
+ ...(webSearchCalls > 0 ? { webSearchRequests: webSearchCalls } : {}),
188
+ };
189
+ }
190
+ /**
191
+ * Parse a function-call argument string, falling back to `{}` when malformed.
192
+ *
193
+ * @param args - The JSON argument string.
194
+ * @returns The parsed input.
195
+ */
196
+ function parseArgs(args) {
197
+ try {
198
+ return args ? JSON.parse(args) : {};
199
+ }
200
+ catch (_error) {
201
+ // Best-effort: malformed tool-call arguments are unusable; fall back to empty object.
202
+ return {};
203
+ }
204
+ }
205
+ /**
206
+ * Parse a non-streaming `/v1/responses` result.
207
+ *
208
+ * @param data - The parsed JSON response body.
209
+ * @yields {ChatEvent} Text, tool-use, and done events.
210
+ */
211
+ export function* parseResponsesNonStreaming(data) {
212
+ const output = data.output ?? [];
213
+ let webSearchCalls = 0;
214
+ for (const item of output) {
215
+ if (item.type === 'web_search_call')
216
+ webSearchCalls++;
217
+ if (item.type === 'message') {
218
+ for (const part of item.content ?? []) {
219
+ if (part.type === 'output_text' && typeof part.text === 'string' && part.text.length > 0) {
220
+ yield { type: 'text', content: part.text };
221
+ }
222
+ }
223
+ }
224
+ else if (item.type === 'function_call') {
225
+ yield {
226
+ type: 'tool_use',
227
+ id: String(item.call_id ?? ''),
228
+ name: String(item.name ?? ''),
229
+ input: parseArgs(item.arguments),
230
+ };
231
+ }
232
+ }
233
+ yield {
234
+ type: 'done',
235
+ usage: responsesUsage(data.usage, webSearchCalls),
236
+ };
237
+ }
238
+ /**
239
+ * Parse a streaming SSE response from `/v1/responses`.
240
+ *
241
+ * @param response - The fetch Response whose body is an SSE stream.
242
+ * @yields {ChatEvent} Text, tool-call progress, tool-use, keep-alive, and done events.
243
+ */
244
+ export async function* parseResponsesStream(response) {
245
+ const reader = response.body?.getReader();
246
+ if (!reader) {
247
+ yield {
248
+ type: 'error',
249
+ message: 'No response body from OpenAI.',
250
+ errorKey: 'ai.error.noResponseBody',
251
+ };
252
+ return;
253
+ }
254
+ const decoder = new TextDecoder();
255
+ let buffer = '';
256
+ let usage = null;
257
+ /** Function calls in progress, keyed by output item id. */
258
+ const calls = new Map();
259
+ /**
260
+ * `web_search_call` items started — OpenAI bills each one. Counted when the
261
+ * call starts so a stream cut mid-search still meters it.
262
+ */
263
+ let webSearchCalls = 0;
264
+ /**
265
+ * Turn one SSE data payload into zero or more ChatEvents.
266
+ *
267
+ * @param json - The `data:` payload.
268
+ * @yields {ChatEvent}
269
+ */
270
+ function* handle(json) {
271
+ let event;
272
+ try {
273
+ event = JSON.parse(json);
274
+ }
275
+ catch (error) {
276
+ logger.debug('Skipping malformed OpenAI Responses SSE JSON line', { json, error });
277
+ return;
278
+ }
279
+ const item = event.item;
280
+ switch (event.type) {
281
+ case 'response.output_text.delta':
282
+ if (typeof event.delta === 'string' && event.delta.length > 0) {
283
+ yield { type: 'text', content: event.delta };
284
+ }
285
+ return;
286
+ case 'response.output_item.added':
287
+ if (item?.type === 'web_search_call') {
288
+ webSearchCalls++;
289
+ // Metering snapshot: the search is billed even if the turn is cut.
290
+ yield {
291
+ type: 'usage',
292
+ usage: { inputTokens: 0, outputTokens: 0, webSearchRequests: webSearchCalls },
293
+ };
294
+ }
295
+ else if (item?.type === 'function_call') {
296
+ const callId = String(item.call_id ?? '');
297
+ const name = String(item.name ?? '');
298
+ calls.set(String(item.id ?? ''), { callId, name });
299
+ yield { type: 'tool_use_start', id: callId, name };
300
+ }
301
+ return;
302
+ case 'response.function_call_arguments.delta': {
303
+ const call = calls.get(String(event.item_id ?? ''));
304
+ if (call && typeof event.delta === 'string') {
305
+ yield {
306
+ type: 'tool_input_delta',
307
+ id: call.callId,
308
+ chars: event.delta.length,
309
+ text: event.delta,
310
+ };
311
+ }
312
+ return;
313
+ }
314
+ case 'response.output_item.done':
315
+ if (item?.type === 'function_call') {
316
+ calls.delete(String(item.id ?? ''));
317
+ yield {
318
+ type: 'tool_use',
319
+ id: String(item.call_id ?? ''),
320
+ name: String(item.name ?? ''),
321
+ input: parseArgs(item.arguments),
322
+ };
323
+ }
324
+ return;
325
+ case 'response.completed':
326
+ case 'response.incomplete': {
327
+ const res = event.response;
328
+ usage = responsesUsage(res?.usage, webSearchCalls);
329
+ if (event.type === 'response.incomplete') {
330
+ logger.warn('OpenAI response incomplete', { details: res?.incomplete_details });
331
+ }
332
+ return;
333
+ }
334
+ case 'response.failed':
335
+ case 'error': {
336
+ const err = (event.type === 'error'
337
+ ? event
338
+ : (event.response?.error ?? {}));
339
+ logger.error('OpenAI Responses streaming error event', {
340
+ type: err.type,
341
+ code: err.code,
342
+ message: err.message,
343
+ });
344
+ yield streamErrorEvent(`${err.code ?? err.type ?? ''} ${err.message ?? ''}`);
345
+ return;
346
+ }
347
+ default:
348
+ // Lifecycle, reasoning, and server-tool progress events carry nothing
349
+ // to forward; the caller yields keep_alive for them.
350
+ }
351
+ }
352
+ try {
353
+ while (true) {
354
+ const { done, value } = await reader.read();
355
+ if (done)
356
+ break;
357
+ buffer += decoder.decode(value, { stream: true });
358
+ const lines = buffer.split('\n');
359
+ buffer = lines.pop() ?? '';
360
+ let yielded = false;
361
+ for (const line of lines) {
362
+ if (!line.startsWith('data: '))
363
+ continue;
364
+ for (const event of handle(line.slice(6).trim())) {
365
+ yielded = true;
366
+ yield event;
367
+ // A truncated turn must not fall through to a successful `done`.
368
+ if (event.type === 'error')
369
+ return;
370
+ }
371
+ }
372
+ if (!yielded)
373
+ yield { type: 'keep_alive' };
374
+ }
375
+ if (buffer.startsWith('data: ')) {
376
+ for (const event of handle(buffer.slice(6).trim())) {
377
+ yield event;
378
+ if (event.type === 'error')
379
+ return;
380
+ }
381
+ }
382
+ }
383
+ finally {
384
+ reader.releaseLock();
385
+ }
386
+ if (!usage) {
387
+ // The stream ended without response.completed / response.incomplete: the
388
+ // connection was cut, so the turn is truncated, not finished.
389
+ logger.error('OpenAI Responses stream ended without a terminal event');
390
+ yield {
391
+ type: 'error',
392
+ message: 'AI service error. Please try again.',
393
+ errorKey: 'ai.error.apiError',
394
+ };
395
+ return;
396
+ }
397
+ yield { type: 'done', usage };
398
+ }
package/dist/types.d.ts CHANGED
@@ -16,7 +16,16 @@ export interface OpenaiConfig {
16
16
  baseUrl?: string;
17
17
  /** Called on each rate-limited/overloaded upstream response, before any retry sleep. */
18
18
  onRateLimit?: AiRateLimitCallback;
19
+ /**
20
+ * Which OpenAI endpoint to call. Defaults to `'responses'` (`/v1/responses`)
21
+ * when the base URL is OpenAI's own API, and to `'chat-completions'`
22
+ * (`/v1/chat/completions`) for any other base URL, since OpenAI-compatible
23
+ * servers generally implement only chat/completions.
24
+ */
25
+ api?: OpenaiApi;
19
26
  }
27
+ /** The OpenAI endpoint a provider instance calls. */
28
+ export type OpenaiApi = 'responses' | 'chat-completions';
20
29
  /** Environment variables read by this provider. */
21
30
  export interface ProcessEnv {
22
31
  /** OpenAI API key (required unless `config.apiKey` is passed). */
@@ -1 +1 @@
1
- {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAE3D,qCAAqC;AACrC,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,wFAAwF;IACxF,WAAW,CAAC,EAAE,mBAAmB,CAAA;CAClC;AAED,mDAAmD;AACnD,MAAM,WAAW,UAAU;IACzB,kEAAkE;IAClE,cAAc,EAAE,MAAM,CAAA;IACtB,yGAAyG;IACzG,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB"}
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAE3D,qCAAqC;AACrC,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,wFAAwF;IACxF,WAAW,CAAC,EAAE,mBAAmB,CAAA;IACjC;;;;;OAKG;IACH,GAAG,CAAC,EAAE,SAAS,CAAA;CAChB;AAED,qDAAqD;AACrD,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,kBAAkB,CAAA;AAExD,mDAAmD;AACnD,MAAM,WAAW,UAAU;IACzB,kEAAkE;IAClE,cAAc,EAAE,MAAM,CAAA;IACtB,yGAAyG;IACzG,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB"}
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Helpers shared by the chat/completions and Responses transports.
3
+ *
4
+ * @module
5
+ */
6
+ import type { ChatEvent } from '@molecule/api-ai';
7
+ /**
8
+ * Map a mid-stream error's code/type/message to the client-facing `error`
9
+ * event. Overload and rate-limit errors get their own messages so the
10
+ * consumer's retry recovery can tell them apart from other failures.
11
+ *
12
+ * @param detail - The upstream error's code/type and message, joined.
13
+ * @returns The `error` ChatEvent to yield.
14
+ */
15
+ export declare function streamErrorEvent(detail: string): ChatEvent;
16
+ //# sourceMappingURL=utilities.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAEjD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAO1D"}
@@ -0,0 +1,21 @@
1
+ /**
2
+ * Helpers shared by the chat/completions and Responses transports.
3
+ *
4
+ * @module
5
+ */
6
+ /**
7
+ * Map a mid-stream error's code/type/message to the client-facing `error`
8
+ * event. Overload and rate-limit errors get their own messages so the
9
+ * consumer's retry recovery can tell them apart from other failures.
10
+ *
11
+ * @param detail - The upstream error's code/type and message, joined.
12
+ * @returns The `error` ChatEvent to yield.
13
+ */
14
+ export function streamErrorEvent(detail) {
15
+ const message = /overload|capacity|503|529/i.test(detail)
16
+ ? 'AI service is temporarily overloaded. Please try again in a moment.'
17
+ : /rate.?limit|429|quota/i.test(detail)
18
+ ? 'AI rate limit exceeded. Please try again shortly.'
19
+ : 'AI service error. Please try again.';
20
+ return { type: 'error', message, errorKey: 'ai.error.apiError' };
21
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/api-ai-openai",
3
- "version": "1.2.0",
3
+ "version": "1.4.0",
4
4
  "description": "",
5
5
  "homepage": "https://www.molecule.dev/packages/api-ai-openai",
6
6
  "type": "module",
@@ -33,7 +33,7 @@
33
33
  "directory": "packages/api/bonds/ai/openai"
34
34
  },
35
35
  "devDependencies": {
36
- "@molecule/api-ai": "1.2.1",
36
+ "@molecule/api-ai": "1.3.0",
37
37
  "@molecule/api-bond": "1.0.2",
38
38
  "@types/node": "26.1.2",
39
39
  "typescript": "6.0.3",