@molecule/api-ai-openai 1.4.5 → 1.5.1

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-10-16T23:28:30.373Z
6
+ Generated: 2026-11-04T14:08:52.008Z
7
7
  -->
8
8
 
9
9
  # @molecule/api-ai-openai
@@ -62,6 +62,15 @@ interface OpenaiConfig {
62
62
  maxTokens?: number
63
63
  /** Override the API base URL (for proxies / Azure). */
64
64
  baseUrl?: string
65
+ /**
66
+ * How the upstream uses OpenAI's documented 429 quota codes. `'openai'`
67
+ * treats them as exhausted billing/spend limits and stops without retrying;
68
+ * `'retryable'` treats them as ordinary throttling. Defaults to `'openai'`
69
+ * for `api.openai.com` and `*.openai.azure.com` (including explicit ports),
70
+ * and `'retryable'` for every other host. Set `'openai'` for a proxy that
71
+ * forwards OpenAI or Azure OpenAI quota failures unchanged.
72
+ */
73
+ quotaSemantics?: 'openai' | 'retryable'
65
74
  /** Called on each rate-limited/overloaded upstream response, before any retry sleep. */
66
75
  onRateLimit?: AiRateLimitCallback
67
76
  /**
@@ -112,6 +121,7 @@ class OpenaiAIProvider implements AIProvider {
112
121
  private baseUrl: string
113
122
  private onRateLimit?: AiRateLimitCallback
114
123
  private api: OpenaiApi
124
+ private quotaSemantics: OpenaiQuotaSemantics
115
125
 
116
126
  constructor(config: OpenaiConfig = {}) {
117
127
  this.apiKey = config.apiKey ?? process.env.OPENAI_API_KEY ?? ''
@@ -120,13 +130,8 @@ class OpenaiAIProvider implements AIProvider {
120
130
  this.baseUrl = config.baseUrl ?? process.env.OPENAI_BASE_URL ?? 'https://api.openai.com'
121
131
  this.onRateLimit = config.onRateLimit
122
132
  this.api = config.api ?? defaultApiFor(this.baseUrl)
133
+ this.quotaSemantics = config.quotaSemantics ?? defaultQuotaSemanticsFor(this.baseUrl)
123
134
 
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
135
  const usingCustomEndpoint = Boolean(config.baseUrl ?? process.env.OPENAI_BASE_URL)
131
136
  if (!this.apiKey && !usingCustomEndpoint) {
132
137
  throw new Error(
@@ -135,15 +140,6 @@ class OpenaiAIProvider implements AIProvider {
135
140
  }
136
141
  }
137
142
 
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
143
  private buildChatCompletionsBody(
148
144
  params: ChatParams,
149
145
  model: string,
@@ -153,40 +149,14 @@ class OpenaiAIProvider implements AIProvider {
153
149
  const messages = this.formatMessages(params.messages, params.system)
154
150
 
155
151
  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
152
  ...(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
153
  ...(params.endUserId ? { safety_identifier: params.endUserId } : {}),
174
154
  model,
175
155
  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
156
  max_completion_tokens: maxTokens,
183
157
  }
184
158
  if (params.temperature !== undefined) body.temperature = params.temperature
185
159
 
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
160
  if (params.thinking?.effort) {
191
161
  body.reasoning_effort = params.thinking.effort
192
162
  }
@@ -207,83 +177,11 @@ class OpenaiAIProvider implements AIProvider {
207
177
  }
208
178
  return body
209
179
  }
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
180
+ // … truncated — 7 more members: chat, formatMessages, formatBlock, formatTools, parseNonStreamingResponse, parseStreamingResponse, processSSELines; the full declaration is in node_modules/@molecule/api-ai-openai/dist/provider.d.ts
285
181
  ```
286
182
 
183
+ _(Member comments are left out to fit; the full declaration is in `node_modules/@molecule/api-ai-openai/dist/provider.d.ts`.)_
184
+
287
185
  ### Functions
288
186
 
289
187
  #### `createProvider(config)`
@@ -368,6 +266,11 @@ tools (`serverTools`, e.g. `{ type: 'web_search', name: 'web_search' }`); chat/c
368
266
  ignores `serverTools`. `extraBody` is merged into whichever endpoint's body is sent, so its
369
267
  keys must be that endpoint's params (e.g. `reasoning`, not `reasoning_effort`, on Responses).
370
268
 
269
+ **Quota semantics**: OpenAI and Azure OpenAI hosts treat documented 429 billing, spend, and
270
+ quota codes as exhausted without retrying; other hosts retry them as ordinary throttling.
271
+ Set `quotaSemantics: 'openai'` when a proxy forwards those failures unchanged, or
272
+ `quotaSemantics: 'retryable'` to preserve retries on a native host with different semantics.
273
+
371
274
  **Missing `OPENAI_API_KEY` fails fast**: the provider throws naming the exact env var on
372
275
  first use (the exported `provider` is a lazy proxy, so this fires on the first `chat()` call,
373
276
  not at bond/module-load time) — it never silently sends an empty key.
package/dist/index.d.ts CHANGED
@@ -33,6 +33,11 @@
33
33
  * ignores `serverTools`. `extraBody` is merged into whichever endpoint's body is sent, so its
34
34
  * keys must be that endpoint's params (e.g. `reasoning`, not `reasoning_effort`, on Responses).
35
35
  *
36
+ * **Quota semantics**: OpenAI and Azure OpenAI hosts treat documented 429 billing, spend, and
37
+ * quota codes as exhausted without retrying; other hosts retry them as ordinary throttling.
38
+ * Set `quotaSemantics: 'openai'` when a proxy forwards those failures unchanged, or
39
+ * `quotaSemantics: 'retryable'` to preserve retries on a native host with different semantics.
40
+ *
36
41
  * **Missing `OPENAI_API_KEY` fails fast**: the provider throws naming the exact env var on
37
42
  * first use (the exported `provider` is a lazy proxy, so this fires on the first `chat()` call,
38
43
  * 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;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
@@ -33,6 +33,11 @@
33
33
  * ignores `serverTools`. `extraBody` is merged into whichever endpoint's body is sent, so its
34
34
  * keys must be that endpoint's params (e.g. `reasoning`, not `reasoning_effort`, on Responses).
35
35
  *
36
+ * **Quota semantics**: OpenAI and Azure OpenAI hosts treat documented 429 billing, spend, and
37
+ * quota codes as exhausted without retrying; other hosts retry them as ordinary throttling.
38
+ * Set `quotaSemantics: 'openai'` when a proxy forwards those failures unchanged, or
39
+ * `quotaSemantics: 'retryable'` to preserve retries on a native host with different semantics.
40
+ *
36
41
  * **Missing `OPENAI_API_KEY` fails fast**: the provider throws naming the exact env var on
37
42
  * first use (the exported `provider` is a lazy proxy, so this fires on the first `chat()` call,
38
43
  * not at bond/module-load time) — it never silently sends an empty key.
@@ -22,6 +22,7 @@ export declare class OpenaiAIProvider implements AIProvider {
22
22
  private baseUrl;
23
23
  private onRateLimit?;
24
24
  private api;
25
+ private quotaSemantics;
25
26
  constructor(config?: OpenaiConfig);
26
27
  /**
27
28
  * Build the request body for `POST /v1/chat/completions`.
@@ -1 +1 @@
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"}
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;AAiHzD;;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;IACtB,OAAO,CAAC,cAAc,CAAsB;gBAEhC,MAAM,GAAE,YAAiB;IAuBrC;;;;;;;;OAQG;IACH,OAAO,CAAC,wBAAwB;IAgEhC;;;;;OAKG;IACI,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,CAAC,SAAS,CAAC;IA0KzD;;;;;;;;;;;;;;;;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
@@ -19,6 +19,19 @@ import { streamErrorEvent } from './utilities.js';
19
19
  const logger = getLogger();
20
20
  /** OpenAI's own API host — the only one assumed to serve `/v1/responses`. */
21
21
  const OPENAI_API_HOST = 'api.openai.com';
22
+ /** The URL's normalized hostname, without a port or a trailing DNS root dot. */
23
+ function normalizedHostname(baseUrl) {
24
+ try {
25
+ return new URL(baseUrl).hostname.replace(/\.$/, '');
26
+ }
27
+ catch (_error) {
28
+ return undefined;
29
+ }
30
+ }
31
+ /** Whether a base URL addresses OpenAI's own API rather than a compatible service. */
32
+ function isOpenAIEndpoint(baseUrl) {
33
+ return normalizedHostname(baseUrl) === OPENAI_API_HOST;
34
+ }
22
35
  /**
23
36
  * Pick the default endpoint for a base URL: Responses for OpenAI's own API,
24
37
  * chat/completions for anything else.
@@ -27,13 +40,62 @@ const OPENAI_API_HOST = 'api.openai.com';
27
40
  * @returns The endpoint to use.
28
41
  */
29
42
  function defaultApiFor(baseUrl) {
43
+ return isOpenAIEndpoint(baseUrl) ? 'responses' : 'chat-completions';
44
+ }
45
+ /**
46
+ * Pick the quota semantics native OpenAI and Azure OpenAI endpoints use.
47
+ * Compatible services retain ordinary 429 retries unless explicitly configured
48
+ * to forward OpenAI's billing/quota behavior.
49
+ */
50
+ function defaultQuotaSemanticsFor(baseUrl) {
51
+ const hostname = normalizedHostname(baseUrl);
52
+ return hostname === OPENAI_API_HOST || hostname?.endsWith('.openai.azure.com')
53
+ ? 'openai'
54
+ : 'retryable';
55
+ }
56
+ /**
57
+ * OpenAI's documented billing, spend, and quota errors on HTTP 429
58
+ * (https://platform.openai.com/docs/guides/error-codes/api-errors). Retrying
59
+ * cannot restore access; ordinary rate-limit codes on that status stay retryable.
60
+ */
61
+ const QUOTA_EXHAUSTED_CODES = new Set([
62
+ 'insufficient_quota',
63
+ 'credit_balance_exhausted',
64
+ 'organization_spend_limit_exceeded',
65
+ 'project_spend_limit_exceeded',
66
+ 'organization_usage_limit_exceeded',
67
+ ]);
68
+ /** Whether this is a documented account quota failure on its documented status. */
69
+ function isQuotaExhausted(status, error) {
70
+ return status === 429 && error?.type !== undefined && QUOTA_EXHAUSTED_CODES.has(error.type);
71
+ }
72
+ /**
73
+ * Read the upstream's explanation from a rejected response body: its error
74
+ * `code` (or broader `type`) and `message`, the message bounded to 500 characters.
75
+ * OpenAI directs callers to inspect the specific `code` for billing failures.
76
+ *
77
+ * @param text - The rejected response's body text.
78
+ * @returns The upstream error, or `undefined` when the body carried neither field.
79
+ */
80
+ function parseUpstreamError(text) {
81
+ let error;
30
82
  try {
31
- return new URL(baseUrl).host === OPENAI_API_HOST ? 'responses' : 'chat-completions';
83
+ error = JSON.parse(text)?.error;
32
84
  }
33
85
  catch (_error) {
34
- // An unparseable base URL is not OpenAI's; the request itself will report it.
35
- return 'chat-completions';
86
+ // Not JSON (a proxy's error page, plain text): a short body is the message itself.
87
+ const trimmed = text.trim();
88
+ return trimmed && trimmed.length <= 500 ? { message: trimmed } : undefined;
36
89
  }
90
+ const type = typeof error?.code === 'string'
91
+ ? error.code
92
+ : typeof error?.type === 'string'
93
+ ? error.type
94
+ : undefined;
95
+ const message = typeof error?.message === 'string' ? error.message.slice(0, 500) : undefined;
96
+ if (!type && !message)
97
+ return undefined;
98
+ return { ...(type ? { type } : {}), ...(message ? { message } : {}) };
37
99
  }
38
100
  /**
39
101
  * OpenAI Chat Completions provider implementing the `AIProvider` interface.
@@ -46,6 +108,7 @@ export class OpenaiAIProvider {
46
108
  baseUrl;
47
109
  onRateLimit;
48
110
  api;
111
+ quotaSemantics;
49
112
  constructor(config = {}) {
50
113
  this.apiKey = config.apiKey ?? process.env.OPENAI_API_KEY ?? '';
51
114
  this.defaultModel = config.defaultModel ?? 'gpt-6-luna';
@@ -53,6 +116,7 @@ export class OpenaiAIProvider {
53
116
  this.baseUrl = config.baseUrl ?? process.env.OPENAI_BASE_URL ?? 'https://api.openai.com';
54
117
  this.onRateLimit = config.onRateLimit;
55
118
  this.api = config.api ?? defaultApiFor(this.baseUrl);
119
+ this.quotaSemantics = config.quotaSemantics ?? defaultQuotaSemanticsFor(this.baseUrl);
56
120
  // Fail fast with an actionable local error rather than a cryptic 401 on the
57
121
  // first request. The default `provider` export constructs lazily on first
58
122
  // use (see index.ts), so this surfaces the moment the provider is actually
@@ -161,7 +225,9 @@ export class OpenaiAIProvider {
161
225
  const signal = params.signal ?? AbortSignal.timeout(DEFAULT_TIMEOUT_MS);
162
226
  const MAX_RETRIES = 3;
163
227
  let response = null;
228
+ let rejectedBody;
164
229
  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
230
+ rejectedBody = undefined;
165
231
  response = await fetch(`${this.baseUrl}${path}`, {
166
232
  method: 'POST',
167
233
  headers,
@@ -169,7 +235,24 @@ export class OpenaiAIProvider {
169
235
  signal,
170
236
  });
171
237
  if (response.status === 429 || response.status === 503) {
172
- const willRetry = attempt < MAX_RETRIES;
238
+ // Read the body once: an unread body pins its connection, and only the
239
+ // body says whether a 429 is a rate limit or an exhausted quota.
240
+ try {
241
+ rejectedBody = await response.text();
242
+ }
243
+ catch (error) {
244
+ // Caller cancellation still ends the request; any other read failure
245
+ // only loses the reason, so the body counts as read and the retry
246
+ // policy goes on (the same guard the moonshot bond applies).
247
+ signal.throwIfAborted();
248
+ logger.debug('OpenAI rejected response body could not be read', { error });
249
+ rejectedBody = '';
250
+ }
251
+ const upstreamError = parseUpstreamError(rejectedBody);
252
+ // Billing, spend, and quota failures do not recover by waiting: a
253
+ // bounded retry budget fails at once instead of burning its retries.
254
+ const quotaExhausted = this.quotaSemantics === 'openai' && isQuotaExhausted(response.status, upstreamError);
255
+ const willRetry = !quotaExhausted && attempt < MAX_RETRIES;
173
256
  // Retry-After is equally-valid as delta-seconds or an HTTP-date;
174
257
  // parseInt on the date form yields NaN, degrading the backoff to a
175
258
  // ~0ms retry against an already rate-limiting API. Guard it.
@@ -192,6 +275,7 @@ export class OpenaiAIProvider {
192
275
  willRetry,
193
276
  retryInMs: delayMs,
194
277
  ...(hasRetryAfter ? { retryAfterSeconds: parsedRetryAfterSeconds } : {}),
278
+ ...(upstreamError ? { upstreamError } : {}),
195
279
  });
196
280
  }
197
281
  catch (error) {
@@ -199,10 +283,13 @@ export class OpenaiAIProvider {
199
283
  logger.warn('onRateLimit callback threw', { error });
200
284
  }
201
285
  if (willRetry) {
202
- logger.warn('OpenAI API rate limited, retrying', {
286
+ logger.warn(quotaExhausted
287
+ ? 'OpenAI account quota exhausted, retrying until recharged'
288
+ : 'OpenAI API rate limited, retrying', {
203
289
  status: response.status,
204
290
  attempt: attempt + 1,
205
291
  delayMs,
292
+ ...(upstreamError ? { upstreamError } : {}),
206
293
  });
207
294
  await new Promise((resolve) => {
208
295
  const timer = setTimeout(resolve, delayMs);
@@ -219,7 +306,8 @@ export class OpenaiAIProvider {
219
306
  break;
220
307
  }
221
308
  if (!response.ok) {
222
- const errorBody = await response.text();
309
+ // A 429/503 body was already read by the retry loop; a body reads only once.
310
+ const errorBody = rejectedBody ?? (await response.text());
223
311
  let detail = `HTTP ${response.status}`;
224
312
  try {
225
313
  const parsed = JSON.parse(errorBody);
@@ -232,18 +320,21 @@ export class OpenaiAIProvider {
232
320
  detail = errorBody;
233
321
  }
234
322
  logger.error('OpenAI API error', { status: response.status, detail });
235
- const clientMessage = response.status === 429
236
- ? 'AI rate limit exceeded. Please try again shortly.'
237
- : response.status === 401
238
- ? 'AI service configuration error.'
239
- : response.status === 400 &&
240
- /context.*length|maximum context|too many tokens|prompt is too long/i.test(detail)
241
- ? "Conversation too long for the model's context window."
242
- : response.status === 400
243
- ? 'AI request was invalid — check the model and request parameters.'
244
- : response.status === 503 || response.status === 502
245
- ? 'AI service is temporarily overloaded. Please try again in a moment.'
246
- : 'AI service error. Please try again.';
323
+ const clientMessage = this.quotaSemantics === 'openai' &&
324
+ isQuotaExhausted(response.status, parseUpstreamError(errorBody))
325
+ ? 'AI service is unavailable right now. Please try again later.'
326
+ : response.status === 429
327
+ ? 'AI rate limit exceeded. Please try again shortly.'
328
+ : response.status === 401
329
+ ? 'AI service configuration error.'
330
+ : response.status === 400 &&
331
+ /context.*length|maximum context|too many tokens|prompt is too long/i.test(detail)
332
+ ? "Conversation too long for the model's context window."
333
+ : response.status === 400
334
+ ? 'AI request was invalid — check the model and request parameters.'
335
+ : response.status === 503 || response.status === 502
336
+ ? 'AI service is temporarily overloaded. Please try again in a moment.'
337
+ : 'AI service error. Please try again.';
247
338
  yield { type: 'error', message: clientMessage, errorKey: 'ai.error.apiError' };
248
339
  return;
249
340
  }
package/dist/types.d.ts CHANGED
@@ -14,6 +14,15 @@ export interface OpenaiConfig {
14
14
  maxTokens?: number;
15
15
  /** Override the API base URL (for proxies / Azure). */
16
16
  baseUrl?: string;
17
+ /**
18
+ * How the upstream uses OpenAI's documented 429 quota codes. `'openai'`
19
+ * treats them as exhausted billing/spend limits and stops without retrying;
20
+ * `'retryable'` treats them as ordinary throttling. Defaults to `'openai'`
21
+ * for `api.openai.com` and `*.openai.azure.com` (including explicit ports),
22
+ * and `'retryable'` for every other host. Set `'openai'` for a proxy that
23
+ * forwards OpenAI or Azure OpenAI quota failures unchanged.
24
+ */
25
+ quotaSemantics?: 'openai' | 'retryable';
17
26
  /** Called on each rate-limited/overloaded upstream response, before any retry sleep. */
18
27
  onRateLimit?: AiRateLimitCallback;
19
28
  /**
@@ -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;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"}
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;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAA;IACvC,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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/api-ai-openai",
3
- "version": "1.4.5",
3
+ "version": "1.5.1",
4
4
  "description": "",
5
5
  "homepage": "https://www.molecule.dev/packages/api-ai-openai",
6
6
  "type": "module",
@@ -33,8 +33,8 @@
33
33
  "directory": "packages/api/bonds/ai/openai"
34
34
  },
35
35
  "devDependencies": {
36
- "@molecule/api-ai": "1.3.5",
37
- "@molecule/api-bond": "1.0.3",
36
+ "@molecule/api-ai": "1.5.0",
37
+ "@molecule/api-bond": "1.0.4",
38
38
  "@types/node": "26.6.5",
39
39
  "typescript": "6.0.3",
40
40
  "vitest": "4.1.12"