@molecule/api-ai-deepseek 1.1.0 → 1.1.1

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-10-16T23:28:16.072Z
+Generated: 2026-10-27T11:22:37.877Z
 -->
 
 # @molecule/api-ai-deepseek
@@ -225,8 +225,10 @@ malformed tool schema) gets its own non-retryable message distinct from the gene
 **A stream that opens and then produces nothing is bounded, not waited on.** DeepSeek answers
 200 and then keeps a stalled prefill alive with `: keep-alive` comments, so no HTTP status is
 ever wrong and a byte-level idle timeout never sees the stall. `chat()` therefore bounds the
-wait for the first CONTENT event (45 s, `MOL_DEEPSEEK_FIRST_TOKEN_TIMEOUT_MS`) and asks once
-more with a fresh stream; after the reply has started it bounds the silence between chunks
+wait for the first CONTENT event (45 s, `MOL_DEEPSEEK_FIRST_TOKEN_TIMEOUT_MS`) — a window that
+starts when the request is sent, so it also bounds an attempt whose response HEADERS never
+arrive — and asks once more with a fresh stream; after the reply has started it bounds the
+silence between chunks
 instead (60 s, `MOL_DEEPSEEK_STREAM_SILENCE_TIMEOUT_MS`) and surfaces an error event, keeping
 the partial reply. Hosts observe both through the `onStreamStall` callback.
 

package/dist/index.d.ts

@@ -34,8 +34,10 @@
  * **A stream that opens and then produces nothing is bounded, not waited on.** DeepSeek answers
  * 200 and then keeps a stalled prefill alive with `: keep-alive` comments, so no HTTP status is
  * ever wrong and a byte-level idle timeout never sees the stall. `chat()` therefore bounds the
- * wait for the first CONTENT event (45 s, `MOL_DEEPSEEK_FIRST_TOKEN_TIMEOUT_MS`) and asks once
- * more with a fresh stream; after the reply has started it bounds the silence between chunks
+ * wait for the first CONTENT event (45 s, `MOL_DEEPSEEK_FIRST_TOKEN_TIMEOUT_MS`) — a window that
+ * starts when the request is sent, so it also bounds an attempt whose response HEADERS never
+ * arrive — and asks once more with a fresh stream; after the reply has started it bounds the
+ * silence between chunks
  * instead (60 s, `MOL_DEEPSEEK_STREAM_SILENCE_TIMEOUT_MS`) and surfaces an error event, keeping
  * the partial reply. Hosts observe both through the `onStreamStall` callback.
  *

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;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

@@ -34,8 +34,10 @@
  * **A stream that opens and then produces nothing is bounded, not waited on.** DeepSeek answers
  * 200 and then keeps a stalled prefill alive with `: keep-alive` comments, so no HTTP status is
  * ever wrong and a byte-level idle timeout never sees the stall. `chat()` therefore bounds the
- * wait for the first CONTENT event (45 s, `MOL_DEEPSEEK_FIRST_TOKEN_TIMEOUT_MS`) and asks once
- * more with a fresh stream; after the reply has started it bounds the silence between chunks
+ * wait for the first CONTENT event (45 s, `MOL_DEEPSEEK_FIRST_TOKEN_TIMEOUT_MS`) — a window that
+ * starts when the request is sent, so it also bounds an attempt whose response HEADERS never
+ * arrive — and asks once more with a fresh stream; after the reply has started it bounds the
+ * silence between chunks
  * instead (60 s, `MOL_DEEPSEEK_STREAM_SILENCE_TIMEOUT_MS`) and surfaces an error event, keeping
  * the partial reply. Hosts observe both through the `onStreamStall` callback.
  *

package/dist/provider.d.ts

