@molecule/api-ai-deepseek 1.0.14 → 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

@@ -8,7 +8,7 @@
  *
  * @module
  */
-import type { AIProvider, ChatEvent, ChatParams } from '@molecule/api-ai';
+import type { AIProvider, ChatEvent, ChatParams, ImageInputSize, ImageInputTokenEstimate } from '@molecule/api-ai';
 import './secrets.js';
 import type { DeepseekConfig } from './types.js';
 /** How long a stream may wait for its first content event. */
@@ -38,6 +38,26 @@ declare class DeepseekAIProviderImpl implements AIProvider {
      * @yields {ChatEvent} Chat events including text chunks, tool use requests, done signals, and errors.
      */
     chat(params: ChatParams): AsyncIterable<ChatEvent>;
+    /**
+     * DeepSeek's own documented price for one image, in input tokens.
+     *
+     * Priced only when BOTH conditions hold: the request is going to DeepSeek's
+     * own documented endpoint ({@link isNativeDeepseekEndpoint}), and the model
+     * the wire will carry is a documented DeepSeek vision id. The alias is
+     * resolved exactly the way {@link chat} resolves it — the bond's `modelMap`
+     * first, a miss passing through unchanged — so a host that renames the model
+     * on the wire (a US re-host) is priced under the id it actually serves, and a
+     * custom endpoint that keeps the native names is still unknown because
+     * another backend does the billing. Anything else — another model, another
+     * format, another endpoint — is an explicit unknown rather than DeepSeek's
+     * ceiling.
+     *
+     * @param image - The selected catalog model id and the image's media type.
+     * @returns 1024 tokens per image for a documented vision model and a
+     *   supported format on DeepSeek's own endpoint, otherwise an explicit
+     *   unknown.
+     */
+    estimateImageInputTokens(image: ImageInputSize): ImageInputTokenEstimate;
     /**
      * POST the chat body, retrying with exponential backoff on a rate-limited
      * (429) or overloaded (503) status. Extracted from {@link chat} so the
@@ -46,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;AAIH,OAAO,KAAK,EACV,UAAU,EAIV,SAAS,EAET,UAAU,EAIX,MAAM,kBAAkB,CAAA;AASzB,OAAO,cAAc,CAAA;AAErB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAgHhD,8DAA8D;AAC9D,eAAO,MAAM,8BAA8B,QAAS,CAAA;AAgGpD;;;;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;;;;;;;;;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

@@ -9,6 +9,7 @@
  * @module
  */
 import { randomUUID } from 'node:crypto';
+import { URL } from 'node:url';
 import { getLogger } from '@molecule/api-bond';
 import { t } from '@molecule/api-i18n';
 const logger = getLogger();
@@ -41,6 +42,101 @@ const MAX_TIMER_MS = 2_147_483_647;
  * A longer list is sent truncated rather than refused by the API.
  */
 const MAX_STOP_SEQUENCES = 16;
+/**
+ * Model ids DeepSeek documents as accepting image input (vision guide, read
+ * 2026-10-25): `deepseek-flash` takes images alongside text, and the retired
+ * `deepseek-v4-flash-vision-exp` id is still accepted and served by the latest
+ * Flash model. Any other id — including one this bond's own `modelMap` sends to
+ * a different host — has no documented image rule, so it answers unknown.
+ *
+ * A documented id is necessary but not sufficient: the ceiling is a fact about
+ * DeepSeek's OWN backend, so it is applied only when the request is going to
+ * DeepSeek's own documented endpoint (see {@link isNativeDeepseekEndpoint}).
+ */
+const VISION_MODEL_IDS = ['deepseek-flash', 'deepseek-v4-flash-vision-exp'];
+/**
+ * The image formats the vision guide lists as supported: JPEG, PNG, GIF and
+ * WebP. A payload of any other type is not covered by the token rule.
+ */
+const VISION_MEDIA_TYPES = ['image/jpeg', 'image/png', 'image/gif', 'image/webp'];
+/**
+ * DeepSeek's documented ceiling for ONE image, in input tokens: the guide states
+ * "there is an upper bound of 1024 tokens per image", each image "counted
+ * independently under the same rule" with no separate multi-image calculation.
+ * Images below roughly 544×544 are scaled up and larger ones down to roughly
+ * 1300×1300, so the bound holds whatever the source dimensions are — including
+ * `detail: 'low'` (downscaled to 512×512) and `'original'`/`'auto'`.
+ *
+ * The request-level limits around it (32 MiB per base64 image, 8192 px per side,
+ * images in `user` messages only) reject an unusable request rather than change
+ * the price, so this bond prices the image alone and leaves message placement to
+ * the caller that knows it.
+ */
+const VISION_TOKENS_PER_IMAGE_UPPER_BOUND = 1024;
+/**
+ * The host DeepSeek documents as its own API endpoint. The per-image ceiling is
+ * a fact about THIS backend's accounting; the same model ids served by a
+ * gateway, a proxy or another OpenAI-compatible host are billed by that host's
+ * rule, which this bond cannot point at documentation for.
+ */
+const NATIVE_ENDPOINT_HOST = 'api.deepseek.com';
+/**
+ * The chat-completions path DeepSeek documents, in both of its published base
+ * URL forms: `https://api.deepseek.com` + `/chat/completions`, and
+ * `https://api.deepseek.com/v1` + `/chat/completions` (this bond's default is
+ * the root base with `/v1/chat/completions`).
+ */
+const NATIVE_COMPLETIONS_PATHS = ['/v1/chat/completions', '/chat/completions'];
+/**
+ * Whether the endpoint this bond will actually POST to is DeepSeek's own
+ * documented HTTPS endpoint.
+ *
+ * The documented per-image ceiling belongs to DeepSeek's backend, and a
+ * `baseUrl`, `DEEPSEEK_BASE_URL` or `completionsPath` can point this bond at a
+ * gateway, a proxy or another provider's OpenAI-compatible host. Model alias
+ * resolution alone cannot catch that: a custom endpoint may keep the native
+ * model names, so the wire still says `deepseek-flash` while another backend
+ * does the billing. Only the RESOLVED endpoint can say which backend it is.
+ *
+ * Parsed with the WHATWG URL parser, so the answer is about the endpoint as the
+ * request will be sent: https only, the exact hostname, no explicit
+ * non-default port (an explicit `:443` normalizes away, being the same
+ * endpoint), no credentials, no query or fragment, and a pathname equal to one
+ * of the two documented completions paths. Neither the parser nor the request
+ * normalizes duplicate or trailing slashes, so a base URL carrying one composes
+ * to a different path — `/v1/chat/completions/` or `//v1/chat/completions` —
+ * which is not native; anything else (another host, a port, a query, a
+ * fragment, an unparsable or relative URL) is not native either.
+ *
+ * Returns a boolean only: no part of the URL is logged, and nothing here reads,
+ * echoes or reports a credential.
+ *
+ * @param endpoint - The resolved request URL, `baseUrl + completionsPath`.
+ * @returns True only for DeepSeek's own documented endpoint.
+ */
+function isNativeDeepseekEndpoint(endpoint) {
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch (_error) {
+        // Not a URL this bond can reason about, so the documented rule does not
+        // apply. The caller answers unknown, which needs neither a log line nor an
+        // echo of the value that failed to parse.
+        return false;
+    }
+    if (url.protocol !== 'https:')
+        return false;
+    if (url.hostname !== NATIVE_ENDPOINT_HOST)
+        return false;
+    if (url.port !== '')
+        return false;
+    if (url.username !== '' || url.password !== '')
+        return false;
+    if (url.search !== '' || url.hash !== '')
+        return false;
+    return NATIVE_COMPLETIONS_PATHS.includes(url.pathname);
+}
 /**
  * Resolve a stream bound from the config, then the environment, then the
  * default. A value that is not a positive finite number is IGNORED rather than
@@ -102,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,
@@ -272,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
@@ -371,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,
@@ -410,6 +558,35 @@ class DeepseekAIProviderImpl {
             }
         }
     }
+    /**
+     * DeepSeek's own documented price for one image, in input tokens.
+     *
+     * Priced only when BOTH conditions hold: the request is going to DeepSeek's
+     * own documented endpoint ({@link isNativeDeepseekEndpoint}), and the model
+     * the wire will carry is a documented DeepSeek vision id. The alias is
+     * resolved exactly the way {@link chat} resolves it — the bond's `modelMap`
+     * first, a miss passing through unchanged — so a host that renames the model
+     * on the wire (a US re-host) is priced under the id it actually serves, and a
+     * custom endpoint that keeps the native names is still unknown because
+     * another backend does the billing. Anything else — another model, another
+     * format, another endpoint — is an explicit unknown rather than DeepSeek's
+     * ceiling.
+     *
+     * @param image - The selected catalog model id and the image's media type.
+     * @returns 1024 tokens per image for a documented vision model and a
+     *   supported format on DeepSeek's own endpoint, otherwise an explicit
+     *   unknown.
+     */
+    estimateImageInputTokens(image) {
+        if (!isNativeDeepseekEndpoint(`${this.baseUrl}${this.completionsPath}`))
+            return { known: false };
+        const upstream = this.modelMap[image.model] ?? image.model;
+        if (!VISION_MODEL_IDS.includes(upstream))
+            return { known: false };
+        if (!VISION_MEDIA_TYPES.includes(image.mediaType.toLowerCase()))
+            return { known: false };
+        return { known: true, upperBoundTokens: VISION_TOKENS_PER_IMAGE_UPPER_BOUND };
+    }
     /**
      * POST the chat body, retrying with exponential backoff on a rate-limited
      * (429) or overloaded (503) status. Extracted from {@link chat} so the
@@ -418,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;
@@ -468,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.0.14",
+  "version": "1.1.1",
   "description": "DeepSeek AI provider for molecule.dev",
   "homepage": "https://www.molecule.dev/packages/api-ai-deepseek",
   "type": "module",
@@ -33,8 +33,8 @@
     "directory": "packages/api/bonds/ai/deepseek"
   },
   "devDependencies": {
-    "@molecule/api-ai": "1.3.5",
-    "@molecule/api-bond": "1.0.3",
+    "@molecule/api-ai": "1.4.0",
+    "@molecule/api-bond": "1.0.4",
     "@types/node": "26.6.5",
     "typescript": "6.0.3",
     "vitest": "4.1.12"