@molecule/api-ai-deepseek 1.1.2 → 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,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;IA0UzD;;;;;;;;;;;;;;;;;;OAkBG;IACH,wBAAwB,CAAC,KAAK,EAAE,cAAc,GAAG,uBAAuB;IAQxE;;;;;;;;;OASG;YACW,2BAA2B;IAgKzC;;;;;;;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,19 @@ 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 restartCeiling = () => {
420
+ if (ceiling)
421
+ clearTimeout(ceiling);
422
+ ceiling = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
423
+ ceiling.unref?.();
424
+ };
425
+ restartCeiling();
414
426
  try {
415
427
  let response;
416
428
  let requestSentAt = 0;
@@ -423,6 +435,11 @@ class DeepseekAIProviderImpl {
423
435
  headers,
424
436
  model,
425
437
  controller,
438
+ restartCeiling,
439
+ // A credit wait lasts until the caller cancels, so only a call that
440
+ // CAN be cancelled waits; any other 402 still fails at once.
441
+ waitForCredit: this.waitForCredit && params.signal !== undefined,
442
+ onProviderWait: params.onProviderWait,
426
443
  // The first-token window covers an attempt that never receives
427
444
  // response HEADERS too, not only one that receives them and then
428
445
  // sends no content: a window that started at the headers left the
@@ -586,7 +603,8 @@ class DeepseekAIProviderImpl {
586
603
  return;
587
604
  }
588
605
  finally {
589
- clearTimeout(ceiling);
606
+ if (ceiling)
607
+ clearTimeout(ceiling);
590
608
  params.signal?.removeEventListener('abort', forwardAbort);
591
609
  }
592
610
  }
@@ -631,7 +649,7 @@ class DeepseekAIProviderImpl {
631
649
  * @returns The response and the final dispatch send time (deliberate backoff excluded).
632
650
  */
633
651
  async requestWithRateLimitRetries(args) {
634
- const { body, headers, model, controller, firstTokenTimeoutMs } = args;
652
+ const { body, headers, model, controller, firstTokenTimeoutMs, restartCeiling } = args;
635
653
  const signal = controller.signal;
636
654
  // Retry with exponential backoff for rate limits (429) and overloaded (503)
637
655
  const MAX_RETRIES = 3;
@@ -641,7 +659,13 @@ class DeepseekAIProviderImpl {
641
659
  // on a 429/503: a body reads only once, so the caller must reuse this text
642
660
  // instead of asking the response for it a second time (which throws).
643
661
  let rejectedBody;
644
- for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
662
+ // Credit waits are counted apart from the rate-limit budget: an empty account
663
+ // recovers only when someone tops it up, so its wait is bounded by the
664
+ // caller's signal, never by MAX_RETRIES.
665
+ let creditWaits = 0;
666
+ for (let attempt = 0, dispatches = 0; attempt <= MAX_RETRIES; dispatches++) {
667
+ if (dispatches > 0)
668
+ restartCeiling?.();
645
669
  // Reset per attempt: only THIS attempt's rejection has been read.
646
670
  rejectedBody = undefined;
647
671
  // Bound THIS dispatch, not the retry loop: a deliberate backoff sleep is
@@ -666,7 +690,10 @@ class DeepseekAIProviderImpl {
666
690
  if (headerDeadline)
667
691
  clearTimeout(headerDeadline);
668
692
  }
669
- if (response.status === 429 || response.status === 503) {
693
+ // An empty account (402) is held only under waitForCredit; otherwise it
694
+ // falls through to the caller's "provider credit balance too low" error.
695
+ const creditWait = response.status === 402 && args.waitForCredit === true;
696
+ if (response.status === 429 || response.status === 503 || creditWait) {
670
697
  // Read the body once: an unread body pins its connection, and only the
671
698
  // body says what the upstream actually refused the request for.
672
699
  try {
@@ -681,7 +708,10 @@ class DeepseekAIProviderImpl {
681
708
  rejectedBody = '';
682
709
  }
683
710
  const upstreamError = parseUpstreamError(rejectedBody);
684
- const willRetry = attempt < MAX_RETRIES;
711
+ const willRetry = creditWait || attempt < MAX_RETRIES;
712
+ // The backoff step: this wait's own count, so credit waits and rate
713
+ // limits never lengthen each other's delays.
714
+ const step = creditWait ? creditWaits : attempt;
685
715
  // Retry-After is equally-valid as delta-seconds or an HTTP-date;
686
716
  // parseInt on the date form yields NaN, degrading the backoff to a
687
717
  // ~0ms retry against an already rate-limiting API. Guard it.
@@ -693,31 +723,45 @@ class DeepseekAIProviderImpl {
693
723
  const delayMs = willRetry
694
724
  ? (hasRetryAfter
695
725
  ? Math.min(parsedRetryAfterSeconds * 1000, 60_000)
696
- : Math.min(1000 * 2 ** attempt, 30_000)) + Math.floor(Math.random() * 500)
726
+ : Math.min(1000 * 2 ** step, 30_000)) + Math.floor(Math.random() * 500)
697
727
  : 0;
728
+ const event = {
729
+ provider: this.name,
730
+ model,
731
+ status: response.status,
732
+ attempt: step + 1,
733
+ willRetry,
734
+ retryInMs: delayMs,
735
+ ...(hasRetryAfter ? { retryAfterSeconds: parsedRetryAfterSeconds } : {}),
736
+ ...(upstreamError ? { upstreamError } : {}),
737
+ };
698
738
  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
- });
739
+ this.onRateLimit?.(event);
709
740
  }
710
741
  catch (error) {
711
742
  // Host-app telemetry; its failure must never break the request.
712
743
  logger.warn('onRateLimit callback threw', { error });
713
744
  }
714
745
  if (willRetry) {
715
- logger.warn('DeepSeek API rate limited, retrying', {
746
+ try {
747
+ args.onProviderWait?.(event);
748
+ }
749
+ catch (error) {
750
+ // The caller's liveness/status hook; its failure must never break the request.
751
+ logger.warn('onProviderWait callback threw', { error });
752
+ }
753
+ logger.warn(creditWait
754
+ ? 'DeepSeek account balance exhausted, waiting for credit'
755
+ : 'DeepSeek API rate limited, retrying', {
716
756
  status: response.status,
717
- attempt: attempt + 1,
757
+ attempt: step + 1,
718
758
  delayMs,
719
759
  ...(upstreamError ? { upstreamError } : {}),
720
760
  });
761
+ if (creditWait)
762
+ creditWaits++;
763
+ else
764
+ attempt++;
721
765
  // A host may cancel inside onRateLimit, before a backoff listener exists.
722
766
  signal.throwIfAborted();
723
767
  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.0",
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",