@molecule/api-ai-openai 1.4.3 → 1.4.4

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/LICENSE CHANGED
@@ -1,3 +1,4 @@
1
+
1
2
  Apache License
2
3
  Version 2.0, January 2004
3
4
  http://www.apache.org/licenses/
@@ -34,21 +35,33 @@
34
35
 
35
36
  "Work" shall mean the work of authorship, whether in Source or
36
37
  Object form, made available under the License, as indicated by a
37
- copyright notice that is included in or attached to the work.
38
+ copyright notice that is included in or attached to the work
39
+ (an example is provided in the Appendix below).
38
40
 
39
41
  "Derivative Works" shall mean any work, whether in Source or Object
40
42
  form, that is based on (or derived from) the Work and for which the
41
43
  editorial revisions, annotations, elaborations, or other modifications
42
- represent, as a whole, an original work of authorship.
43
-
44
- "Contribution" shall mean any work of authorship, including the
45
- original version of the Work and any modifications or additions
46
- to that Work, that is intentionally submitted to the Licensor for
47
- inclusion in the Work by the copyright owner or by an individual or
48
- Legal Entity authorized to submit on behalf of the copyright owner.
44
+ represent, as a whole, an original work of authorship. For the purposes
45
+ of this License, Derivative Works shall not include works that remain
46
+ separable from, or merely link (or bind by name) to the interfaces of,
47
+ the Work and Derivative Works thereof.
48
+
49
+ "Contribution" shall mean any work of authorship, including
50
+ the original version of the Work and any modifications or additions
51
+ to that Work or Derivative Works thereof, that is intentionally
52
+ submitted to Licensor for inclusion in the Work by the copyright owner
53
+ or by an individual or Legal Entity authorized to submit on behalf of
54
+ the copyright owner. For the purposes of this definition, "submitted"
55
+ means any form of electronic, verbal, or written communication sent
56
+ to the Licensor or its representatives, including but not limited to
57
+ communication on electronic mailing lists, source code control systems,
58
+ and issue tracking systems that are managed by, or on behalf of, the
59
+ Licensor for the purpose of discussing and improving the Work, but
60
+ excluding communication that is conspicuously marked or otherwise
61
+ designated in writing by the copyright owner as "Not a Contribution."
49
62
 
50
63
  "Contributor" shall mean Licensor and any individual or Legal Entity
51
- on behalf of whom a Contribution has been received by the Licensor and
64
+ on behalf of whom a Contribution has been received by Licensor and
52
65
  subsequently incorporated within the Work.
53
66
 
54
67
  2. Grant of Copyright License. Subject to the terms and conditions of
@@ -61,8 +74,18 @@
61
74
  3. Grant of Patent License. Subject to the terms and conditions of
62
75
  this License, each Contributor hereby grants to You a perpetual,
63
76
  worldwide, non-exclusive, no-charge, royalty-free, irrevocable
