@molecule/api-ai-deepseek 1.0.6 → 1.0.8

package/LICENSE

@@ -1,3 +1,4 @@
+
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -34,21 +35,33 @@
 
       "Work" shall mean the work of authorship, whether in Source or
       Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work.
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
 
       "Derivative Works" shall mean any work, whether in Source or Object
       form, that is based on (or derived from) the Work and for which the
       editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship.
-
-      "Contribution" shall mean any work of authorship, including the
-      original version of the Work and any modifications or additions
-      to that Work, that is intentionally submitted to the Licensor for
-      inclusion in the Work by the copyright owner or by an individual or
-      Legal Entity authorized to submit on behalf of the copyright owner.
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
 
       "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by the Licensor and
+      on behalf of whom a Contribution has been received by Licensor and
       subsequently incorporated within the Work.
 
    2. Grant of Copyright License. Subject to the terms and conditions of
@@ -61,8 +74,18 @@
    3. Grant of Patent License. Subject to the terms and conditions of
       this License, each Contributor hereby grants to You a perpetual,
       worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      patent license to make, have made, use, offer to sell, sell, import,
-      and otherwise transfer the Work.
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
 
    4. Redistribution. You may reproduce and distribute copies of the
       Work or Derivative Works thereof in any medium, with or without
@@ -84,23 +107,87 @@
       (d) If the Work includes a "NOTICE" text file as part of its
           distribution, then any Derivative Works that You distribute must
           include a readable copy of the attribution notices contained
-          within such NOTICE file.
-
-   5. Submission of Contributions.
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
 
    6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor.
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
 
    7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
-
-   8. Limitation of Liability. In no event and under no legal theory shall
-      any Contributor be liable to You for damages.
-
-   9. Accepting Warranty or Additional Liability.
-
-   Copyright 2026 Molecule Dev, Inc.
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

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-01T18:20:44.372Z
+Generated: 2026-10-16T10:23:43.043Z
 -->
 
 # @molecule/api-ai-deepseek
@@ -80,6 +80,31 @@ interface DeepseekConfig {
   modelMap?: Record<string, string>
   /** Called on each rate-limited/overloaded upstream response, before any retry sleep. */
   onRateLimit?: AiRateLimitCallback
+  /** Called when a stream accepts the request and then produces no content for the whole first-token window. */
+  onStreamStall?: AiStreamStallCallback
+  /**
+   * How long a stream may wait for its FIRST content event before the provider
+   * abandons it and asks again (ms). Defaults to 45 000.
+   *
+   * Counted from the moment the request is sent, and cleared by the first
+   * `text` / `thinking` / `tool_use` event — NOT by a liveness frame, because
+   * DeepSeek keeps a stalled prefill's connection alive with `: keep-alive`
+   * comments, so a byte-level idle timeout never sees the stall at all. A turn's
+   * healthy first-token wait is ~1 s even on million-token prompts, so this
+   * window is a stall bound, not a latency budget.
+   */
+  firstTokenTimeoutMs?: number
+  /**
+   * How long a stream that has ALREADY started may go without a single byte
+   * before the provider abandons it (ms). Defaults to 60 000.
+   *
+   * Measured over the socket, not over content: once the reply has started, any
+   * byte proves the connection is alive, and a stretch with none is a broken
+   * stream rather than a slow one. Abandoning it here is not retried — the
+   * partial reply is already on the wire — it is reported as an error event for
+   * the caller's own ladder, which keeps the partial.
+   */
+  streamSilenceTimeoutMs?: number
 }
 ```
 
@@ -113,12 +138,20 @@ function createProvider(config?: DeepseekConfig): AIProvider
 
 ### Constants
 
-#### `aiDeepseekSecretDefinitions`
+#### `provider`
 
-Secret definitions required by the DeepSeek AI bond.
+The provider implementation.
 
 ```typescript
