@molecule/api-ai-deepseek 1.0.8 → 1.0.10

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

@@ -90,6 +90,8 @@ declare class DeepseekAIProviderImpl implements AIProvider {
      *   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.
+     * @param call - The request's own identity, filled in from the response —
+     *   see {@link DeepseekCallContext}.
      * @yields {ChatEvent} Chat events as they arrive from the SSE stream.
      */
     private parseStreamingResponse;
@@ -100,6 +102,8 @@ declare class DeepseekAIProviderImpl implements AIProvider {
      * @param lines - Raw SSE lines to process.
      * @param pendingTools - Mutable map tracking tool call deltas accumulated across chunks.
      * @param state - Mutable token usage counters.
+     * @param call - The request's identity: the answer's own `id` and `model` are
+     *   recorded on `call.meta`, and any echo of the request is verified.
      * @yields {ChatEvent} Chat events extracted from the SSE lines.
      */
     private processSSELines;

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

package/dist/provider.js

@@ -8,6 +8,7 @@
  *
  * @module
  */
+import { randomUUID } from 'node:crypto';
 import { getLogger } from '@molecule/api-bond';
 import { t } from '@molecule/api-i18n';
 const logger = getLogger();
@@ -32,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
@@ -143,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
@@ -156,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) : [];
@@ -205,9 +223,24 @@ class DeepseekAIProviderImpl {
                 body.temperature = params.temperature;
             }
         }
+        // Correlation for THIS call (see ChatParams.requestId). It rides a header
+        // rather than the body's `user`: `user` is the stable per-user
+        // abuse-attribution value the provider scopes enforcement by, and varying it
+        // per request would make one account look like thousands. The header is
+        // ignored by every OpenAI-compatible server and is here so the vendor can
+        // find our request when a reply turns out not to belong to it.
+        const requestId = params.requestId ?? randomUUID();
+        // What the provider tells us about the call, reported on `done` (or logged
+        // when the reply has to be dropped as foreign). `responseId` and `model`
+        // come off the stream itself; the trace id off the response headers.
+        const call = {
+            meta: { requestId, endpoint: `${this.baseUrl}${this.completionsPath}` },
+            endUserId: params.endUserId,
+        };
         const headers = {
             'Content-Type': 'application/json',
             Authorization: `Bearer ${this.apiKey}`,
+            'X-Mol-Request-Id': requestId,
         };
         const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
         const firstTokenTimeoutMs = this.firstTokenTimeoutMs;
@@ -241,6 +274,16 @@ class DeepseekAIProviderImpl {
                     model,
                     signal,
                 });
