@molecule/api-ai-openai 1.4.4 → 1.5.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,17 +3,17 @@ 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-16T16:53:56.772Z
6
+ Generated: 2026-10-31T06:54:53.084Z
7
7
  -->
8
8
 
9
9
  # @molecule/api-ai-openai
10
10
 
11
+ OpenAI (GPT) AI provider for molecule.dev.
12
+
11
13
  > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
12
14
  > It is written to be read by coding agents as much as by people, and is generated from this
13
15
  > package's source — edit `src/index.ts` JSDoc, not this file.
14
16
 
15
- OpenAI (GPT) AI provider for molecule.dev.
16
-
17
17
  ## Quick Start
18
18
 
19
19
  ```typescript
@@ -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,6 +130,7 @@ 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
135
  // Fail fast with an actionable local error rather than a cryptic 401 on the
125
136
  // first request. The default `provider` export constructs lazily on first
@@ -245,7 +256,9 @@ class OpenaiAIProvider implements AIProvider {
245
256
 
246
257
  const MAX_RETRIES = 3
247
258
  let response: Response | null = null
259
+ let rejectedBody: string | undefined
248
260
  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
261
+ rejectedBody = undefined
249
262
  response = await fetch(`${this.baseUrl}${path}`, {
250
263
  method: 'POST',
251
264
  headers,
@@ -254,33 +267,25 @@ class OpenaiAIProvider implements AIProvider {
254
267
  })
255
268
 
256
269
  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
270
+ // Read the body once: an unread body pins its connection, and only the
271
+ // body says whether a 429 is a rate limit or an exhausted quota.
272
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
- })
273
+ rejectedBody = await response.text()
282
274
  } catch (error) {
283
- // Host-app telemetry; its failure must never break the request.
275
+ // Caller cancellation still ends the request; any other read failure
276
+ // only loses the reason, so the body counts as read and the retry
277
+ // policy goes on (the same guard the moonshot bond applies).
278
+ signal.throwIfAborted()
279
+ logger.debug('OpenAI rejected response body could not be read', { error })
280
+ rejectedBody = ''
281
+ }
282
+ const upstreamError = parseUpstreamError(rejectedBody)
283
+ // Billing, spend, and quota failures do not recover by waiting: a
284
+ // bounded retry budget fails at once instead of burning its retries.
285
+ const quotaExhausted =
286
+ this.quotaSemantics === 'openai' && isQuotaExhausted(response.status, upstreamError)
287
+ const willRetry = !quotaExhausted && attempt < MAX_RETRIES
288
+ // Retry-After is equally-valid as delta-seconds or an HTTP-date;
284
289
  // … truncated — the full declaration is in node_modules/@molecule/api-ai-openai/dist/provider.d.ts
285
290
  ```
286
291
 
@@ -368,6 +373,11 @@ tools (`serverTools`, e.g. `{ type: 'web_search', name: 'web_search' }`); chat/c
368
373
  ignores `serverTools`. `extraBody` is merged into whichever endpoint's body is sent, so its
369
374
  keys must be that endpoint's params (e.g. `reasoning`, not `reasoning_effort`, on Responses).
370
375
 
376
+ **Quota semantics**: OpenAI and Azure OpenAI hosts treat documented 429 billing, spend, and
377
+ quota codes as exhausted without retrying; other hosts retry them as ordinary throttling.
378
+ Set `quotaSemantics: 'openai'` when a proxy forwards those failures unchanged, or
379
+ `quotaSemantics: 'retryable'` to preserve retries on a native host with different semantics.
380
+
371
381
  **Missing `OPENAI_API_KEY` fails fast**: the provider throws naming the exact env var on
372
382
  first use (the exported `provider` is a lazy proxy, so this fires on the first `chat()` call,
373
383
  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.4",
3
+ "version": "1.5.0",
4
4
  "description": "",
5
5
  "homepage": "https://www.molecule.dev/packages/api-ai-openai",
6
6
  "type": "module",
@@ -33,11 +33,11 @@
33
33
  "directory": "packages/api/bonds/ai/openai"
34
34
  },
35
35
  "devDependencies": {
36
- "@molecule/api-ai": "1.3.3",
37
- "@molecule/api-bond": "1.0.2",
38
- "@types/node": "26.1.2",
36
+ "@molecule/api-ai": "1.5.0",
37
+ "@molecule/api-bond": "1.0.4",
38
+ "@types/node": "26.6.5",
39
39
  "typescript": "6.0.3",
40
- "vitest": "4.1.11"
40
+ "vitest": "4.1.12"
41
41
  },
42
42
  "peerDependencies": {
43
43
  "@molecule/api-ai": "^1.0.1",