@@ -66,7 +66,7 @@ declare class DeepseekAIProviderImpl implements AIProvider {
      * them in one loop made each one's attempt count depend on the other's.
      *
      * @param args - The request body, headers, upstream model and abort signal.
-     * @returns The upstream response (possibly a 429/503 that exhausted retries).
+     * @returns The response and the final dispatch send time (deliberate backoff excluded).
      */
     private requestWithRateLimitRetries;
     /**

package/dist/provider.d.ts.map

@@ -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;AAgHhD,8DAA8D;AAC9D,eAAO,MAAM,8BAA8B,QAAS,CAAA;AA+LpD;;;;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;IAoRzD;;;;;;;;;;;;;;;;;;OAkBG;IACH,wBAAwB,CAAC,KAAK,EAAE,cAAc,GAAG,uBAAuB;IAQxE;;;;;;;;;OASG;YACW,2BAA2B;IA0EzC;;;;;;;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"}
+{"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;AAgHhD,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;IAsTzD;;;;;;;;;;;;;;;;;;OAkBG;IACH,wBAAwB,CAAC,KAAK,EAAE,cAAc,GAAG,uBAAuB;IAQxE;;;;;;;;;OASG;YACW,2BAA2B;IA4GzC;;;;;;;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

@@ -198,6 +198,22 @@ function isContentEvent(event) {
         event.type === 'tool_use_start' ||
         event.type === 'tool_input_delta');
 }
+/**
+ * The first-token window expired before response HEADERS arrived.
+ *
+ * Module-private: the only consumer is this provider's own stall loop, which
+ * reports it in the existing `before_content` shape and asks once more. It is
+ * never thrown for a caller cancellation — a caller abort (or the whole-attempt
+ * ceiling) outranks the window and is re-thrown untouched.
+ */
+class FirstTokenHeaderTimeoutError extends Error {
+    boundMs;
+    constructor(boundMs) {
+        super(`DeepSeek sent no response headers within ${boundMs} ms`);
+        this.boundMs = boundMs;
+        this.name = 'FirstTokenHeaderTimeoutError';
+    }
+}
 /**
  * DeepSeek AI provider that implements the `AIProvider` interface using
  * DeepSeek's OpenAI-compatible Chat Completions API with support for streaming,
@@ -368,14 +384,47 @@ class DeepseekAIProviderImpl {
             // present, still wins over it (both abort this one controller).
             const ceiling = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
             ceiling.unref?.();
-            const signal = controller.signal;
             try {
-                const response = await this.requestWithRateLimitRetries({
-                    body,
-                    headers,
-                    model,
-                    signal,
-                });
+                let response;
+                let requestSentAt = 0;
+                try {
+                    const dispatched = await this.requestWithRateLimitRetries({
+                        body,
+                        headers,
+                        model,
+                        controller,
+                        // The first-token window covers an attempt that never receives
+                        // response HEADERS too, not only one that receives them and then
+                        // sends no content: a window that started at the headers left the
+                        // whole pre-header phase to the five-minute attempt ceiling alone.
+                        // Passing it only while streaming keeps the non-streaming path —
+                        // which has no first token to wait for — on that ceiling.
+                        ...(params.stream === false ? {} : { firstTokenTimeoutMs }),
+                    });
+                    response = dispatched.response;
+                    requestSentAt = dispatched.sentAt;
+                }
+                catch (error) {
+                    if (!(error instanceof FirstTokenHeaderTimeoutError) || params.signal?.aborted)
+                        throw error;
+                    // Nothing reached the consumer, so the same once-only re-ask a
+                    // post-header stall gets is safe here too — reported in the
+                    // established `before_content` shape, so hosts and analytics see one
+                    // kind of stall either way.
+                    const willRetry = stalledAttempt < MAX_STALL_RETRIES;
+                    this.reportStreamStall(model, {
+                        stallMs: error.boundMs,
+                        attempt: stalledAttempt + 1,
+                        willRetry,
+                        streamedChars: 0,
+                        keepAlives: 0,
+                        phase: 'before_content',
+                    });
+                    if (willRetry)
+                        continue;
+                    yield { type: 'error', message: t('ai.error.apiError'), errorKey: 'ai.error.apiError' };
+                    return;
+                }
                 // Whatever the transport exposes about this call. DeepSeek's edge
                 // answers with `x-ds-trace-id`; other OpenAI-compatible hosts use
                 // `x-request-id`. Recorded rather than read for control flow: it is the
@@ -467,14 +516,17 @@ class DeepseekAIProviderImpl {
                         controller.abort();
                     }, ms);
                 };
-                armBound(firstTokenTimeoutMs, 'before_content');
+                // Headers and content share this dispatch's existing first-token window.
+                // A 429/503 retry has its own send time; deliberate backoff is excluded.
+                armBound(Math.max(0, firstTokenTimeoutMs - (Date.now() - requestSentAt)), 'before_content');
+                bounds.windowStartedAt = requestSentAt;
                 try {
                     yield* this.parseStreamingResponse(response, state, { silenceMs: this.streamSilenceTimeoutMs, arm: armBound }, call);
                 }
                 catch (error) {
                     // Only a bound expiry is this provider's to absorb — anything else
                     // (the caller aborting, a socket failure) belongs to the caller.
-                    if (!bounds.expired)
+                    if (!bounds.expired || params.signal?.aborted)
                         throw error;
                     const stall = {
                         stallMs: Date.now() - bounds.windowStartedAt,
@@ -543,20 +595,38 @@ class DeepseekAIProviderImpl {
      * them in one loop made each one's attempt count depend on the other's.
      *
      * @param args - The request body, headers, upstream model and abort signal.
-     * @returns The upstream response (possibly a 429/503 that exhausted retries).
+     * @returns The response and the final dispatch send time (deliberate backoff excluded).
      */
     async requestWithRateLimitRetries(args) {
-        const { body, headers, model, signal } = args;
+        const { body, headers, model, controller, firstTokenTimeoutMs } = args;
+        const signal = controller.signal;
         // Retry with exponential backoff for rate limits (429) and overloaded (503)
         const MAX_RETRIES = 3;
         let response = null;
+        let sentAt = 0;
         for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-            response = await fetch(`${this.baseUrl}${this.completionsPath}`, {
-                method: 'POST',
-                headers,
-                body: JSON.stringify(body),
-                signal,
-            });
+            // Bound THIS dispatch, not the retry loop: a deliberate backoff sleep is
+            // this provider's own wait, so no window is running while it is spent.
+            let headerDeadline = null;
+            sentAt = Date.now();
+            if (firstTokenTimeoutMs !== undefined) {
+                headerDeadline = setTimeout(() => controller.abort(new FirstTokenHeaderTimeoutError(firstTokenTimeoutMs)), firstTokenTimeoutMs);
+                headerDeadline.unref?.();
+            }
+            try {
+                response = await fetch(`${this.baseUrl}${this.completionsPath}`, {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify(body),
+                    signal,
+                });
+            }
+            finally {
+                // Release the header timer when fetch settles. The successful SSE reader
+                // uses the remaining window; a rate-limit retry starts a new dispatch.
+                if (headerDeadline)
+                    clearTimeout(headerDeadline);
+            }
             if (response.status === 429 || response.status === 503) {
                 const willRetry = attempt < MAX_RETRIES;
                 // Retry-After is equally-valid as delta-seconds or an HTTP-date;
@@ -593,21 +663,24 @@ class DeepseekAIProviderImpl {
                         attempt: attempt + 1,
                         delayMs,
                     });
+                    // A host may cancel inside onRateLimit, before a backoff listener exists.
+                    signal.throwIfAborted();
                     await new Promise((resolve) => {
-                        const timer = setTimeout(resolve, delayMs);
-                        signal.addEventListener('abort', () => {
+                        const finish = () => {
                             clearTimeout(timer);
+                            signal.removeEventListener('abort', finish);
                             resolve();
-                        }, { once: true });
+                        };
+                        const timer = setTimeout(finish, delayMs);
+                        signal.addEventListener('abort', finish, { once: true });
                     });
-                    if (signal.aborted)
-                        break;
+                    signal.throwIfAborted();
                     continue;
                 }
             }
             break;
         }
-        return response;
+        return { response: response, sentAt };
     }
     /**
      * Record one stalled attempt: a warn line always, plus the host's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-ai-deepseek",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "DeepSeek AI provider for molecule.dev",
   "homepage": "https://www.molecule.dev/packages/api-ai-deepseek",
   "type": "module",
@@ -34,7 +34,7 @@
   },
   "devDependencies": {
     "@molecule/api-ai": "1.4.0",
-    "@molecule/api-bond": "1.0.3",
+    "@molecule/api-bond": "1.0.4",
     "@types/node": "26.6.5",
     "typescript": "6.0.3",
     "vitest": "4.1.12"