64
- patent license to make, have made, use, offer to sell, sell, import,
65
- and otherwise transfer the Work.
77
+ (except as stated in this section) patent license to make, have made,
78
+ use, offer to sell, sell, import, and otherwise transfer the Work,
79
+ where such license applies only to those patent claims licensable
80
+ by such Contributor that are necessarily infringed by their
81
+ Contribution(s) alone or by combination of their Contribution(s)
82
+ with the Work to which such Contribution(s) was submitted. If You
83
+ institute patent litigation against any entity (including a
84
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
85
+ or a Contribution incorporated within the Work constitutes direct
86
+ or contributory patent infringement, then any patent licenses
87
+ granted to You under this License for that Work shall terminate
88
+ as of the date such litigation is filed.
66
89
 
67
90
  4. Redistribution. You may reproduce and distribute copies of the
68
91
  Work or Derivative Works thereof in any medium, with or without
@@ -84,23 +107,87 @@
84
107
  (d) If the Work includes a "NOTICE" text file as part of its
85
108
  distribution, then any Derivative Works that You distribute must
86
109
  include a readable copy of the attribution notices contained
87
- within such NOTICE file.
88
-
89
- 5. Submission of Contributions.
110
+ within such NOTICE file, excluding those notices that do not
111
+ pertain to any part of the Derivative Works, in at least one
112
+ of the following places: within a NOTICE text file distributed
113
+ as part of the Derivative Works; within the Source form or
114
+ documentation, if provided along with the Derivative Works; or,
115
+ within a display generated by the Derivative Works, if and
116
+ wherever such third-party notices normally appear. The contents
117
+ of the NOTICE file are for informational purposes only and
118
+ do not modify the License. You may add Your own attribution
119
+ notices within Derivative Works that You distribute, alongside
120
+ or as an addendum to the NOTICE text from the Work, provided
121
+ that such additional attribution notices cannot be construed
122
+ as modifying the License.
123
+
124
+ You may add Your own copyright statement to Your modifications and
125
+ may provide additional or different license terms and conditions
126
+ for use, reproduction, or distribution of Your modifications, or
127
+ for any such Derivative Works as a whole, provided Your use,
128
+ reproduction, and distribution of the Work otherwise complies with
129
+ the conditions stated in this License.
130
+
131
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
132
+ any Contribution intentionally submitted for inclusion in the Work
133
+ by You to the Licensor shall be under the terms and conditions of
134
+ this License, without any additional terms or conditions.
135
+ Notwithstanding the above, nothing herein shall supersede or modify
136
+ the terms of any separate license agreement you may have executed
137
+ with Licensor regarding such Contributions.
90
138
 
91
139
  6. Trademarks. This License does not grant permission to use the trade
92
- names, trademarks, service marks, or product names of the Licensor.
140
+ names, trademarks, service marks, or product names of the Licensor,
141
+ except as required for reasonable and customary use in describing the
142
+ origin of the Work and reproducing the content of the NOTICE file.
93
143
 
94
144
  7. Disclaimer of Warranty. Unless required by applicable law or
95
- agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
96
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
97
-
98
- 8. Limitation of Liability. In no event and under no legal theory shall
99
- any Contributor be liable to You for damages.
100
-
101
- 9. Accepting Warranty or Additional Liability.
102
-
103
- Copyright 2026 Molecule Dev, Inc.
145
+ agreed to in writing, Licensor provides the Work (and each
146
+ Contributor provides its Contributions) on an "AS IS" BASIS,
147
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148
+ implied, including, without limitation, any warranties or conditions
149
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150
+ PARTICULAR PURPOSE. You are solely responsible for determining the
151
+ appropriateness of using or redistributing the Work and assume any
152
+ risks associated with Your exercise of permissions under this License.
153
+
154
+ 8. Limitation of Liability. In no event and under no legal theory,
155
+ whether in tort (including negligence), contract, or otherwise,
156
+ unless required by applicable law (such as deliberate and grossly
157
+ negligent acts) or agreed to in writing, shall any Contributor be
158
+ liable to You for damages, including any direct, indirect, special,
159
+ incidental, or consequential damages of any character arising as a
160
+ result of this License or out of the use or inability to use the
161
+ Work (including but not limited to damages for loss of goodwill,
162
+ work stoppage, computer failure or malfunction, or any and all
163
+ other commercial damages or losses), even if such Contributor
164
+ has been advised of the possibility of such damages.
165
+
166
+ 9. Accepting Warranty or Additional Liability. While redistributing
167
+ the Work or Derivative Works thereof, You may choose to offer,
168
+ and charge a fee for, acceptance of support, warranty, indemnity,
169
+ or other liability obligations and/or rights consistent with this
170
+ License. However, in accepting such obligations, You may act only
171
+ on Your own behalf and on Your sole responsibility, not on behalf
172
+ of any other Contributor, and only if You agree to indemnify,
173
+ defend, and hold each Contributor harmless for any liability
174
+ incurred by, or claims asserted against, such Contributor by reason
175
+ of your accepting any such warranty or additional liability.
176
+
177
+ END OF TERMS AND CONDITIONS
178
+
179
+ APPENDIX: How to apply the Apache License to your work.
180
+
181
+ To apply the Apache License to your work, attach the following
182
+ boilerplate notice, with the fields enclosed by brackets "[]"
183
+ replaced with your own identifying information. (Don't include
184
+ the brackets!) The text should be enclosed in the appropriate
185
+ comment syntax for the file format. We also recommend that a
186
+ file or class name and description of purpose be included on the
187
+ same "printed page" as the copyright notice for easier
188
+ identification within third-party archives.
189
+
190
+ Copyright [yyyy] [name of copyright owner]
104
191
 
105
192
  Licensed under the Apache License, Version 2.0 (the "License");
106
193
  you may not use this file except in compliance with the License.
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-10-01T18:20:48.517Z
6
+ Generated: 2026-10-16T16:53:56.772Z
7
7
  -->
8
8
 
9
9
  # @molecule/api-ai-openai
@@ -103,6 +103,187 @@ type OpenaiApi = 'responses' | 'chat-completions'
103
103
 
104
104
  OpenAI Chat Completions provider implementing the `AIProvider` interface.
105
105
 
106
+ ```typescript
107
+ class OpenaiAIProvider implements AIProvider {
108
+ readonly name = 'openai'
109
+ private apiKey: string
110
+ private defaultModel: string
111
+ private maxTokens: number
112
+ private baseUrl: string
113
+ private onRateLimit?: AiRateLimitCallback
114
+ private api: OpenaiApi
115
+
116
+ constructor(config: OpenaiConfig = {}) {
117
+ this.apiKey = config.apiKey ?? process.env.OPENAI_API_KEY ?? ''
118
+ this.defaultModel = config.defaultModel ?? 'gpt-6-luna'
119
+ this.maxTokens = config.maxTokens ?? 4096
120
+ this.baseUrl = config.baseUrl ?? process.env.OPENAI_BASE_URL ?? 'https://api.openai.com'
121
+ this.onRateLimit = config.onRateLimit
122
+ this.api = config.api ?? defaultApiFor(this.baseUrl)
123
+
124
+ // Fail fast with an actionable local error rather than a cryptic 401 on the
125
+ // first request. The default `provider` export constructs lazily on first
126
+ // use (see index.ts), so this surfaces the moment the provider is actually
127
+ // used, not at bond/module-load time. A key is required only for the
128
+ // official endpoint — a custom baseUrl may target a keyless self-hosted /
129
+ // local server (Ollama, LM Studio), where the auth header is omitted below.
130
+ const usingCustomEndpoint = Boolean(config.baseUrl ?? process.env.OPENAI_BASE_URL)
131
+ if (!this.apiKey && !usingCustomEndpoint) {
132
+ throw new Error(
133
+ 'OPENAI_API_KEY is not set. Add it to your environment to use the OpenAI AI provider.',
134
+ )
135
+ }
136
+ }
137
+
138
+ /**
139
+ * Build the request body for `POST /v1/chat/completions`.
140
+ *
141
+ * @param params - The caller's chat parameters.
142
+ * @param model - The resolved model id.
143
+ * @param maxTokens - The resolved output-token limit.
144
+ * @param useStream - Whether to request an SSE stream.
145
+ * @returns The JSON request body.
146
+ */
147
+ private buildChatCompletionsBody(
148
+ params: ChatParams,
149
+ model: string,
150
+ maxTokens: number,
151
+ useStream: boolean,
152
+ ): Record<string, unknown> {
153
+ const messages = this.formatMessages(params.messages, params.system)
154
+
155
+ const body: Record<string, unknown> = {
156
+ // BYO / provider-native tunables (reasoning_effort, enable_thinking, …).
157
+ // Spread FIRST so the structural fields below (model, messages,
158
+ // max_completion_tokens, tools, stream) always win and cannot be broken.
159
+ ...(params.extraBody ?? {}),
160
+ // Abuse attribution (see ChatParams.endUserId). OpenAI DEPRECATED `user`
161
+ // and replaced it with `safety_identifier` for exactly this purpose —
162
+ // their guidance is a hashed, stable per-user string, which is what
163
+ // endUserId already is. Sibling OpenAI-compatible bonds keep `user`: it is
164
+ // the field they actually implement, verified accepted by deepseek, xai,
165
+ // moonshot, alibaba and zhipu against their live APIs.
166
+ //
167
+ // This bond is also pointed at arbitrary BYO OpenAI-compatible endpoints
168
+ // (molecule-dev's custom providers), so the unknown-field question matters
169
+ // here: those same five providers all returned 200 when sent an unknown
170
+ // `safety_identifier`, i.e. tolerating unknown body params is the norm.
171
+ // A BYO endpoint therefore ignores this rather than rejecting it — and BYO
172
+ // runs on the user's OWN key, where attribution protects nothing of ours.
173
+ ...(params.endUserId ? { safety_identifier: params.endUserId } : {}),
174
+ model,
175
+ messages,
176
+ // `max_completion_tokens`, NOT `max_tokens`. Every GPT-5-family model
177
+ // hard-rejects the latter — "Unsupported parameter: 'max_tokens' is not
178
+ // supported with this model" (400) — and the catalog's OpenAI entries are
179
+ // all gpt-5.6-*, so this bond could not call any of its own models. The
180
+ // newer name is accepted by the older generations too (verified 200 on
181
+ // gpt-4o-mini and gpt-3.5-turbo), so there is no need to branch per model.
182
+ max_completion_tokens: maxTokens,
183
+ }
184
+ if (params.temperature !== undefined) body.temperature = params.temperature
185
+
186
+ // Reasoning depth: the caller resolves the model's native reasoning_effort
187
+ // value (none | low | medium | high | xhigh on GPT-5.4/5.5-family) from the
188
+ // model catalog and passes it as `thinking.effort`. Without it, omit the
189
+ // param entirely (the model's own default applies — medium on gpt-5.5).
190
+ if (params.thinking?.effort) {
191
+ body.reasoning_effort = params.thinking.effort
192
+ }
193
+
194
+ const tools = params.tools?.length ? this.formatTools(params.tools) : null
195
+ if (tools) {
196
+ body.tools = tools
197
+ if (params.toolChoice === 'required') {
198
+ body.tool_choice = 'required'
199
+ } else if (typeof params.toolChoice === 'object' && params.toolChoice?.type === 'tool') {
200
+ body.tool_choice = { type: 'function', function: { name: params.toolChoice.name } }
201
+ }
202
+ }
203
+
204
+ if (useStream) {
205
+ body.stream = true
206
+ body.stream_options = { include_usage: true }
207
+ }
208
+ return body
209
+ }
210
+
211
+ /**
212
+ * Send a chat request and yield streamed `ChatEvent`s.
213
+ *
214
+ * @param params - Chat parameters.
215
+ * @yields {ChatEvent}
216
+ */
217
+ async *chat(params: ChatParams): AsyncIterable<ChatEvent> {
218
+ const model = params.model ?? this.defaultModel
219
+ const maxTokens = params.maxTokens ?? this.maxTokens
220
+ const useStream = params.stream !== false
221
+ const isResponses = this.api === 'responses'
222
+
223
+ const body = isResponses
224
+ ? buildResponsesBody(params, model, maxTokens, useStream)
225
+ : this.buildChatCompletionsBody(params, model, maxTokens, useStream)
226
+ const path = isResponses ? '/v1/responses' : '/v1/chat/completions'
227
+
228
+ // Per-call correlation (see ChatParams.requestId): a header rather than the
229
+ // body's `user`, which is the stable per-account abuse-attribution value.
230
+ const requestId = params.requestId ?? randomUUID()
231
+ const call: OpenaiCallContext = {
232
+ meta: { requestId, endpoint: `${this.baseUrl}${path}` },
233
+ endUserId: params.endUserId,
234
+ }
235
+
236
+ const headers: Record<string, string> = {
237
+ 'Content-Type': 'application/json',
238
+ // Omitted for a keyless custom endpoint (a self-hosted / local server).
239
+ ...(this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}),
240
+ 'X-Mol-Request-Id': requestId,
241
+ }
242
+
243
+ const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000
244
+ const signal = params.signal ?? AbortSignal.timeout(DEFAULT_TIMEOUT_MS)
245
+
246
+ const MAX_RETRIES = 3
247
+ let response: Response | null = null
248
+ for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
249
+ response = await fetch(`${this.baseUrl}${path}`, {
250
+ method: 'POST',
251
+ headers,
252
+ body: JSON.stringify(body),
253
+ signal,
254
+ })
255
+
256
+ if (response.status === 429 || response.status === 503) {
257
+ const willRetry = attempt < MAX_RETRIES
258
+ // Retry-After is equally-valid as delta-seconds or an HTTP-date;
259
+ // parseInt on the date form yields NaN, degrading the backoff to a
260
+ // ~0ms retry against an already rate-limiting API. Guard it.
261
+ const retryAfter = response.headers.get('retry-after')
262
+ const parsedRetryAfterSeconds = retryAfter ? parseInt(retryAfter, 10) : NaN
263
+ const hasRetryAfter =
264
+ Number.isFinite(parsedRetryAfterSeconds) && parsedRetryAfterSeconds >= 0
265
+ // Additive jitter (<500ms): concurrent callers rejected together must
266
+ // not sleep identical delays and re-arrive as the same burst.
267
+ const delayMs = willRetry
268
+ ? (hasRetryAfter
269
+ ? Math.min(parsedRetryAfterSeconds * 1000, 60_000)
270
+ : Math.min(1000 * 2 ** attempt, 30_000)) + Math.floor(Math.random() * 500)
271
+ : 0
272
+ try {
273
+ this.onRateLimit?.({
274
+ provider: this.name,
275
+ model,
276
+ status: response.status,
277
+ attempt: attempt + 1,
278
+ willRetry,
279
+ retryInMs: delayMs,
280
+ ...(hasRetryAfter ? { retryAfterSeconds: parsedRetryAfterSeconds } : {}),
281
+ })
282
+ } catch (error) {
283
+ // Host-app telemetry; its failure must never break the request.
284
+ // … truncated — the full declaration is in node_modules/@molecule/api-ai-openai/dist/provider.d.ts
285
+ ```
286
+
106
287
  ### Functions
107
288
 
108
289
  #### `createProvider(config)`
@@ -119,20 +300,20 @@ function createProvider(config?: OpenaiConfig): AIProvider
119
300
 
120
301
  ### Constants
121
302
 
122
- #### `aiOpenaiSecretDefinitions`
303
+ #### `provider`
123
304
 
124
- Secret definitions required by the OpenAI AI bond.
305
+ The provider implementation.
125
306
 
126
307
  ```typescript
127
- const aiOpenaiSecretDefinitions: SecretDefinition[]
308
+ const provider: AIProvider
128
309
  ```
129
310
 
130
- #### `provider`
311
+ #### `aiOpenaiSecretDefinitions`
131
312
 
132
- The provider implementation.
313
+ Secret definitions required by the OpenAI AI bond.
133
314
 
134
315
  ```typescript
135
- const provider: AIProvider
316
+ const aiOpenaiSecretDefinitions: SecretDefinition[]
136
317
  ```
137
318
 
138
319
  ## Core Interface
@@ -1 +1 @@
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;IA6HzD;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,cAAc;IAmEtB;;;;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"}
1
+ {"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,OAAO,cAAc,CAAA;AAErB,OAAO,KAAK,EACV,UAAU,EAGV,SAAS,EAET,UAAU,EAGX,MAAM,kBAAkB,CAAA;AAQzB,OAAO,KAAK,EAAa,YAAY,EAAE,MAAM,YAAY,CAAA;AA4CzD;;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;IA4IzD;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,cAAc;IAmEtB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IA6BnB,uEAAuE;IACvE,OAAO,CAAC,WAAW;IAWnB;;;;;OAKG;IACH,OAAO,CAAE,yBAAyB;IA8ClC;;;;;OAKG;YACY,sBAAsB;IAgFrC;;;;;;OAMG;IACH,OAAO,CAAE,eAAe;CAyGzB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,UAAU,CAEhE"}
package/dist/provider.js CHANGED
@@ -11,6 +11,7 @@
11
11
  // Side-effect import: registers this bond's secret definitions so the
12
12
  // runtime registry is populated even when provider.js is imported directly
13
13
  // (not through the package barrel).
14
+ import { randomUUID } from 'node:crypto';
14
15
  import './secrets.js';
15
16
  import { getLogger } from '@molecule/api-bond';
16
17
  import { buildResponsesBody, parseResponsesNonStreaming, parseResponsesStream, } from './responses.js';
@@ -143,10 +144,18 @@ export class OpenaiAIProvider {
143
144
  ? buildResponsesBody(params, model, maxTokens, useStream)
144
145
  : this.buildChatCompletionsBody(params, model, maxTokens, useStream);
145
146
  const path = isResponses ? '/v1/responses' : '/v1/chat/completions';
147
+ // Per-call correlation (see ChatParams.requestId): a header rather than the
148
+ // body's `user`, which is the stable per-account abuse-attribution value.
149
+ const requestId = params.requestId ?? randomUUID();
150
+ const call = {
151
+ meta: { requestId, endpoint: `${this.baseUrl}${path}` },
152
+ endUserId: params.endUserId,
153
+ };
146
154
  const headers = {
147
155
  'Content-Type': 'application/json',
148
156
  // Omitted for a keyless custom endpoint (a self-hosted / local server).
149
157
  ...(this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}),
158
+ 'X-Mol-Request-Id': requestId,
150
159
  };
151
160
  const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
152
161
  const signal = params.signal ?? AbortSignal.timeout(DEFAULT_TIMEOUT_MS);
@@ -245,9 +254,14 @@ export class OpenaiAIProvider {
245
254
  : this.parseNonStreamingResponse(data);
246
255
  return;
247
256
  }
257
+ // Whatever the transport exposes about this call — the handle a vendor
258
+ // investigation needs.
259
+ const traceId = response.headers.get('x-request-id') ?? response.headers.get('request-id') ?? undefined;
260
+ if (traceId)
261
+ call.meta.traceId = traceId;
248
262
  yield* isResponses
249
- ? parseResponsesStream(response, model)
250
- : this.parseStreamingResponse(response);
263
+ ? parseResponsesStream(response, model, call.meta)
264
+ : this.parseStreamingResponse(response, call);
251
265
  }