-const aiDeepseekSecretDefinitions: SecretDefinition[]
+const provider: AIProvider
+```
+
+#### `DEFAULT_FIRST_TOKEN_TIMEOUT_MS`
+
+How long a stream may wait for its first content event.
+
+```typescript
+const DEFAULT_FIRST_TOKEN_TIMEOUT_MS: 45000
 ```
 
 #### `DeepseekAIProvider`
@@ -129,12 +162,12 @@ Back-compat alias for the provider class (the scaffold exported this name).
 const DeepseekAIProvider: typeof DeepseekAIProviderImpl
 ```
 
-#### `provider`
+#### `aiDeepseekSecretDefinitions`
 
-The provider implementation.
+Secret definitions required by the DeepSeek AI bond.
 
 ```typescript
-const provider: AIProvider
+const aiDeepseekSecretDefinitions: SecretDefinition[]
 ```
 
 ## Core Interface
@@ -189,6 +222,14 @@ not at bond/module-load time) — it never silently sends an empty key.
 malformed tool schema) gets its own non-retryable message distinct from the generic
 "AI service error. Please try again." used for retryable failures.
 
+**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
+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.
+
 ## E2E Tests
 
 Integration checklist — drive the real UI (live preview, no mocks), adapt

package/dist/index.d.ts

@@ -31,6 +31,14 @@
  * malformed tool schema) gets its own non-retryable message distinct from the generic
  * "AI service error. Please try again." used for retryable failures.
  *
+ * **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
+ * 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.
+ *
  * @module
  */
 export * from './browser-guard.js';

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -31,6 +31,14 @@
  * malformed tool schema) gets its own non-retryable message distinct from the generic
  * "AI service error. Please try again." used for retryable failures.
  *
+ * **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
+ * 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.
+ *
  * @module
  */
 export * from './browser-guard.js';

package/dist/provider.d.ts

@@ -11,6 +11,8 @@
 import type { AIProvider, ChatEvent, ChatParams } from '@molecule/api-ai';
 import './secrets.js';
 import type { DeepseekConfig } from './types.js';
+/** How long a stream may wait for its first content event. */
+export declare const DEFAULT_FIRST_TOKEN_TIMEOUT_MS = 45000;
 /**
  * DeepSeek AI provider that implements the `AIProvider` interface using
  * DeepSeek's OpenAI-compatible Chat Completions API with support for streaming,
@@ -25,6 +27,9 @@ declare class DeepseekAIProviderImpl implements AIProvider {
     private completionsPath;
     private modelMap;
     private onRateLimit?;
+    private onStreamStall?;
+    private firstTokenTimeoutMs;
+    private streamSilenceTimeoutMs;
     constructor(config?: DeepseekConfig);
     /**
      * Sends a chat request and yields streamed events (text chunks, tool use, done/error).
@@ -33,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>;
+    /**
+     * POST the chat body, retrying with exponential backoff on a rate-limited
+     * (429) or overloaded (503) status. Extracted from {@link chat} so the
+     * stream-level first-token retry can wrap it: a rate-limited request and a
+     * stalled stream are different failures with different budgets, and nesting
+     * 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).
+     */
+    private requestWithRateLimitRetries;
+    /**
+     * Record one stalled attempt: a warn line always, plus the host's
+     * `onStreamStall` callback so the gap is queryable from the turn's own
+     * analytics rather than only from a log buffer that has since rotated.
+     *
+     * @param model - The upstream model id the stalled request targeted.
+     * @param stall - What the stalled attempt looked like.
+     */
+    private reportStreamStall;
     /**
      * Converts internal `ChatMessage` objects to the OpenAI-compatible message format.
      * System prompt is prepended as a system role message.
@@ -61,6 +86,10 @@ declare class DeepseekAIProviderImpl implements AIProvider {
      * format), yielding `ChatEvent` objects as they arrive.
      *
      * @param response - The fetch Response with an SSE body stream.
+     * @param state - Mutable counters for this attempt's tokens, liveness frames
+     *   and streamed content. Owned by the caller so a retry can read what the
+     *   abandoned attempt produced.
+     * @param bounds - How to re-arm the stream bound after the reply starts.
      * @yields {ChatEvent} Chat events as they arrive from the SSE stream.
      */
     private parseStreamingResponse;

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,UAAU,EAGV,SAAS,EAET,UAAU,EAEX,MAAM,kBAAkB,CAAA;AASzB,OAAO,cAAc,CAAA;AAErB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAuBhD;;;;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;gBAE7B,MAAM,GAAE,cAAmB;IAqBvC;;;;;OAKG;IACI,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,CAAC,SAAS,CAAC;IAwLzD;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;IAgFtB;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAWnB;;;;;OAKG;IACH,OAAO,CAAE,yBAAyB;IAuDlC;;;;;;OAMG;YACY,sBAAsB;IAoFrC;;;;;;;;OAQG;IACH,OAAO,CAAE,eAAe;CAkIzB;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;AAEH,OAAO,KAAK,EACV,UAAU,EAIV,SAAS,EAET,UAAU,EAEX,MAAM,kBAAkB,CAAA;AASzB,OAAO,cAAc,CAAA;AAErB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAoFhD,8DAA8D;AAC9D,eAAO,MAAM,8BAA8B,QAAS,CAAA;AAyFpD;;;;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;IA4MzD;;;;;;;;;OASG;YACW,2BAA2B;IA0EzC;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IA2BzB;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;IAgFtB;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAWnB;;;;;OAKG;IACH,OAAO,CAAE,yBAAyB;IAuDlC;;;;;;;;;;OAUG;YACY,sBAAsB;IAyGrC;;;;;;;;OAQG;IACH,OAAO,CAAE,eAAe;CAkIzB;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

