@molecule/api-ai-moonshot 1.1.7 → 1.3.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-10-23T20:52:04.229Z
6
+ Generated: 2026-10-29T12:21:44.469Z
7
7
  -->
8
8
 
9
9
  # @molecule/api-ai-moonshot
@@ -60,7 +60,7 @@ interface MoonshotConfig {
60
60
  defaultModel?: string
61
61
  /** Maximum tokens for completions. */
62
62
  maxTokens?: number
63
- /** Base URL override (for proxies). Defaults to 'https://api.moonshot.cn'. */
63
+ /** Base URL override (for proxies). Defaults to 'https://api.moonshot.ai'. */
64
64
  baseUrl?: string
65
65
  /**
66
66
  * Chat-completions path appended to {@link baseUrl}. Defaults to
@@ -80,6 +80,12 @@ interface MoonshotConfig {
80
80
  modelMap?: Record<string, string>
81
81
  /** Called on each rate-limited/overloaded upstream response, before any retry sleep. */
82
82
  onRateLimit?: AiRateLimitCallback
83
+ /**
84
+ * Transient 429/503 retries after the initial request. Defaults to the historical three.
85
+ * `'until-aborted'` keeps replaying the identical request and requires every chat call to
86
+ * supply its own cancellation signal; permanent failures such as HTTP 400/401 are never retried.
87
+ */
88
+ rateLimitRetries?: MoonshotRateLimitRetries
83
89
  }
84
90
  ```
85
91
 
@@ -97,6 +103,16 @@ interface ProcessEnv {
97
103
  }
98
104
  ```
99
105
 
106
+ ### Types
107
+
108
+ #### `MoonshotRateLimitRetries`
109
+
110
+ Retry policy for transient HTTP 429/503 responses. A number counts retries after the first POST.
111
+
112
+ ```typescript
113
+ type MoonshotRateLimitRetries = number | 'until-aborted'
114
+ ```
115
+
100
116
  ### Functions
101
117
 
102
118
  #### `createProvider(config)`
@@ -172,6 +188,9 @@ Peer dependencies:
172
188
  - `@molecule/api-secrets`
173
189
 
174
190
  Config: `MOONSHOT_API_KEY` (SERVER-side only) plus an optional default model id/base URL.
191
+ `createProvider({ rateLimitRetries: 'until-aborted' })` keeps retrying temporary
192
+ HTTP 429/503 responses with the same request. Each call must supply its own
193
+ cancellation signal. The default remains three retries; permanent errors are not retried.
175
194
 
176
195
  **Missing `MOONSHOT_API_KEY` fails fast**: the provider throws naming the exact env var on
