@molecule/api-ai-deepseek 1.0.10 → 1.0.12

package/dist/provider.d.ts

@@ -62,8 +62,20 @@ declare class DeepseekAIProviderImpl implements AIProvider {
      * Converts internal `ChatMessage` objects to the OpenAI-compatible message format.
      * System prompt is prepended as a system role message.
      *
+     * Thinking mode has one wire obligation that non-thinking mode does not:
+     * DeepSeek's thinking-mode guide requires the `reasoning_content` of every
+     * retained assistant turn to be sent back on a later request carrying `tools`,
+     * including turns where the model made no tool call — omitting it is a 400.
+     * So when `replayReasoning` is set (the caller passed a `thinking` block), each
+     * assistant turn carries `ChatMessage.reasoning` verbatim. That reasoning is
+     * never synthesized: a turn with no recorded reasoning sends `''`, which is
+     * the only representation of "this turn ran without thinking" the wire has.
+     * A non-thinking request keeps the historical shape (no `reasoning_content`);
+     * the guide says a non-thinking request ignores the field anyway.
+     *
      * @param messages - The chat messages to format.
      * @param system - Optional system prompt to prepend.
+     * @param replayReasoning - Whether thinking mode is on for this request.
      * @returns The formatted messages array for the DeepSeek API.
      */
     private formatMessages;

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,EAGX,MAAM,kBAAkB,CAAA;AASzB,OAAO,cAAc,CAAA;AAErB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAsGhD,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;IAqPzD;;;;;;;;;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;;;;;;;;;;;;OAYG;YACY,sBAAsB;IA2GrC;;;;;;;;;;OAUG;IACH,OAAO,CAAE,eAAe;CA2KzB;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;AAIH,OAAO,KAAK,EACV,UAAU,EAIV,SAAS,EAET,UAAU,EAGX,MAAM,kBAAkB,CAAA;AASzB,OAAO,cAAc,CAAA;AAErB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAwGhD,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;IAsRzD;;;;;;;;;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;IAuDlC;;;;;;;;;;;;OAYG;YACY,sBAAsB;IA2GrC;;;;;;;;;;OAUG;IACH,OAAO,CAAE,eAAe;CA0LzB;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

@@ -17,9 +17,11 @@ const logger = getLogger();
 // (not through the package barrel).
 import './secrets.js';
 /**
- * Map thinking budget tokens to a DeepSeek reasoning_effort level. DeepSeek V4
- * accepts only `'high'` or `'max'` for `reasoning_effort`, so larger budgets map
- * to `'max'` and everything else to `'high'`.
+ * Map thinking budget tokens to a DeepSeek reasoning_effort level, used ONLY as
+ * a fallback when the caller supplies a budget without a resolved native level.
+ * The native API accepts `low`/`high`/`max`; a caller that resolved one of them
+ * (the catalog's `supportedEffortLevels`) sends it verbatim and never reaches
+ * this function, so the fallback stays the two coarse buckets.
  *
  * @param budgetTokens - Requested thinking budget in tokens.
  * @returns `'high'` or `'max'` for the upstream effort hint.
@@ -149,7 +151,7 @@ class DeepseekAIProviderImpl {
         const canonicalModel = params.model ?? this.defaultModel;
         const model = this.modelMap[canonicalModel] ?? canonicalModel;
         const maxTokens = params.maxTokens ?? this.maxTokens;
-        const messages = this.formatMessages(params.messages, params.system);
+        const messages = this.formatMessages(params.messages, params.system, Boolean(params.thinking));
         // Stop sequences, capped at the API's own limit. Verified honoured by the
         // native endpoint on 2026-10-17: with `stop: ['<analysis>']` a reply that
         // would have opened with that tag streamed nothing at all, and one that
@@ -188,10 +190,11 @@ class DeepseekAIProviderImpl {
             // weaker nudge still produces a turn, and the agent loop has its own
             // prose-only backstops, whereas a 400 produces nothing at all.
             //
-            // Latent rather than live at the time of writing — no DeepSeek model in
-            // the catalog sets supportsThinking — but the model-health cron adds
-            // models to that catalog unattended, and the one place forceToolUse fires
-            // is discovery mode, i.e. the FIRST turn of every new conversation.
+            // LIVE for an entry that exposes opt-in reasoning (deepseek-flash, whose
+            // effort levels include the local `off` default): a project that picks
+            // low/high/max gets thinking mode on a discovery turn, and the forced
+            // nudge is degraded here instead of 400ing the first turn of the
+            // conversation.
             const forcedChoice = params.toolChoice === 'required' ||
                 (typeof params.toolChoice === 'object' && params.toolChoice?.type === 'tool');
             if (forcedChoice && params.thinking) {
@@ -206,15 +209,19 @@ class DeepseekAIProviderImpl {
                 body.tool_choice = { type: 'function', function: { name: params.toolChoice.name } };
             }
         }
-        // DeepSeek V4 defaults `thinking` to ENABLED. Thinking mode requires the
-        // assistant's reasoning_content to be echoed back on every subsequent turn
-        // (a 400 otherwise) and is awkward to combine with the tool-calling loop, so
-        // we run non-thinking unless a thinking budget is explicitly requested. The
-        // chat handler gates that on the model's `supportsThinking` flag.
+        // DeepSeek V4 defaults `thinking` to ENABLED. Per DeepSeek's thinking-mode
+        // guide (https://api-docs.deepseek.com/guides/thinking_mode/), a
+        // thinking-mode request that carries tools must send every retained
+        // assistant turn's `reasoning_content` back — including a turn where the
+        // model made no tool call — or the API answers 400. `formatMessages` replays
+        // `ChatMessage.reasoning` for exactly that reason. The catalog decides
+        // whether a turn carries a thinking block: deepseek-flash defaults to the
+        // local `off` level (no block → reasoning explicitly disabled below), and
+        // only a project that opts into low/high/max sends one.
         if (params.thinking) {
             body.thinking = { type: 'enabled' };
-            // Prefer a caller-resolved native value ('high' | 'max') from the model
-            // catalog; fall back to the budget threshold.
+            // Prefer a caller-resolved native value (`low` | `high` | `max`) from the
+            // model catalog; fall back to the budget threshold.
             body.reasoning_effort = params.thinking.effort ?? budgetToEffort(params.thinking.budgetTokens);
         }
         else {
@@ -298,18 +305,44 @@ class DeepseekAIProviderImpl {
                             detail = errorBody;
                     }
                     logger.error('DeepSeek API error', { status: response.status, detail, errorBody });
+                    // The status ladder decides what the CALLER can do, so every branch
+                    // must stay distinguishable downstream: the turn classifier keys on
+                    // these sentences, and an exhausted account must never read as
+                    // "try again" (2026-10-20: a −$0.09 DeepSeek account answered 402 on
+                    // every request and each one surfaced as the generic error — sixteen
+                    // benchmark runs died at their first request, indistinguishable from
+                    // an outage and each given a retry that could never succeed).
                     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.';
+                            ? // The status rides in the text: the turn classifier is
+                                // text-only, and an auth failure must classify `auth`
+                                // (never retried) — not the unknown bucket's pity retry.
+                                'AI service configuration error (HTTP 401) — the API key was rejected.'
+                            : response.status === 402 ||
+                                /insufficient balance|credit balance|payment required/i.test(detail)
+                                ? // An exhausted account is a platform billing condition, not a
+                                    // request problem and not a transient outage — no retry can
+                                    // restore a negative balance.
+                                    'AI service is unavailable — provider credit balance too low.'
+                                : 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 === 500 ||
+                                            response.status === 502 ||
+                                            response.status === 503 ||
+                                            response.status === 504 ||
+                                            response.status === 529
+                                            ? // The outage statuses the turn classifier reads as transient —
+                                                // one shared sentence, so a provider shed rides the retry
+                                                // ladder instead of killing the turn (was: 503 only).
+                                                'AI service is temporarily overloaded. Please try again in a moment.'
+                                            : // Anything else still names its status, so a never-before-seen
+                                                // code is classifiable (and 5xx-shaped ones ride `http 5xx`
+                                                // into the transient class) instead of a bare "try again".
+                                                `AI service error (HTTP ${response.status}). Please try again.`;
                     yield { type: 'error', message: clientMessage, errorKey: 'ai.error.apiError' };
                     return;
                 }
@@ -492,11 +525,23 @@ class DeepseekAIProviderImpl {
      * Converts internal `ChatMessage` objects to the OpenAI-compatible message format.
      * System prompt is prepended as a system role message.
      *
+     * Thinking mode has one wire obligation that non-thinking mode does not:
+     * DeepSeek's thinking-mode guide requires the `reasoning_content` of every
+     * retained assistant turn to be sent back on a later request carrying `tools`,
+     * including turns where the model made no tool call — omitting it is a 400.
+     * So when `replayReasoning` is set (the caller passed a `thinking` block), each
+     * assistant turn carries `ChatMessage.reasoning` verbatim. That reasoning is
+     * never synthesized: a turn with no recorded reasoning sends `''`, which is
+     * the only representation of "this turn ran without thinking" the wire has.
+     * A non-thinking request keeps the historical shape (no `reasoning_content`);
+     * the guide says a non-thinking request ignores the field anyway.
+     *
      * @param messages - The chat messages to format.
      * @param system - Optional system prompt to prepend.
+     * @param replayReasoning - Whether thinking mode is on for this request.
      * @returns The formatted messages array for the DeepSeek API.
      */
-    formatMessages(messages, system) {
+    formatMessages(messages, system, replayReasoning = false) {
         const formatted = [];
         if (system) {
             formatted.push({ role: 'system', content: system });
@@ -504,8 +549,14 @@ class DeepseekAIProviderImpl {
         for (const m of messages) {
             if (m.role === 'system')
                 continue; // handled above
+            // Only assistant turns have a reasoning channel. `reasoning_content: ''`
+            // is deliberate for a retained turn with no recorded reasoning (a
+            // non-thinking turn inside a thinking-mode history): the vendor requires
+            // the field on every retained assistant turn, and an empty string is the
+            // only way to say "nothing was recorded" without inventing content.
+            const reasoningField = replayReasoning && m.role === 'assistant' ? { reasoning_content: m.reasoning ?? '' } : {};
             if (typeof m.content === 'string') {
-                formatted.push({ role: m.role, content: m.content });
+                formatted.push({ role: m.role, content: m.content, ...reasoningField });
                 continue;
             }
             // Content blocks — convert to OpenAI format
@@ -552,13 +603,14 @@ class DeepseekAIProviderImpl {
                 // screenshot tool) must not be dropped: Chat Completions accepts a user
                 // message after the tool messages, so emit them instead of losing them.
                 if (parts.length > 0)
-                    formatted.push({ role: m.role, content: parts });
+                    formatted.push({ role: m.role, content: parts, ...reasoningField });
             }
             else if (toolCalls.length > 0) {
                 // Assistant message with tool calls
                 formatted.push({
                     role: 'assistant',
                     content: parts.length > 0 ? parts : null,
+                    ...reasoningField,
                     tool_calls: toolCalls,
                 });
             }
@@ -566,6 +618,7 @@ class DeepseekAIProviderImpl {
                 formatted.push({
                     role: m.role,
                     content: parts.length === 1 && parts[0].type === 'text' ? parts[0].text : parts,
+                    ...reasoningField,
                 });
             }
         }
@@ -821,11 +874,24 @@ class DeepseekAIProviderImpl {
                         code: streamError.code,
                         message: streamError.message,
                     });
-                    const clientMessage = /overload|capacity|503|529/i.test(detail)
-                        ? 'AI service is temporarily overloaded. Please try again in a moment.'
-                        : /rate.?limit|429|quota/i.test(detail)
-                            ? 'AI rate limit exceeded. Please try again shortly.'
-                            : 'AI service error. Please try again.';
+                    // Same distinctions as the pre-flight ladder, in the same precedence
+                    // the turn classifier applies (rate → auth → context → balance →
+                    // transient): an exhausted account is a billing state (never
+                    // transient, never "try again"), an auth failure stays `auth`, a
+                    // context overflow stays recoverable. There is no HTTP status here —
+                    // the stream answered 200 — so each class keys on the provider's own
+                    // wording, plus numeric codes some hosts send as `code`.
+                    const clientMessage = /rate.?limit|\b429\b|quota/i.test(detail)
+                        ? 'AI rate limit exceeded. Please try again shortly.'
+                        : /\b401\b|authentication|unauthorized/i.test(detail)
+                            ? 'AI service authentication/configuration error — the API key was rejected.'
+                            : /context.?length|context.?window|too long|too many tokens|token.?limit/i.test(detail)
+                                ? "Conversation too long for the model's context window. Use /compact to free space, or start a new conversation."
+                                : /insufficient balance|credit balance|payment required|\b402\b/i.test(detail)
+                                    ? 'AI service is unavailable — provider credit balance too low.'
+                                    : /overload|capacity|\b(?:500|502|503|504|529)\b/i.test(detail)
+                                        ? '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' };
                     continue;
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-ai-deepseek",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "DeepSeek AI provider for molecule.dev",
   "homepage": "https://www.molecule.dev/packages/api-ai-deepseek",
   "type": "module",
@@ -37,7 +37,7 @@
     "@molecule/api-bond": "1.0.2",
     "@types/node": "26.1.2",
     "typescript": "6.0.3",
-    "vitest": "4.1.11"
+    "vitest": "4.1.12"
   },
   "peerDependencies": {
     "@molecule/api-ai": "^1.0.1",