@@ -26,6 +26,73 @@ import './secrets.js';
 function budgetToEffort(budgetTokens) {
     return budgetTokens >= 12_000 ? 'max' : 'high';
 }
+/** How long a stream may wait for its first content event. */
+export const DEFAULT_FIRST_TOKEN_TIMEOUT_MS = 45_000;
+/** How long a stream that HAS started may go without a single byte. */
+const DEFAULT_STREAM_SILENCE_TIMEOUT_MS = 60_000;
+/** Node's `setTimeout` ceiling: a larger delay is clamped to 1 ms, i.e. instant. */
+const MAX_TIMER_MS = 2_147_483_647;
+/**
+ * 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
+ * armed: these values arm `setTimeout`, and a non-positive one (or one past
+ * Node's 32-bit timer ceiling, which `setTimeout` clamps to 1 ms) would abandon
+ * every stream on its first tick — turning a stall bound into a universal
+ * failure.
+ *
+ * @param configured - The value from the provider config, when set.
+ * @param envValue - The raw environment value, when set.
+ * @param fallback - The default to use when neither resolves.
+ * @returns Milliseconds for the bound.
+ */
+function resolveBoundMs(configured, envValue, fallback) {
+    for (const candidate of [configured, Number(envValue)]) {
+        if (typeof candidate === 'number' &&
+            Number.isFinite(candidate) &&
+            candidate > 0 &&
+            candidate <= MAX_TIMER_MS) {
+            return candidate;
+        }
+    }
+    return fallback;
+}
+/**
+ * The first-token bound, from the config, then
+ * `MOL_DEEPSEEK_FIRST_TOKEN_TIMEOUT_MS`, then the default.
+ *
+ * @param configured - The value from {@link DeepseekConfig.firstTokenTimeoutMs}.
+ * @returns Milliseconds to wait for the first content event.
+ */
+function resolveFirstTokenTimeoutMs(configured) {
+    return resolveBoundMs(configured, process.env.MOL_DEEPSEEK_FIRST_TOKEN_TIMEOUT_MS, DEFAULT_FIRST_TOKEN_TIMEOUT_MS);
+}
+/**
+ * The post-content inter-chunk silence bound, from the config, then
+ * `MOL_DEEPSEEK_STREAM_SILENCE_TIMEOUT_MS`, then the default.
+ *
+ * @param configured - The value from {@link DeepseekConfig.streamSilenceTimeoutMs}.
+ * @returns Milliseconds a started stream may go without a byte.
+ */
+function resolveStreamSilenceTimeoutMs(configured) {
+    return resolveBoundMs(configured, process.env.MOL_DEEPSEEK_STREAM_SILENCE_TIMEOUT_MS, DEFAULT_STREAM_SILENCE_TIMEOUT_MS);
+}
+/**
+ * Whether an event means the reply has STARTED, i.e. the first-token bound no
+ * longer applies. A `keep_alive` is deliberately NOT content: it is exactly what
+ * a stalled upstream keeps dripping, so treating it as progress would disarm the
+ * bound on the one stream it exists to catch. `usage` and `done` are not content
+ * either — a stream that reports usage and closes produced no reply.
+ *
+ * @param event - One event from the provider stream.
+ * @returns True for the first real output of a reply.
+ */
+function isContentEvent(event) {
+    return (event.type === 'text' ||
+        event.type === 'thinking' ||
+        event.type === 'tool_use' ||
+        event.type === 'tool_use_start' ||
+        event.type === 'tool_input_delta');
+}
 /**
  * DeepSeek AI provider that implements the `AIProvider` interface using
  * DeepSeek's OpenAI-compatible Chat Completions API with support for streaming,
@@ -40,6 +107,9 @@ class DeepseekAIProviderImpl {
     completionsPath;
     modelMap;
     onRateLimit;
+    onStreamStall;
+    firstTokenTimeoutMs;
+    streamSilenceTimeoutMs;
     constructor(config = {}) {
         this.apiKey = config.apiKey ?? process.env.DEEPSEEK_API_KEY ?? '';
         this.defaultModel = config.defaultModel ?? 'deepseek-flash';
@@ -49,6 +119,9 @@ class DeepseekAIProviderImpl {
             config.completionsPath ?? process.env.DEEPSEEK_COMPLETIONS_PATH ?? '/v1/chat/completions';
         this.modelMap = config.modelMap ?? {};
         this.onRateLimit = config.onRateLimit;
+        this.onStreamStall = config.onStreamStall;
+        this.firstTokenTimeoutMs = resolveFirstTokenTimeoutMs(config.firstTokenTimeoutMs);
+        this.streamSilenceTimeoutMs = resolveStreamSilenceTimeoutMs(config.streamSilenceTimeoutMs);
         // Fail fast with an actionable local error rather than a cryptic 401 on the
         // first request. The default `provider` export constructs lazily on first
         // use (see index.ts), so this surfaces the moment the provider is actually
@@ -137,7 +210,147 @@ class DeepseekAIProviderImpl {
             Authorization: `Bearer ${this.apiKey}`,
         };
         const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
-        const signal = params.signal ?? AbortSignal.timeout(DEFAULT_TIMEOUT_MS);
+        const firstTokenTimeoutMs = this.firstTokenTimeoutMs;
+        const MAX_STALL_RETRIES = 1;
+        // A stream that OPENS and then produces no content is invisible to every
+        // other signal this provider has: the request returns 200, no status is ever
+        // wrong, and DeepSeek keeps a stalled prefill's connection alive with
+        // `: keep-alive` comments — so a byte-level idle timeout stays quiet too.
+        // Left alone, the whole first-token window is spent before anything notices.
+        // Measured in production: on 2026-10-01 nine turns died this way in one
+        // project, each spending 540-582 s — three 180 s windows of the chat
+        // handler's progress watchdog, which was the ONLY bound on the stream, and
+        // their own record named no provider time at all. Bound it here instead,
+        // where the same request can simply be asked again.
+        for (let stalledAttempt = 0;; stalledAttempt++) {
+            const controller = new AbortController();
+            const forwardAbort = () => controller.abort();
+            if (params.signal?.aborted)
+                controller.abort();
+            else
+                params.signal?.addEventListener('abort', forwardAbort, { once: true });
+            // The provider's own ceiling bounds each ATTEMPT; the caller's signal, when
+            // 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,
+                });
+                if (!response.ok) {
+                    const errorBody = await response.text();
+                    let detail = `HTTP ${response.status}`;
+                    try {
+                        const parsed = JSON.parse(errorBody);
+                        if (parsed.error?.message)
+                            detail = parsed.error.message;
+                    }
+                    catch (_error) {
+                        // JSON.parse failed — raw text is already in `errorBody`; use it as-is.
+                        if (errorBody.length > 0 && errorBody.length < 200)
+                            detail = errorBody;
+                    }
+                    logger.error('DeepSeek API error', { status: response.status, detail, errorBody });
+                    const clientMessage = response.status === 429
+                        ? 'AI rate limit exceeded. Please try again shortly.'
+                        : response.status === 401
+                            ? 'AI service configuration error.'
+                            : response.status === 400 &&
+                                /prompt is too long|too many tokens|token.*limit|context.*length/i.test(detail)
+                                ? "Conversation too long for the model's context window. Use /compact to free space, or start a new conversation."
+                                : response.status === 400
+                                    ? 'AI request was invalid — check the model and request parameters.'
+                                    : response.status === 503
+                                        ? 'AI service is temporarily overloaded. Please try again in a moment.'
+                                        : 'AI service error. Please try again.';
+                    yield { type: 'error', message: clientMessage, errorKey: 'ai.error.apiError' };
+                    return;
+                }
+                if (params.stream === false) {
+                    const data = (await response.json());
+                    yield* this.parseNonStreamingResponse(data);
+                    return;
+                }
+                const state = {
+                    inputTokens: 0,
+                    outputTokens: 0,
+                    cachedTokens: 0,
+                    keepAlives: 0,
+                    streamedChars: 0,
+                    contentSeen: false,
+                };
+                // Both bounds abort the same request; `expired` says which one did, and
+                // `windowStartedAt` how long that one had been running — the stall is
+                // the WINDOW that expired, not the time since the request went out (an
+                // inter-chunk stall after a long reply would otherwise report minutes).
+                const bounds = { expired: null, timer: null, windowStartedAt: 0 };
+                const armBound = (ms, phase) => {
+                    if (bounds.timer)
+                        clearTimeout(bounds.timer);
+                    bounds.windowStartedAt = Date.now();
+                    bounds.timer = setTimeout(() => {
+                        bounds.expired = phase;
+                        controller.abort();
+                    }, ms);
+                };
+                armBound(firstTokenTimeoutMs, 'before_content');
+                try {
+                    yield* this.parseStreamingResponse(response, state, {
+                        silenceMs: this.streamSilenceTimeoutMs,
+                        arm: armBound,
+                    });
+                }
+                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)
+                        throw error;
+                    const stall = {
+                        stallMs: Date.now() - bounds.windowStartedAt,
+                        attempt: stalledAttempt + 1,
+                        // Only a stream that never started may be asked again: a reply that
+                        // already partly reached the consumer would be duplicated.
+                        willRetry: bounds.expired === 'before_content' && stalledAttempt < MAX_STALL_RETRIES,
+                        streamedChars: state.streamedChars,
+                        keepAlives: state.keepAlives,
+                        phase: bounds.expired,
+                    };
+                    this.reportStreamStall(model, stall);
+                    if (stall.willRetry)
+                        continue;
+                    // Out of retries, or the partial reply is already on the wire. Hand it
+                    // to the caller's own error ladder, which keeps the partial.
+                    yield { type: 'error', message: t('ai.error.apiError'), errorKey: 'ai.error.apiError' };
+                    return;
+                }
+                finally {
+                    if (bounds.timer)
+                        clearTimeout(bounds.timer);
+                }
+                return;
+            }
+            finally {
+                clearTimeout(ceiling);
+                params.signal?.removeEventListener('abort', forwardAbort);
+            }
+        }
+    }
+    /**
+     * POST the chat body, retrying with exponential backoff on a rate-limited
+     * (429) or overloaded (503) status. Extracted from {@link chat} so the
+     * stream-level first-token retry can wrap it: a rate-limited request and a
+     * stalled stream are different failures with different budgets, and nesting
+     * 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).
+     */
+    async requestWithRateLimitRetries(args) {
+        const { body, headers, model, signal } = args;
         // Retry with exponential backoff for rate limits (429) and overloaded (503)
         const MAX_RETRIES = 3;
         let response = null;
@@ -198,41 +411,42 @@ class DeepseekAIProviderImpl {
             }
             break;
         }