177
196
  first use (the exported `provider` is a lazy proxy, so this fires on the first `chat()` call,
package/dist/index.d.ts CHANGED
@@ -22,6 +22,9 @@
22
22
  *
23
23
  * @remarks
24
24
  * Config: `MOONSHOT_API_KEY` (SERVER-side only) plus an optional default model id/base URL.
25
+ * `createProvider({ rateLimitRetries: 'until-aborted' })` keeps retrying temporary
26
+ * HTTP 429/503 responses with the same request. Each call must supply its own
27
+ * cancellation signal. The default remains three retries; permanent errors are not retried.
25
28
  *
26
29
  * **Missing `MOONSHOT_API_KEY` fails fast**: the provider throws naming the exact env var on
27
30
  * first use (the exported `provider` is a lazy proxy, so this fires on the first `chat()` call,
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAE1B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAMlD;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,UAUrB,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAE1B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAMlD;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,UAUrB,CAAA"}
package/dist/index.js CHANGED
@@ -22,6 +22,9 @@
22
22
  *
23
23
  * @remarks
24
24
  * Config: `MOONSHOT_API_KEY` (SERVER-side only) plus an optional default model id/base URL.
25
+ * `createProvider({ rateLimitRetries: 'until-aborted' })` keeps retrying temporary
26
+ * HTTP 429/503 responses with the same request. Each call must supply its own
27
+ * cancellation signal. The default remains three retries; permanent errors are not retried.
25
28
  *
26
29
  * **Missing `MOONSHOT_API_KEY` fails fast**: the provider throws naming the exact env var on
27
30
  * first use (the exported `provider` is a lazy proxy, so this fires on the first `chat()` call,
@@ -1 +1 @@
1
- {"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EACV,UAAU,EAQX,MAAM,kBAAkB,CAAA;AASzB,OAAO,cAAc,CAAA;AAErB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAgtBhD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,UAAU,CAElE"}
1
+ {"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EACV,UAAU,EAQX,MAAM,kBAAkB,CAAA;AASzB,OAAO,cAAc,CAAA;AAErB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAizBhD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,UAAU,CAElE"}
package/dist/provider.js CHANGED
@@ -22,6 +22,59 @@ import './secrets.js';
22
22
  function budgetToEffort(budgetTokens) {
23
23
  return budgetTokens >= 8_000 ? 'high' : 'low';
24
24
  }
25
+ /**
26
+ * Wait before replaying a rejected request without leaving a timer or abort
27
+ * listener behind. Caller cancellation rejects immediately, so no later POST
28
+ * can escape after the caller has abandoned the conversation.
29
+ */
30
+ async function waitForRetry(delayMs, signal) {
31
+ if (signal.aborted)
32
+ throw signal.reason;
33
+ await new Promise((resolve, reject) => {
34
+ const onAbort = () => {
35
+ clearTimeout(timer);
36
+ signal.removeEventListener('abort', onAbort);
37
+ reject(signal.reason);
38
+ };
39
+ const timer = setTimeout(() => {
40
+ signal.removeEventListener('abort', onAbort);
41
+ resolve();
42
+ }, delayMs);
43
+ signal.addEventListener('abort', onAbort, { once: true });
44
+ // Cover cancellation between the first check and listener registration.
45
+ if (signal.aborted)
46
+ onAbort();
47
+ });
48
+ }
49
+ /** Moonshot's error type for an account whose balance is exhausted; it is answered with HTTP 429. */
50
+ const QUOTA_EXHAUSTED_TYPE = 'exceeded_current_quota_error';
51
+ /**
52
+ * Read the upstream's explanation from a rejected response body: its error
53
+ * `type` (or `code`) and `message`, the message bounded to 500 characters.
54
+ *
55
+ * @param text - The rejected response's body text.
56
+ * @returns The upstream error, or `undefined` when the body carried neither field.
57
+ */
58
+ function parseUpstreamError(text) {
59
+ let error;
60
+ try {
61
+ error = JSON.parse(text)?.error;
62
+ }
63
+ catch (_error) {
64
+ // Not JSON (a proxy's error page, plain text): a short body is the message itself.
65
+ const trimmed = text.trim();
66
+ return trimmed && trimmed.length <= 500 ? { message: trimmed } : undefined;
67
+ }
68
+ const type = typeof error?.type === 'string'
69
+ ? error.type
70
+ : typeof error?.code === 'string'
71
+ ? error.code
72
+ : undefined;
73
+ const message = typeof error?.message === 'string' ? error.message.slice(0, 500) : undefined;
74
+ if (!type && !message)
75
+ return undefined;
76
+ return { ...(type ? { type } : {}), ...(message ? { message } : {}) };
77
+ }
25
78
  /**
26
79
  * Moonshot (Kimi) AI provider that implements the `AIProvider` interface
27
80
  * using Moonshot's OpenAI-compatible Chat Completions API with support
@@ -36,6 +89,7 @@ class MoonshotAIProvider {
36
89
  completionsPath;
37
90
  modelMap;
38
91
  onRateLimit;
92
+ rateLimitRetries;
39
93
  constructor(config = {}) {
40
94
  this.apiKey = config.apiKey ?? process.env.MOONSHOT_API_KEY ?? '';
41
95
  this.defaultModel = config.defaultModel ?? 'kimi-k3.1-pro-highspeed';
@@ -45,6 +99,15 @@ class MoonshotAIProvider {
45
99
  config.completionsPath ?? process.env.MOONSHOT_COMPLETIONS_PATH ?? '/v1/chat/completions';
46
100
  this.modelMap = config.modelMap ?? {};
47
101
  this.onRateLimit = config.onRateLimit;
102
+ const rateLimitRetries = config.rateLimitRetries ?? 3;
103
+ if (rateLimitRetries !== 'until-aborted' &&
104
+ (typeof rateLimitRetries !== 'number' ||
105
+ !Number.isFinite(rateLimitRetries) ||
106
+ !Number.isInteger(rateLimitRetries) ||
107
+ rateLimitRetries < 0)) {
108
+ throw new TypeError("Moonshot rateLimitRetries must be a nonnegative finite integer or 'until-aborted'.");
109
+ }
110
+ this.rateLimitRetries = rateLimitRetries;
48
111
  // Fail fast with an actionable local error rather than a cryptic 401 on the
49
112
  // first request. The default `provider` export constructs lazily on first
50
113
  // use (see index.ts), so this surfaces the moment the provider is actually
@@ -60,6 +123,9 @@ class MoonshotAIProvider {
60
123
  * @yields {ChatEvent} Chat events including text chunks, tool use requests, done signals, and errors.
61
124
  */
62
125
  async *chat(params) {
126
+ if (this.rateLimitRetries === 'until-aborted' && !params.signal) {
127
+ throw new TypeError("Moonshot rateLimitRetries 'until-aborted' requires params.signal for caller cancellation.");
128
+ }
63
129
  // Canonical catalog id (used everywhere else); translate to the upstream's
64
130
  // id only for the outbound request body via `modelMap`.
65
131
  const canonicalModel = params.model ?? this.defaultModel;
@@ -163,18 +229,40 @@ class MoonshotAIProvider {
163
229
  // params.signal if a tighter budget is needed.
164
230
  const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000;
165
231
  const signal = params.signal ?? AbortSignal.timeout(DEFAULT_TIMEOUT_MS);
166
- // Retry with exponential backoff for rate limits (429) and overloaded (503)
167
- const MAX_RETRIES = 3;
232
+ // Retry the SAME serialized request with capped, jittered exponential
233
+ // backoff for rate limits (429) and overloaded (503) responses.
234
+ const serializedBody = JSON.stringify(body);
168
235
  let response = null;
169
- for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
236
+ let rejectedBody;
237
+ for (let attempt = 0; this.rateLimitRetries === 'until-aborted' || attempt <= this.rateLimitRetries; attempt++) {
238
+ signal.throwIfAborted();
239
+ rejectedBody = undefined;
170
240
  response = await fetch(`${this.baseUrl}${this.completionsPath}`, {
171
241
  method: 'POST',
172
242
  headers,
173
- body: JSON.stringify(body),
243
+ body: serializedBody,
174
244
  signal,
175
245
  });
176
246
  if (response.status === 429 || response.status === 503) {
177
- const willRetry = attempt < MAX_RETRIES;
247
+ // Read the body once: an unread body pins its connection, and only the
248
+ // body says whether a 429 is a rate limit or an exhausted balance.
249
+ try {
250
+ rejectedBody = await response.text();
251
+ }
252
+ catch (error) {
253
+ // Caller cancellation still ends the request; any other read failure only
254
+ // loses the reason, so the body counts as read and the retry policy goes on.
255
+ signal.throwIfAborted();
256
+ logger.debug('Moonshot rejected response body could not be read', { error });
257
+ rejectedBody = '';
258
+ }
259
+ const upstreamError = parseUpstreamError(rejectedBody);
260
+ // An exhausted balance does not recover by waiting: a bounded retry
261
+ // budget fails at once, while 'until-aborted' keeps the same request
262
+ // pending so a long-running caller resumes when the account is recharged.
263
+ const quotaExhausted = upstreamError?.type === QUOTA_EXHAUSTED_TYPE;
264
+ const willRetry = this.rateLimitRetries === 'until-aborted' ||
265
+ (!quotaExhausted && attempt < this.rateLimitRetries);
178
266
  // Retry-After is equally-valid as delta-seconds or an HTTP-date;
179
267
  // parseInt on the date form yields NaN, degrading the backoff to a
180
268
  // ~0ms retry against an already rate-limiting API. Guard it.
@@ -197,6 +285,7 @@ class MoonshotAIProvider {
197
285
  willRetry,
198
286
  retryInMs: delayMs,
199
287
  ...(hasRetryAfter ? { retryAfterSeconds: parsedRetryAfterSeconds } : {}),
288
+ ...(upstreamError ? { upstreamError } : {}),
200
289
  });
201
290
  }
202
291
  catch (error) {
@@ -204,27 +293,23 @@ class MoonshotAIProvider {
204
293
  logger.warn('onRateLimit callback threw', { error });
205
294
  }
206
295
  if (willRetry) {
207
- logger.warn('Moonshot API rate limited, retrying', {
296
+ logger.warn(quotaExhausted
297
+ ? 'Moonshot account balance exhausted, retrying until recharged'
298
+ : 'Moonshot API rate limited, retrying', {
208
299
  status: response.status,
209
300
  attempt: attempt + 1,
210
301
  delayMs,
302
+ ...(upstreamError ? { upstreamError } : {}),
211
303
  });
212
- await new Promise((resolve) => {
213
- const timer = setTimeout(resolve, delayMs);
214
- signal.addEventListener('abort', () => {
215
- clearTimeout(timer);
216
- resolve();
217
- }, { once: true });
218
- });
219
- if (signal.aborted)
220
- break;
304
+ await waitForRetry(delayMs, signal);
221
305
  continue;
222
306
  }
223
307
  }
224
308
  break;
225
309
  }
226
310
  if (!response.ok) {
227
- const errorBody = await response.text();
311
+ // A 429/503 body was already read by the retry loop; a body reads only once.
312
+ const errorBody = rejectedBody ?? (await response.text());
228
313
  let detail = `HTTP ${response.status}`;
229
314
  try {
230
315
  const parsed = JSON.parse(errorBody);
@@ -237,18 +322,20 @@ class MoonshotAIProvider {
237
322
  detail = errorBody;
238
323
  }
239
324
  logger.error('Moonshot API error', { status: response.status, detail, errorBody });
240
- const clientMessage = response.status === 429
241
- ? 'AI rate limit exceeded. Please try again shortly.'
242
- : response.status === 401
243
- ? 'AI service configuration error.'
244
- : response.status === 400 &&
245
- /prompt is too long|too many tokens|token.*limit|context.*length/i.test(detail)
246
- ? "Conversation too long for the model's context window. Use /compact to free space, or start a new conversation."
247
- : response.status === 400
248
- ? 'AI request was invalid — check the model and request parameters.'
249
- : response.status === 503
250
- ? 'AI service is temporarily overloaded. Please try again in a moment.'
251
- : 'AI service error. Please try again.';
325
+ const clientMessage = response.status === 429 && parseUpstreamError(errorBody)?.type === QUOTA_EXHAUSTED_TYPE
326
+ ? 'AI service is unavailable right now. Please try again later.'
327
+ : response.status === 429
328
+ ? 'AI rate limit exceeded. Please try again shortly.'
329
+ : response.status === 401
330
+ ? 'AI service configuration error.'
331
+ : response.status === 400 &&
332
+ /prompt is too long|too many tokens|token.*limit|context.*length/i.test(detail)
333
+ ? "Conversation too long for the model's context window. Use /compact to free space, or start a new conversation."
334
+ : response.status === 400
335
+ ? 'AI request was invalid — check the model and request parameters.'
336
+ : response.status === 503
337
+ ? 'AI service is temporarily overloaded. Please try again in a moment.'
338
+ : 'AI service error. Please try again.';
252
339
  yield { type: 'error', message: clientMessage, errorKey: 'ai.error.apiError' };
253
340
  return;
254
341
  }
package/dist/types.d.ts CHANGED
@@ -4,6 +4,8 @@
4
4
  * @module
5
5
  */
6
6
  import type { AiRateLimitCallback } from '@molecule/api-ai';
7
+ /** Retry policy for transient HTTP 429/503 responses. A number counts retries after the first POST. */
8
+ export type MoonshotRateLimitRetries = number | 'until-aborted';
7
9
  /**
8
10
  * Configuration for Moonshot.
9
11
  */
@@ -14,7 +16,7 @@ export interface MoonshotConfig {
14
16
  defaultModel?: string;
15
17
  /** Maximum tokens for completions. */
16
18
  maxTokens?: number;
17
- /** Base URL override (for proxies). Defaults to 'https://api.moonshot.cn'. */
19
+ /** Base URL override (for proxies). Defaults to 'https://api.moonshot.ai'. */
18
20
  baseUrl?: string;
19
21
  /**
20
22
  * Chat-completions path appended to {@link baseUrl}. Defaults to
@@ -34,6 +36,12 @@ export interface MoonshotConfig {
34
36
  modelMap?: Record<string, string>;
35
37
  /** Called on each rate-limited/overloaded upstream response, before any retry sleep. */
36
38
  onRateLimit?: AiRateLimitCallback;
39
+ /**
40
+ * Transient 429/503 retries after the initial request. Defaults to the historical three.
41
+ * `'until-aborted'` keeps replaying the identical request and requires every chat call to
42
+ * supply its own cancellation signal; permanent failures such as HTTP 400/401 are never retried.
43
+ */
44
+ rateLimitRetries?: MoonshotRateLimitRetries;
37
45
  }
38
46
  /**
39
47
  * Process Env interface.
@@ -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;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACjC,wFAAwF;IACxF,WAAW,CAAC,EAAE,mBAAmB,CAAA;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,gBAAgB,EAAE,MAAM,CAAA;IACxB,0FAA0F;IAC1F,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,mFAAmF;IACnF,yBAAyB,CAAC,EAAE,MAAM,CAAA;CACnC"}
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,uGAAuG;AACvG,MAAM,MAAM,wBAAwB,GAAG,MAAM,GAAG,eAAe,CAAA;AAE/D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACjC,wFAAwF;IACxF,WAAW,CAAC,EAAE,mBAAmB,CAAA;IACjC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,wBAAwB,CAAA;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,gBAAgB,EAAE,MAAM,CAAA;IACxB,0FAA0F;IAC1F,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,mFAAmF;IACnF,yBAAyB,CAAC,EAAE,MAAM,CAAA;CACnC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/api-ai-moonshot",
3
- "version": "1.1.7",
3
+ "version": "1.3.0",
4
4
  "description": "Moonshot (Kimi) AI provider for molecule.dev",
5
5
  "homepage": "https://www.molecule.dev/packages/api-ai-moonshot",
6
6
  "type": "module",
@@ -34,8 +34,8 @@
34
34
  "directory": "packages/api/bonds/ai/moonshot"
35
35
  },
36
36
  "devDependencies": {
37
- "@molecule/api-ai": "1.3.5",
38
- "@molecule/api-bond": "1.0.3",
37
+ "@molecule/api-ai": "1.5.0",
38
+ "@molecule/api-bond": "1.0.4",
39
39
  "@types/node": "26.6.5",
40
40
  "typescript": "6.0.3",
41
41
  "vitest": "4.1.12"