@molecule/api-ai-deepseek 1.1.2 → 1.2.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-27T11:22:37.877Z
6
+ Generated: 2026-11-05T09:06:10.027Z
7
7
  -->
8
8
 
9
9
  # @molecule/api-ai-deepseek
@@ -80,6 +80,19 @@ interface DeepseekConfig {
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
+ * Keep a request whose account has no balance left (HTTP 402) and send it
85
+ * again until the account is topped up, instead of failing it. Defaults to
86
+ * false: a 402 ends the request with "provider credit balance too low".
87
+ *
88
+ * The wait lasts until the CALLER cancels, so it applies only to a call that
89
+ * passes `params.signal`; a call without one still fails at once, because
90
+ * nothing could end its wait. The same serialized request is re-sent, so a
91
+ * long-running caller loses no conversation or tool result. Each wait is
92
+ * reported, before it starts, to `onRateLimit` and to the call's
93
+ * `params.onProviderWait` (status 402), backing off up to 30 s between tries.
94
+ */
95
+ waitForCredit?: boolean
83
96
  /** Called when a stream accepts the request and then produces no content for the whole first-token window. */
84
97
  onStreamStall?: AiStreamStallCallback
85
98
  /**
@@ -30,6 +30,7 @@ declare class DeepseekAIProviderImpl implements AIProvider {
30
30
  private onStreamStall?;
31
31
  private firstTokenTimeoutMs;
32
32
  private streamSilenceTimeoutMs;
33
+ private waitForCredit;
33
34
  constructor(config?: DeepseekConfig);
34
35
  /**
35
36
  * Sends a chat request and yields streamed events (text chunks, tool use, done/error).
@@ -1 +1 @@
1
- {"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EACV,UAAU,EAIV,SAAS,EAET,UAAU,EAEV,cAAc,EACd,uBAAuB,EAGxB,MAAM,kBAAkB,CAAA;AASzB,OAAO,cAAc,CAAA;AAErB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AA2IhD,8DAA8D;AAC9D,eAAO,MAAM,8BAA8B,QAAS,CAAA;AA8MpD;;;;GAIG;AACH,cAAM,sBAAuB,YAAW,UAAU;IAChD,QAAQ,CAAC,IAAI,cAAa;IAC1B,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,YAAY,CAAQ;IAC5B,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,eAAe,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAwB;IACxC,OAAO,CAAC,WAAW,CAAC,CAAqB;IACzC,OAAO,CAAC,aAAa,CAAC,CAAuB;IAC7C,OAAO,CAAC,mBAAmB,CAAQ;IACnC,OAAO,CAAC,sBAAsB,CAAQ;gBAE1B,MAAM,GAAE,cAAmB;IAwBvC;;;;;OAKG;IACI,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,CAAC,SAAS,CAAC;IA4TzD;;;;;;;;;;;;;;;;;;OAkBG;IACH,wBAAwB,CAAC,KAAK,EAAE,cAAc,GAAG,uBAAuB;IAQxE;;;;;;;;;OASG;YACW,2BAA2B;IAiIzC;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IA2BzB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,cAAc;IA8FtB;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAWnB;;;;;OAKG;IACH,OAAO,CAAE,yBAAyB;IA+ElC;;;;;;;OAOG;IACH,OAAO,CAAC,UAAU;IAUlB;;;;;;;;;;;;OAYG;YACY,sBAAsB;IA2GrC;;;;;;;;;;OAUG;IACH,OAAO,CAAE,eAAe;CAwOzB;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB,+BAAyB,CAAA;AAExD;;;;;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;;;;;;;;;GASG;AAKH,OAAO,KAAK,EACV,UAAU,EAIV,SAAS,EAET,UAAU,EAEV,cAAc,EACd,uBAAuB,EAGxB,MAAM,kBAAkB,CAAA;AASzB,OAAO,cAAc,CAAA;AAErB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AA2IhD,8DAA8D;AAC9D,eAAO,MAAM,8BAA8B,QAAS,CAAA;AA8MpD;;;;GAIG;AACH,cAAM,sBAAuB,YAAW,UAAU;IAChD,QAAQ,CAAC,IAAI,cAAa;IAC1B,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,YAAY,CAAQ;IAC5B,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,eAAe,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAwB;IACxC,OAAO,CAAC,WAAW,CAAC,CAAqB;IACzC,OAAO,CAAC,aAAa,CAAC,CAAuB;IAC7C,OAAO,CAAC,mBAAmB,CAAQ;IACnC,OAAO,CAAC,sBAAsB,CAAQ;IACtC,OAAO,CAAC,aAAa,CAAS;gBAElB,MAAM,GAAE,cAAmB;IAyBvC;;;;;OAKG;IACI,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,CAAC,SAAS,CAAC;IA+UzD;;;;;;;;;;;;;;;;;;OAkBG;IACH,wBAAwB,CAAC,KAAK,EAAE,cAAc,GAAG,uBAAuB;IAQxE;;;;;;;;;OASG;YACW,2BAA2B;IAsKzC;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IA2BzB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,cAAc;IA8FtB;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAWnB;;;;;OAKG;IACH,OAAO,CAAE,yBAAyB;IA+ElC;;;;;;;OAOG;IACH,OAAO,CAAC,UAAU;IAUlB;;;;;;;;;;;;OAYG;YACY,sBAAsB;IA2GrC;;;;;;;;;;OAUG;IACH,OAAO,CAAE,eAAe;CAwOzB;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB,+BAAyB,CAAA;AAExD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,UAAU,CAElE"}
package/dist/provider.js CHANGED
@@ -258,6 +258,7 @@ class DeepseekAIProviderImpl {
258
258
  onStreamStall;
259
259
  firstTokenTimeoutMs;
260
260
  streamSilenceTimeoutMs;
261
+ waitForCredit;
261
262
  constructor(config = {}) {
262
263
  this.apiKey = config.apiKey ?? process.env.DEEPSEEK_API_KEY ?? '';
263
264
  this.defaultModel = config.defaultModel ?? 'deepseek-flash';
@@ -270,6 +271,7 @@ class DeepseekAIProviderImpl {
270
271
  this.onStreamStall = config.onStreamStall;
271
272
  this.firstTokenTimeoutMs = resolveFirstTokenTimeoutMs(config.firstTokenTimeoutMs);
272
273
  this.streamSilenceTimeoutMs = resolveStreamSilenceTimeoutMs(config.streamSilenceTimeoutMs);
274
+ this.waitForCredit = config.waitForCredit === true;
273
275
  // Fail fast with an actionable local error rather than a cryptic 401 on the
274
276
  // first request. The default `provider` export constructs lazily on first
275
277
  // use (see index.ts), so this surfaces the moment the provider is actually
@@ -408,9 +410,23 @@ class DeepseekAIProviderImpl {
408
410
  else
409
411
  params.signal?.addEventListener('abort', forwardAbort, { once: true });
410
412
  // The provider's own ceiling bounds each ATTEMPT; the caller's signal, when
411
- // present, still wins over it (both abort this one controller).
412
- const ceiling = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
413
- ceiling.unref?.();
413
+ // present, still wins over it (both abort this one controller). It restarts
414
+ // with every dispatch of the request: a retry's backoff sleep is this
415
+ // provider's own deliberate wait, and a credit wait can last until the
416
+ // account is topped up, so neither may spend the ceiling of the dispatch
417
+ // that follows it.
418
+ let ceiling;
419
+ const pauseCeiling = () => {
420
+ if (ceiling)
421
+ clearTimeout(ceiling);
422
+ ceiling = undefined;
423
+ };
424
+ const restartCeiling = () => {
425
+ pauseCeiling();
426
+ ceiling = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
427
+ ceiling.unref?.();
428
+ };
429
+ restartCeiling();
414
430
  try {
415
431
  let response;
416
432
  let requestSentAt = 0;
@@ -423,6 +439,12 @@ class DeepseekAIProviderImpl {
423
439
  headers,
424
440
  model,
425
441
  controller,
442
+ restartCeiling,
443
+ pauseCeiling,
444
+ // A credit wait lasts until the caller cancels, so only a call that
445
+ // CAN be cancelled waits; any other 402 still fails at once.
446
+ waitForCredit: this.waitForCredit && params.signal !== undefined,
447
+ onProviderWait: params.onProviderWait,
426
448
  // The first-token window covers an attempt that never receives
427
449
  // response HEADERS too, not only one that receives them and then
428
450
  // sends no content: a window that started at the headers left the
@@ -586,7 +608,7 @@ class DeepseekAIProviderImpl {
586
608
  return;
587
609
  }
588
610
  finally {
589
- clearTimeout(ceiling);
611
+ pauseCeiling();
590
612
  params.signal?.removeEventListener('abort', forwardAbort);
591
613
  }
592
614
  }
@@ -631,7 +653,7 @@ class DeepseekAIProviderImpl {
631
653
  * @returns The response and the final dispatch send time (deliberate backoff excluded).
632
654
  */
633
655
  async requestWithRateLimitRetries(args) {
634
- const { body, headers, model, controller, firstTokenTimeoutMs } = args;
656
+ const { body, headers, model, controller, firstTokenTimeoutMs, restartCeiling } = args;
635
657
  const signal = controller.signal;
636
658
  // Retry with exponential backoff for rate limits (429) and overloaded (503)
637
659
  const MAX_RETRIES = 3;
@@ -641,7 +663,13 @@ class DeepseekAIProviderImpl {
641
663
  // on a 429/503: a body reads only once, so the caller must reuse this text
642
664
  // instead of asking the response for it a second time (which throws).
643
665
  let rejectedBody;
644
- for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
666
+ // Credit waits are counted apart from the rate-limit budget: an empty account
667
+ // recovers only when someone tops it up, so its wait is bounded by the
668
+ // caller's signal, never by MAX_RETRIES.
669
+ let creditWaits = 0;
670
+ for (let attempt = 0, dispatches = 0; attempt <= MAX_RETRIES; dispatches++) {
671
+ if (dispatches > 0)
672
+ restartCeiling?.();
645
673
  // Reset per attempt: only THIS attempt's rejection has been read.
646
674
  rejectedBody = undefined;
647
675
  // Bound THIS dispatch, not the retry loop: a deliberate backoff sleep is
@@ -666,7 +694,10 @@ class DeepseekAIProviderImpl {
666
694
  if (headerDeadline)
667
695
  clearTimeout(headerDeadline);
668
696
  }
669
- if (response.status === 429 || response.status === 503) {
697
+ // An empty account (402) is held only under waitForCredit; otherwise it
698
+ // falls through to the caller's "provider credit balance too low" error.
699
+ const creditWait = response.status === 402 && args.waitForCredit === true;
700
+ if (response.status === 429 || response.status === 503 || creditWait) {
670
701
  // Read the body once: an unread body pins its connection, and only the
671
702
  // body says what the upstream actually refused the request for.
672
703
  try {
@@ -681,7 +712,10 @@ class DeepseekAIProviderImpl {
681
712
  rejectedBody = '';
682
713
  }
683
714
  const upstreamError = parseUpstreamError(rejectedBody);
684
- const willRetry = attempt < MAX_RETRIES;
715
+ const willRetry = creditWait || attempt < MAX_RETRIES;
716
+ // The backoff step: this wait's own count, so credit waits and rate
717
+ // limits never lengthen each other's delays.
718
+ const step = creditWait ? creditWaits : attempt;
685
719
  // Retry-After is equally-valid as delta-seconds or an HTTP-date;
686
720
  // parseInt on the date form yields NaN, degrading the backoff to a
687
721
  // ~0ms retry against an already rate-limiting API. Guard it.
@@ -693,31 +727,49 @@ class DeepseekAIProviderImpl {
693
727
  const delayMs = willRetry
694
728
  ? (hasRetryAfter
695
729
  ? Math.min(parsedRetryAfterSeconds * 1000, 60_000)
696
- : Math.min(1000 * 2 ** attempt, 30_000)) + Math.floor(Math.random() * 500)
730
+ : Math.min(1000 * 2 ** step, 30_000)) + Math.floor(Math.random() * 500)
697
731
  : 0;
732
+ const event = {
733
+ provider: this.name,
734
+ model,
735
+ status: response.status,
736
+ attempt: step + 1,
737
+ willRetry,
738
+ retryInMs: delayMs,
739
+ ...(hasRetryAfter ? { retryAfterSeconds: parsedRetryAfterSeconds } : {}),
740
+ ...(upstreamError ? { upstreamError } : {}),
741
+ };
698
742
  try {
699
- this.onRateLimit?.({
700
- provider: this.name,
701
- model,
702
- status: response.status,
703
- attempt: attempt + 1,
704
- willRetry,
705
- retryInMs: delayMs,
706
- ...(hasRetryAfter ? { retryAfterSeconds: parsedRetryAfterSeconds } : {}),
707
- ...(upstreamError ? { upstreamError } : {}),
708
- });
743
+ this.onRateLimit?.(event);
709
744
  }
710
745
  catch (error) {
711
746
  // Host-app telemetry; its failure must never break the request.
712
747
  logger.warn('onRateLimit callback threw', { error });
713
748
  }
714
749
  if (willRetry) {
715
- logger.warn('DeepSeek API rate limited, retrying', {
750
+ // The rejected body is consumed: this dispatch is over. A slow
751
+ // response may have used almost its whole ceiling; that old timer
752
+ // must not cancel the backoff before the next dispatch can re-arm it.
753
+ args.pauseCeiling?.();
754
+ try {
755
+ args.onProviderWait?.(event);
756
+ }
757
+ catch (error) {
758
+ // The caller's liveness/status hook; its failure must never break the request.
759
+ logger.warn('onProviderWait callback threw', { error });
760
+ }
761
+ logger.warn(creditWait
762
+ ? 'DeepSeek account balance exhausted, waiting for credit'
763
+ : 'DeepSeek API rate limited, retrying', {
716
764
  status: response.status,
717
- attempt: attempt + 1,
765
+ attempt: step + 1,
718
766
  delayMs,
719
767
  ...(upstreamError ? { upstreamError } : {}),
720
768
  });
769
+ if (creditWait)
770
+ creditWaits++;
771
+ else
772
+ attempt++;
721
773
  // A host may cancel inside onRateLimit, before a backoff listener exists.
722
774
  signal.throwIfAborted();
723
775
  await new Promise((resolve) => {
package/dist/types.d.ts CHANGED
@@ -34,6 +34,19 @@ export interface DeepseekConfig {
34
34
  modelMap?: Record<string, string>;
35
35
  /** Called on each rate-limited/overloaded upstream response, before any retry sleep. */
36
36
  onRateLimit?: AiRateLimitCallback;
37
+ /**
38
+ * Keep a request whose account has no balance left (HTTP 402) and send it
39
+ * again until the account is topped up, instead of failing it. Defaults to
40
+ * false: a 402 ends the request with "provider credit balance too low".
41
+ *
42
+ * The wait lasts until the CALLER cancels, so it applies only to a call that
43
+ * passes `params.signal`; a call without one still fails at once, because
44
+ * nothing could end its wait. The same serialized request is re-sent, so a
45
+ * long-running caller loses no conversation or tool result. Each wait is
46
+ * reported, before it starts, to `onRateLimit` and to the call's
47
+ * `params.onProviderWait` (status 402), backing off up to 30 s between tries.
48
+ */
49
+ waitForCredit?: boolean;
37
50
  /** Called when a stream accepts the request and then produces no content for the whole first-token window. */
38
51
  onStreamStall?: AiStreamStallCallback;
39
52
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAElF;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,+EAA+E;IAC/E,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,8GAA8G;IAC9G,aAAa,CAAC,EAAE,qBAAqB,CAAA;IACrC;;;;;;;;;;OAUG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;;;;;;OASG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAA;CAChC;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,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAElF;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,+EAA+E;IAC/E,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;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,8GAA8G;IAC9G,aAAa,CAAC,EAAE,qBAAqB,CAAA;IACrC;;;;;;;;;;OAUG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;;;;;;OASG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAA;CAChC;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-deepseek",
3
- "version": "1.1.2",
3
+ "version": "1.2.1",
4
4
  "description": "DeepSeek AI provider for molecule.dev",
5
5
  "homepage": "https://www.molecule.dev/packages/api-ai-deepseek",
6
6
  "type": "module",
@@ -33,7 +33,7 @@
33
33
  "directory": "packages/api/bonds/ai/deepseek"
34
34
  },
35
35
  "devDependencies": {
36
- "@molecule/api-ai": "1.5.0",
36
+ "@molecule/api-ai": "1.6.0",
37
37
  "@molecule/api-bond": "1.0.4",
38
38
  "@types/node": "26.6.5",
39
39
  "typescript": "6.0.3",