252
266
  /**
253
267
  * Convert internal `ChatMessage` objects to the OpenAI message format.
@@ -426,7 +440,7 @@ export class OpenaiAIProvider {
426
440
  * @param response - The fetch Response whose body is an SSE stream.
427
441
  * @yields {ChatEvent} Incremental text, keep-alive, tool-use, and done events.
428
442
  */
429
- async *parseStreamingResponse(response) {
443
+ async *parseStreamingResponse(response, call) {
430
444
  const reader = response.body?.getReader();
431
445
  if (!reader) {
432
446
  yield {
@@ -453,7 +467,7 @@ export class OpenaiAIProvider {
453
467
  const lines = buffer.split('\n');
454
468
  buffer = lines.pop() ?? '';
455
469
  let yielded = false;
456
- for (const event of this.processSSELines(lines, state)) {
470
+ for (const event of this.processSSELines(lines, state, call)) {
457
471
  yielded = true;
458
472
  yield event;
459
473
  // A mid-stream error (rate-limit/overload during high load, sent as a
@@ -472,7 +486,7 @@ export class OpenaiAIProvider {
472
486
  yield { type: 'keep_alive' };
473
487
  }
474
488
  if (buffer.trim()) {
475
- for (const event of this.processSSELines(buffer.split('\n'), state)) {
489
+ for (const event of this.processSSELines(buffer.split('\n'), state, call)) {
476
490
  yield event;
477
491
  if (event.type === 'error')
478
492
  return;
@@ -501,6 +515,7 @@ export class OpenaiAIProvider {
501
515
  outputTokens: state.outputTokens,
502
516
  cacheReadInputTokens: state.cachedTokens,
503
517
  },
518
+ provider: call.meta,
504
519
  };
505
520
  }
506
521
  /**
@@ -510,7 +525,7 @@ export class OpenaiAIProvider {
510
525
  * @param state - Mutable stream state tracking tokens and pending tool calls.
511
526
  * @yields {ChatEvent} Text and no-op events parsed from the SSE data lines.
512
527
  */
513
- *processSSELines(lines, state) {
528
+ *processSSELines(lines, state, call) {
514
529
  for (const line of lines) {
515
530
  if (!line.startsWith('data: '))
516
531
  continue;
@@ -519,6 +534,36 @@ export class OpenaiAIProvider {
519
534
  continue;
520
535
  try {
521
536
  const event = JSON.parse(json);
537
+ // The reply's own identity, recorded for the caller, and the request's
538
+ // identity verified against whatever the host echoes back — a reply
539
+ // carrying somebody else's identity is not ours to stream on.
540
+ if (typeof event.id === 'string')
541
+ call.meta.responseId = event.id;
542
+ if (typeof event.model === 'string')
543
+ call.meta.model = event.model;
544
+ const echoedUser = typeof event.user === 'string' ? event.user : undefined;
545
+ const echoedRequest = typeof event.request_id === 'string'
546
+ ? event.request_id
547
+ : typeof event.requestId === 'string'
548
+ ? event.requestId
549
+ : undefined;
550
+ const wrongUser = echoedUser !== undefined && call.endUserId !== undefined && echoedUser !== call.endUserId;
551
+ const wrongRequest = echoedRequest !== undefined && echoedRequest !== call.meta.requestId;
552
+ if (wrongUser || wrongRequest) {
553
+ logger.error('Provider echoed a different identity — this reply is not ours', {
554
+ requestId: call.meta.requestId,
555
+ echoedUser: wrongUser ? echoedUser : undefined,
556
+ echoedRequestId: wrongRequest ? echoedRequest : undefined,
557
+ responseId: call.meta.responseId,
558
+ traceId: call.meta.traceId,
559
+ });
560
+ yield {
561
+ type: 'error',
562
+ message: 'AI service error. Please try again.',
563
+ errorKey: 'ai.error.apiError',
564
+ };
565
+ return;
566
+ }
522
567
  // A mid-stream error arrives as a `data: {"error": {...}}` chunk (no
523
568
  // `choices`) — most importantly rate-limit/overload during high load.
524
569
  // Without this it matches no branch below and is silently dropped, so the
@@ -24,7 +24,7 @@
24
24
  *
25
25
  * @module
26
26
  */
27
- import type { AITool, ChatEvent, ChatMessage, ChatParams, ServerTool, TokenUsage } from '@molecule/api-ai';
27
+ import type { AITool, ChatEvent, ChatMessage, ChatParams, ProviderResponseMeta, ServerTool, TokenUsage } from '@molecule/api-ai';
28
28
  /** Usage object as reported on a Responses API `response`. */
29
29
  interface ResponsesUsage {
30
30
  input_tokens?: number;
@@ -92,6 +92,6 @@ export declare function parseResponsesNonStreaming(data: Record<string, unknown>
92
92
  * @param model - The model the request targeted.
93
93
  * @yields {ChatEvent} Text, tool-call progress, tool-use, keep-alive, and done events.
94
94
  */
95
- export declare function parseResponsesStream(response: Response, model: string): AsyncIterable<ChatEvent>;
95
+ export declare function parseResponsesStream(response: Response, model: string, meta?: ProviderResponseMeta): AsyncIterable<ChatEvent>;
96
96
  export {};
97
97
  //# sourceMappingURL=responses.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../src/responses.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EACV,MAAM,EACN,SAAS,EACT,WAAW,EACX,UAAU,EAEV,UAAU,EACV,UAAU,EACX,MAAM,kBAAkB,CAAA;AA6EzB,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,CA6BzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,WAAW,EAAE,EACvB,KAAK,EAAE,MAAM,GACZ,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAgDhC;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,CACzC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,EAAE,MAAM,GACZ,QAAQ,CAAC,SAAS,CAAC,CA2BrB;AAED;;;;;;GAMG;AACH,wBAAuB,oBAAoB,CACzC,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,MAAM,GACZ,aAAa,CAAC,SAAS,CAAC,CA4J1B"}
1
+ {"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../src/responses.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EACV,MAAM,EACN,SAAS,EACT,WAAW,EACX,UAAU,EAEV,oBAAoB,EACpB,UAAU,EACV,UAAU,EACX,MAAM,kBAAkB,CAAA;AA6EzB,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,CA6BzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,WAAW,EAAE,EACvB,KAAK,EAAE,MAAM,GACZ,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAgDhC;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,CACzC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,EAAE,MAAM,GACZ,QAAQ,CAAC,SAAS,CAAC,CA2BrB;AAED;;;;;;GAMG;AACH,wBAAuB,oBAAoB,CACzC,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,oBAAoB,GAC1B,aAAa,CAAC,SAAS,CAAC,CAmK1B"}
package/dist/responses.js CHANGED
@@ -320,7 +320,7 @@ export function* parseResponsesNonStreaming(data, model) {
320
320
  * @param model - The model the request targeted.
321
321
  * @yields {ChatEvent} Text, tool-call progress, tool-use, keep-alive, and done events.
322
322
  */
323
- export async function* parseResponsesStream(response, model) {
323
+ export async function* parseResponsesStream(response, model, meta) {
324
324
  const reader = response.body?.getReader();
325
325
  if (!reader) {
326
326
  yield {
@@ -356,6 +356,15 @@ export async function* parseResponsesStream(response, model) {
356
356
  logger.debug('Skipping malformed OpenAI Responses SSE JSON line', { json, error });
357
357
  return;
358
358
  }
359
+ // The reply's own identity: the Responses stream carries it on the
360
+ // container event (`response.created` / `response.completed`).
361
+ const envelope = event.response;
362
+ if (meta) {
363
+ if (typeof envelope?.id === 'string')
364
+ meta.responseId = envelope.id;
365
+ if (typeof envelope?.model === 'string')
366
+ meta.model = envelope.model;
367
+ }
359
368
  const item = event.item;
360
369
  switch (event.type) {
361
370
  case 'response.output_text.delta':
@@ -478,5 +487,5 @@ export async function* parseResponsesStream(response, model) {
478
487
  };
479
488
  return;
480
489
  }
481
- yield { type: 'done', usage };
490
+ yield { type: 'done', usage, ...(meta ? { provider: meta } : {}) };
482
491
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/api-ai-openai",
3
- "version": "1.4.3",
3
+ "version": "1.4.4",
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.3.0",
36
+ "@molecule/api-ai": "1.3.3",
37
37
  "@molecule/api-bond": "1.0.2",
38
38
  "@types/node": "26.1.2",
39
39
  "typescript": "6.0.3",