+                // 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
+                // handle a vendor investigation needs.
+                const traceId = response.headers.get('x-ds-trace-id') ??
+                    response.headers.get('x-request-id') ??
+                    response.headers.get('request-id') ??
+                    undefined;
+                if (traceId)
+                    call.meta.traceId = traceId;
                 if (!response.ok) {
                     const errorBody = await response.text();
                     let detail = `HTTP ${response.status}`;
@@ -299,10 +342,7 @@ class DeepseekAIProviderImpl {
                 };
                 armBound(firstTokenTimeoutMs, 'before_content');
                 try {
-                    yield* this.parseStreamingResponse(response, state, {
-                        silenceMs: this.streamSilenceTimeoutMs,
-                        arm: armBound,
-                    });
+                    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
@@ -608,9 +648,11 @@ class DeepseekAIProviderImpl {
      *   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.
+     * @param call - The request's own identity, filled in from the response —
+     *   see {@link DeepseekCallContext}.
      * @yields {ChatEvent} Chat events as they arrive from the SSE stream.
      */
-    async *parseStreamingResponse(response, state, bounds) {
+    async *parseStreamingResponse(response, state, bounds, call) {
         const reader = response.body?.getReader();
         if (!reader) {
             yield {
@@ -634,7 +676,7 @@ class DeepseekAIProviderImpl {
                 const lines = buffer.split('\n');
                 buffer = lines.pop() ?? '';
                 let yieldedContent = false;
-                for (const event of this.processSSELines(lines, pendingTools, state)) {
+                for (const event of this.processSSELines(lines, pendingTools, state, call)) {
                     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
@@ -673,7 +715,7 @@ class DeepseekAIProviderImpl {
             }
             // Flush any remaining data in the buffer after EOF
             if (buffer.trim()) {
-                for (const event of this.processSSELines(buffer.split('\n'), pendingTools, state)) {
+                for (const event of this.processSSELines(buffer.split('\n'), pendingTools, state, call)) {
                     yield event;
                     if (event.type === 'error')
                         return;
@@ -704,6 +746,7 @@ class DeepseekAIProviderImpl {
                 outputTokens: state.outputTokens,
                 cacheReadInputTokens: state.cachedTokens,
             },
+            provider: call.meta,
         };
     }
     /**
@@ -713,9 +756,11 @@ class DeepseekAIProviderImpl {
      * @param lines - Raw SSE lines to process.
      * @param pendingTools - Mutable map tracking tool call deltas accumulated across chunks.
      * @param state - Mutable token usage counters.
+     * @param call - The request's identity: the answer's own `id` and `model` are
+     *   recorded on `call.meta`, and any echo of the request is verified.
      * @yields {ChatEvent} Chat events extracted from the SSE lines.
      */
-    *processSSELines(lines, pendingTools, state) {
+    *processSSELines(lines, pendingTools, state, call) {
         for (const line of lines) {
             if (!line.startsWith('data: '))
                 continue;
@@ -724,6 +769,44 @@ class DeepseekAIProviderImpl {
                 continue;
             try {
                 const event = JSON.parse(json);
+                // The reply's OWN identity, recorded for the caller: the completion id
+                // (one per answer, repeated on every delta) and the model the provider
+                // says answered. Recorded rather than asserted — a re-host legitimately
+                // answers under its own dated snapshot id.
+                if (typeof event.id === 'string')
+                    call.meta.responseId = event.id;
+                if (typeof event.model === 'string')
+                    call.meta.model = event.model;
+                // If this host echoes an identity back, verify it. A reply carrying an
+                // identity that is not the one we sent is a reply that was produced for
+                // somebody else's request, and it must not be streamed on as ours —
+                // 2026-10-16 a conversation received a complete foreign completion on a
+                // stream whose usage matched its own context, and nothing could tell.
+                // DeepSeek's own API echoes nothing, so this arm is inert there; it is
+                // live for any OpenAI-compatible host that does, and it is the only
+                // check that runs BEFORE the text reaches the caller.
+                const echoedUser = typeof event.user === 'string' ? event.user : undefined;
+                const echoedRequest = typeof event.request_id === 'string'
+                    ? event.request_id
+                    : typeof event.requestId === 'string'
+                        ? event.requestId
+                        : undefined;
+                const wrongUser = echoedUser !== undefined && call.endUserId !== undefined && echoedUser !== call.endUserId;
+                const wrongRequest = echoedRequest !== undefined && echoedRequest !== call.meta.requestId;
+                if (wrongUser || wrongRequest) {
+                    logger.error('Provider echoed a different identity — this reply is not ours', {
+                        requestId: call.meta.requestId,
+                        echoedUser: wrongUser ? echoedUser : undefined,
+                        echoedRequestId: wrongRequest ? echoedRequest : undefined,
+                        responseId: call.meta.responseId,
+                        traceId: call.meta.traceId,
+                        endpoint: call.meta.endpoint,
+                    });
+                    yield { type: 'error', message: t('ai.error.apiError'), errorKey: 'ai.error.apiError' };
+                    // The whole reply is somebody else's: stop reading it. The caller's
+                    // error ladder retries the request once.
+                    return;
+                }
                 // A mid-stream error arrives as a `data: {"error": {...}}` chunk (no
                 // `choices`) — most importantly rate-limit/overload during high load.
                 // Without this it matches no branch below and is silently dropped, so the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-ai-deepseek",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "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.2",
+    "@molecule/api-ai": "1.3.4",
     "@molecule/api-bond": "1.0.2",
     "@types/node": "26.1.2",
     "typescript": "6.0.3",