-        if (!response.ok) {
-            const errorBody = await response.text();
-            let detail = `HTTP ${response.status}`;
-            try {
-                const parsed = JSON.parse(errorBody);
-                if (parsed.error?.message)
-                    detail = parsed.error.message;
-            }
-            catch (_error) {
-                // JSON.parse failed — raw text is already in `errorBody`; use it as-is.
-                if (errorBody.length > 0 && errorBody.length < 200)
-                    detail = errorBody;
-            }
-            logger.error('DeepSeek API error', { status: response.status, detail, errorBody });
-            const clientMessage = response.status === 429
-                ? 'AI rate limit exceeded. Please try again shortly.'
-                : response.status === 401
-                    ? 'AI service configuration error.'
-                    : response.status === 400 &&
-                        /prompt is too long|too many tokens|token.*limit|context.*length/i.test(detail)
-                        ? "Conversation too long for the model's context window. Use /compact to free space, or start a new conversation."
-                        : response.status === 400
-                            ? 'AI request was invalid — check the model and request parameters.'
-                            : response.status === 503
-                                ? 'AI service is temporarily overloaded. Please try again in a moment.'
-                                : 'AI service error. Please try again.';
-            yield { type: 'error', message: clientMessage, errorKey: 'ai.error.apiError' };
-            return;
+        return response;
+    }
+    /**
+     * Record one stalled attempt: a warn line always, plus the host's
+     * `onStreamStall` callback so the gap is queryable from the turn's own
+     * analytics rather than only from a log buffer that has since rotated.
+     *
+     * @param model - The upstream model id the stalled request targeted.
+     * @param stall - What the stalled attempt looked like.
+     */
+    reportStreamStall(model, stall) {
+        logger.warn('DeepSeek stream stalled', {
+            model,
+            phase: stall.phase,
+            stallMs: stall.stallMs,
+            attempt: stall.attempt,
+            willRetry: stall.willRetry,
+            streamedChars: stall.streamedChars,
+            keepAlives: stall.keepAlives,
+        });
+        try {
+            this.onStreamStall?.({
+                provider: this.name,
+                model,
+                phase: stall.phase,
+                stallMs: stall.stallMs,
+                attempt: stall.attempt,
+                willRetry: stall.willRetry,
+                streamedChars: stall.streamedChars,
+                keepAlives: stall.keepAlives,
+            });
         }
-        if (params.stream === false) {
-            const data = (await response.json());
-            yield* this.parseNonStreamingResponse(data);
-            return;
+        catch (error) {
+            // Host-app telemetry; its failure must never break the request.
+            logger.warn('onStreamStall callback threw', { error });
         }
-        yield* this.parseStreamingResponse(response);
     }
     /**
      * Converts internal `ChatMessage` objects to the OpenAI-compatible message format.
@@ -390,9 +604,13 @@ class DeepseekAIProviderImpl {
      * format), yielding `ChatEvent` objects as they arrive.
      *
      * @param response - The fetch Response with an SSE body stream.
+     * @param state - Mutable counters for this attempt's tokens, liveness frames
+     *   and streamed content. Owned by the caller so a retry can read what the
+     *   abandoned attempt produced.
+     * @param bounds - How to re-arm the stream bound after the reply starts.
      * @yields {ChatEvent} Chat events as they arrive from the SSE stream.
      */
-    async *parseStreamingResponse(response) {
+    async *parseStreamingResponse(response, state, bounds) {
         const reader = response.body?.getReader();
         if (!reader) {
             yield {
@@ -404,7 +622,6 @@ class DeepseekAIProviderImpl {
         }
         const decoder = new TextDecoder();
         let buffer = '';
-        const state = { inputTokens: 0, outputTokens: 0, cachedTokens: 0 };
         // Track pending tool calls (accumulated across deltas). `started` guards the
         // one-shot tool_use_start emission once the id + name are first known.
         const pendingTools = new Map();
@@ -419,6 +636,20 @@ class DeepseekAIProviderImpl {
                 let yieldedContent = false;
                 for (const event of this.processSSELines(lines, pendingTools, state)) {
                     yieldedContent = true;
+                    // The reply has started. Counting this from the EVENTS (rather than
+                    // from the byte stream) is what lets the first-token bound see a
+                    // stall whose connection is kept alive by empty frames — the shape
+                    // DeepSeek actually produces. And the bound is swapped the instant it
+                    // starts, not at the end of the batch: a first-token timer that fired
+                    // on a reply already yielded to the consumer would retry and
+                    // duplicate it.
+                    if (isContentEvent(event) && !state.contentSeen) {
+                        state.contentSeen = true;
+                        bounds.arm(bounds.silenceMs, 'after_content');
+                    }
+                    if (event.type === 'text' || event.type === 'thinking') {
+                        state.streamedChars += event.content.length;
+                    }
                     yield event;
                     // A mid-stream error (rate-limit/overload during high load, sent as a
                     // `data: {"error": {...}}` chunk) means the turn was truncated. Stop
@@ -432,8 +663,13 @@ class DeepseekAIProviderImpl {
                 // (e.g., during extended reasoning with empty chunks or keepalive comments).
                 // This resets the consumer's stream timeout without forwarding to the client.
                 if (!yieldedContent) {
+                    state.keepAlives += 1;
                     yield { type: 'keep_alive' };
                 }
+                // Any chunk at all proves the socket is alive, so the post-content bound
+                // is re-armed here rather than on content events only.
+                if (state.contentSeen)
+                    bounds.arm(bounds.silenceMs, 'after_content');
             }
             // Flush any remaining data in the buffer after EOF
             if (buffer.trim()) {

package/dist/types.d.ts

@@ -3,7 +3,7 @@
  *
  * @module
  */
-import type { AiRateLimitCallback } from '@molecule/api-ai';
+import type { AiRateLimitCallback, AiStreamStallCallback } from '@molecule/api-ai';
 /**
  * Configuration for DeepSeek.
  */
@@ -34,6 +34,31 @@ export interface DeepseekConfig {
     modelMap?: Record<string, string>;
     /** Called on each rate-limited/overloaded upstream response, before any retry sleep. */
     onRateLimit?: AiRateLimitCallback;
+    /** Called when a stream accepts the request and then produces no content for the whole first-token window. */
+    onStreamStall?: AiStreamStallCallback;
+    /**
+     * How long a stream may wait for its FIRST content event before the provider
+     * abandons it and asks again (ms). Defaults to 45 000.
+     *
+     * Counted from the moment the request is sent, and cleared by the first
+     * `text` / `thinking` / `tool_use` event — NOT by a liveness frame, because
+     * DeepSeek keeps a stalled prefill's connection alive with `: keep-alive`
+     * comments, so a byte-level idle timeout never sees the stall at all. A turn's
+     * healthy first-token wait is ~1 s even on million-token prompts, so this
+     * window is a stall bound, not a latency budget.
+     */
+    firstTokenTimeoutMs?: number;
+    /**
+     * How long a stream that has ALREADY started may go without a single byte
+     * before the provider abandons it (ms). Defaults to 60 000.
+     *
+     * Measured over the socket, not over content: once the reply has started, any
+     * byte proves the connection is alive, and a stretch with none is a broken
+     * stream rather than a slow one. Abandoning it here is not retried — the
+     * partial reply is already on the wire — it is reported as an error event for
+     * the caller's own ladder, which keeps the partial.
+     */
+    streamSilenceTimeoutMs?: number;
 }
 /**
  * Process Env interface.

package/dist/types.d.ts.map

@@ -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,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;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"}
+{"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-ai-deepseek",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "DeepSeek AI provider for molecule.dev",
   "homepage": "https://www.molecule.dev/packages/api-ai-deepseek",
   "type": "module",
@@ -33,7 +33,7 @@
     "directory": "packages/api/bonds/ai/deepseek"
   },
   "devDependencies": {
-    "@molecule/api-ai": "1.3.0",
+    "@molecule/api-ai": "1.3.2",
     "@molecule/api-bond": "1.0.2",
     "@types/node": "26.1.2",
     "typescript": "6.0.3",