@molecule/api-ai-moonshot 1.1.4 → 1.2.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-16T00:29:39.781Z
6
+ Generated: 2026-10-29T12:21:44.469Z
7
7
  -->
8
8
 
9
9
  # @molecule/api-ai-moonshot
10
10
 
11
+ Moonshot (Kimi) 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
- Moonshot (Kimi) AI provider for molecule.dev.
16
-
17
17
  ## Quick Start
18
18
 
19
19
  ```typescript
@@ -56,11 +56,11 @@ Configuration for Moonshot.
56
56
  interface MoonshotConfig {
57
57
  /** API key. Defaults to MOONSHOT_API_KEY env var. */
58
58
  apiKey?: string
59
- /** Default model. Defaults to 'kimi-k3'. */
59
+ /** Default model. Defaults to 'kimi-k3.1-pro-highspeed'. */
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;AAsvBhD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,UAAU,CAElE"}
package/dist/provider.js CHANGED
@@ -22,6 +22,30 @@ 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
+ }
25
49
  /**
26
50
  * Moonshot (Kimi) AI provider that implements the `AIProvider` interface
27
51
  * using Moonshot's OpenAI-compatible Chat Completions API with support
@@ -36,15 +60,25 @@ class MoonshotAIProvider {
36
60
  completionsPath;
37
61
  modelMap;
38
62
  onRateLimit;
63
+ rateLimitRetries;
39
64
  constructor(config = {}) {
40
65
  this.apiKey = config.apiKey ?? process.env.MOONSHOT_API_KEY ?? '';
41
- this.defaultModel = config.defaultModel ?? 'kimi-k3';
66
+ this.defaultModel = config.defaultModel ?? 'kimi-k3.1-pro-highspeed';
42
67
  this.maxTokens = config.maxTokens ?? 4096;
43
68
  this.baseUrl = config.baseUrl ?? process.env.MOONSHOT_BASE_URL ?? 'https://api.moonshot.ai';
44
69
  this.completionsPath =
45
70
  config.completionsPath ?? process.env.MOONSHOT_COMPLETIONS_PATH ?? '/v1/chat/completions';
46
71
  this.modelMap = config.modelMap ?? {};
47
72
  this.onRateLimit = config.onRateLimit;
73
+ const rateLimitRetries = config.rateLimitRetries ?? 3;
74
+ if (rateLimitRetries !== 'until-aborted' &&
75
+ (typeof rateLimitRetries !== 'number' ||
76
+ !Number.isFinite(rateLimitRetries) ||
77
+ !Number.isInteger(rateLimitRetries) ||
78
+ rateLimitRetries < 0)) {
79
+ throw new TypeError("Moonshot rateLimitRetries must be a nonnegative finite integer or 'until-aborted'.");
80
+ }
81
+ this.rateLimitRetries = rateLimitRetries;
48
82
  // Fail fast with an actionable local error rather than a cryptic 401 on the
49
83
  // first request. The default `provider` export constructs lazily on first
50
84
  // use (see index.ts), so this surfaces the moment the provider is actually
@@ -60,6 +94,9 @@ class MoonshotAIProvider {
60
94
  * @yields {ChatEvent} Chat events including text chunks, tool use requests, done signals, and errors.
61
95
  */
62
96
  async *chat(params) {
97
+ if (this.rateLimitRetries === 'until-aborted' && !params.signal) {
98
+ throw new TypeError("Moonshot rateLimitRetries 'until-aborted' requires params.signal for caller cancellation.");
99
+ }
63
100
  // Canonical catalog id (used everywhere else); translate to the upstream's
64
101
  // id only for the outbound request body via `modelMap`.
65
102
  const canonicalModel = params.model ?? this.defaultModel;
@@ -163,18 +200,20 @@ class MoonshotAIProvider {
163
200
  // params.signal if a tighter budget is needed.
164
201
  const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000;
165
202
  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;
203
+ // Retry the SAME serialized request with capped, jittered exponential
204
+ // backoff for rate limits (429) and overloaded (503) responses.
205
+ const serializedBody = JSON.stringify(body);
168
206
  let response = null;
169
- for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
207
+ for (let attempt = 0; this.rateLimitRetries === 'until-aborted' || attempt <= this.rateLimitRetries; attempt++) {
208
+ signal.throwIfAborted();
170
209
  response = await fetch(`${this.baseUrl}${this.completionsPath}`, {
171
210
  method: 'POST',
172
211
  headers,
173
- body: JSON.stringify(body),
212
+ body: serializedBody,
174
213
  signal,
175
214
  });
176
215
  if (response.status === 429 || response.status === 503) {
177
- const willRetry = attempt < MAX_RETRIES;
216
+ const willRetry = this.rateLimitRetries === 'until-aborted' || attempt < this.rateLimitRetries;
178
217
  // Retry-After is equally-valid as delta-seconds or an HTTP-date;
179
218
  // parseInt on the date form yields NaN, degrading the backoff to a
180
219
  // ~0ms retry against an already rate-limiting API. Guard it.
@@ -209,15 +248,7 @@ class MoonshotAIProvider {
209
248
  attempt: attempt + 1,
210
249
  delayMs,
211
250
  });
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;
251
+ await waitForRetry(delayMs, signal);
221
252
  continue;
222
253
  }
223
254
  }
package/dist/types.d.ts CHANGED
@@ -4,17 +4,19 @@
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
  */
10
12
  export interface MoonshotConfig {
11
13
  /** API key. Defaults to MOONSHOT_API_KEY env var. */
12
14
  apiKey?: string;
13
- /** Default model. Defaults to 'kimi-k3'. */
15
+ /** Default model. Defaults to 'kimi-k3.1-pro-highspeed'. */
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,4CAA4C;IAC5C,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.4",
3
+ "version": "1.2.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,11 +34,11 @@
34
34
  "directory": "packages/api/bonds/ai/moonshot"
35
35
  },
36
36
  "devDependencies": {
37
- "@molecule/api-ai": "1.3.3",
38
- "@molecule/api-bond": "1.0.2",
39
- "@types/node": "26.1.2",
37
+ "@molecule/api-ai": "1.4.0",
38
+ "@molecule/api-bond": "1.0.4",
39
+ "@types/node": "26.6.5",
40
40
  "typescript": "6.0.3",
41
- "vitest": "4.1.11"
41
+ "vitest": "4.1.12"
42
42
  },
43
43
  "peerDependencies": {
44
44
  "@molecule/api-ai": "^1.0.1",