@molecule/api-ai-deepseek 1.0.9 → 1.0.11

package/README.md

@@ -3,17 +3,17 @@ 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-16T10:23:43.043Z
+Generated: 2026-10-16T23:28:16.072Z
 -->
 
 # @molecule/api-ai-deepseek
 
+DeepSeek AI provider for molecule.dev.
+
 > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
 > It is written to be read by coding agents as much as by people, and is generated from this
 > package's source — edit `src/index.ts` JSDoc, not this file.
 
-DeepSeek AI provider for molecule.dev.
-
 ## Quick Start
 
 ```typescript

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;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;IAyOzD;;;;;;;;;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;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;IAiRzD;;;;;;;;;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;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

@@ -33,6 +33,12 @@ export const DEFAULT_FIRST_TOKEN_TIMEOUT_MS = 45_000;
 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;
+/**
+ * How many stop sequences DeepSeek accepts in one request ("Up to 16 sequences
+ * where the API will stop generating further tokens", create-chat-completion).
+ * A longer list is sent truncated rather than refused by the API.
+ */
+const MAX_STOP_SEQUENCES = 16;
 /**
  * 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
@@ -144,6 +150,16 @@ class DeepseekAIProviderImpl {
         const model = this.modelMap[canonicalModel] ?? canonicalModel;
         const maxTokens = params.maxTokens ?? this.maxTokens;
         const messages = this.formatMessages(params.messages, params.system);
+        // 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
+        // reached it mid-answer ended there with the tag dropped from the text.
+        const stop = (params.stop ?? []).filter((s) => s.length > 0).slice(0, MAX_STOP_SEQUENCES);
+        if ((params.stop?.length ?? 0) > MAX_STOP_SEQUENCES) {
+            logger.warn('DeepSeek takes at most 16 stop sequences — the rest were dropped', {
+                requested: params.stop?.length,
+            });
+        }
         const body = {
             // Abuse attribution (see ChatParams.endUserId): OpenAI-compatible APIs
             // scope enforcement by `user`, so an abusive tenant can be actioned
@@ -157,6 +173,7 @@ class DeepseekAIProviderImpl {
             messages,
             stream: params.stream !== false,
             ...(params.stream !== false ? { stream_options: { include_usage: true } } : {}),
+            ...(stop.length > 0 ? { stop } : {}),
         };
         // Tools: merge custom tools (function format) and server tools
         const functions = params.tools?.length ? this.formatTools(params.tools) : [];
@@ -281,18 +298,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;
                 }
@@ -804,11 +847,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.9",
+  "version": "1.0.11",
   "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.3",
+    "@molecule/api-ai": "1.3.4",
     "@molecule/api-bond": "1.0.2",
     "@types/node": "26.1.2",
     "typescript": "6.0.3",