melchizedek-agents 1.10.3 → 1.11.0

package/dist/lib/models/adapterResolver.js

@@ -25,6 +25,7 @@ import { GeminiAdapter } from './geminiAdapter.js';
 import { GptAdapter } from './gptAdapter.js';
 import { GrokAdapter } from './grokAdapter.js';
 import { KimiAdapter } from './kimiAdapter.js';
+import { DeepSeekAdapter } from './deepseekAdapter.js';
 import { OllamaAdapter } from './ollamaAdapter.js';
 import { providerForModel } from './providerMap.js';
 /**
@@ -53,7 +54,7 @@ export function scopedKey(model, apiKey, keyProvider) {
 /** A provider name as the A2A X-Provider header gives it; anything unknown reads as gemini. */
 export function normalizeProvider(provider) {
     const p = provider?.toLowerCase();
-    if (p === 'ollama' || p === 'anthropic' || p === 'openai' || p === 'xai' || p === 'moonshot') {
+    if (p === 'ollama' || p === 'anthropic' || p === 'openai' || p === 'xai' || p === 'moonshot' || p === 'deepseek') {
         return p;
     }
     return 'gemini';
@@ -84,6 +85,7 @@ const CONTRACT_ADAPTER = {
         : new GptAdapter({ model: r.model, apiKey: r.apiKey, endpoint: r.endpoint }),
     xai: (r) => new GrokAdapter({ model: r.model, apiKey: r.apiKey }),
     moonshot: (r) => new KimiAdapter({ model: r.model, apiKey: r.apiKey, baseUrl: r.endpoint?.baseURL }),
+    deepseek: (r) => new DeepSeekAdapter({ model: r.model, apiKey: r.apiKey, baseUrl: r.endpoint?.baseURL }),
 };
 /** A resolver over the one prefix table. A Gemini id gets GeminiAdapter (ADR 0100, ADR 0107). */
 export function adapterResolver() {

package/dist/lib/models/capabilities.js

@@ -193,6 +193,16 @@ export const CAPABILITY_MATRIX = {
         vision: ok('test', 'user-turn images only, sent as base64 (Moonshot takes no public image URLs)'),
         native_search: unsupported("Moonshot's model-side $web_search retires 2026-10-20 and its successor is a REST call, not a request field; the web_search sentinel is dropped (use web_extract)"),
     },
+    deepseek: {
+        delegation: ok(),
+        memory_tools: ok(),
+        structured_output: degraded('JSON mode (response_format json_object), not a strict schema: the schema is asked for in the system message and the engine validates the reply'),
+        structured_output_with_tools: degraded(setModelResponseNote('DeepSeek takes JSON mode only, no strict schema')),
+        thinking_with_tools: ok('test', "reasoning_content is sent back on every assistant message of a request with tools, earlier turns included, as DeepSeek requires (else a 400): the same model's stored state, an empty string where none is stored (ADR 0046); effort travels as reasoning_effort beside a thinking switch"),
+        streaming: ok(),
+        vision: ok('test', 'user-turn images only, sent as base64; deepseek-flash only (deepseek-v4-pro is text-only)'),
+        native_search: unsupported("DeepSeek's Search and Fetch are separate per-request REST APIs, not a chat request field; the web_search sentinel is dropped (use web_extract)"),
+    },
     ollama: {
         delegation: ok(),
         memory_tools: ok(),
@@ -239,6 +249,7 @@ export const REASONING_ABOVE_HIGH = {
     openai: 'xhigh as asked on GPT-5.2 and later, and max goes as xhigh there, weakened; high, weakened, on the o-series, GPT-5 and GPT-5.1',
     xai: 'xhigh as asked on grok-4.7, and max goes as xhigh there, weakened; high, weakened, on grok-4.5 and grok-4.6',
     moonshot: 'max as asked on kimi-k3, and xhigh rounds up to max; the K2 generation takes a thinking switch, which these leave on',
+    deepseek: 'max as asked, and xhigh rounds up to max (DeepSeek has low | high | max), each beside thinking enabled',
     ollama: 'reasoning_effort high, weakened',
     gateway: 'reasoning_effort high, weakened, whatever the id: the words above high are not accepted across gateways',
 };

package/dist/lib/models/chatCompletionsAdapter.d.ts

@@ -36,7 +36,10 @@
  *     (replaysReasoningContent: Kimi) writes the response's reasoning_content
  *     as providerState on the part it preceded and sends it back on that
  *     assistant message within the current turn's tool loop, for the same
- *     provider and model only (ADR 0046).
+ *     provider and model only (ADR 0046). An adapter whose provider asks for
+ *     it on every past assistant message of a request with tools
+ *     (replaysReasoningOnEveryTurn: DeepSeek) sends it on all of them, an
+ *     empty string where none of its own is stored.
  *   - A turn that thought, or ran out of tokens, without a reply or a tool
  *     call is an error final (`<ID>_MAX_TOKENS`, `<ID>_EMPTY_RESPONSE`, ADR
  *     0027), carrying its usage. An adapter that opts in
@@ -230,6 +233,24 @@ export declare abstract class ChatCompletionsAdapter implements ModelAdapter {
      * provider asks for the field back on a tool loop turns it on (Kimi).
      */
     protected replaysReasoningContent(_model: string): boolean;
+    /**
+     * Whether, on a request that carries `tools`, EVERY assistant message in
+     * the history (earlier turns' included, not only this turn's tool loop)
+     * carries `reasoning_content`: this adapter's own stored state for the
+     * same model where there is some, else an empty string, so the field is
+     * never missing. Default: never. Only meaningful beside
+     * replaysReasoningContent (DeepSeek, whose API returns 400 on a tool
+     * request missing a past turn's reasoning_content).
+     */
+    protected replaysReasoningOnEveryTurn(_model: string): boolean;
+    /**
+     * Whether the provider enforces a strict `json_schema` response_format.
+     * Default: true. Where it takes JSON mode only (DeepSeek), an outputSchema
+     * goes as `response_format: json_object` and the schema rides in the
+     * system message instead; the engine validates the reply against it
+     * (lib/runtime/native/agentLoop.ts saveOutput).
+     */
+    protected takesStrictJsonSchema(_model: string): boolean;
     /** A precondition the call cannot be made without (e.g. no API key), or undefined when ready. */
     protected missingRequirement(): ChatFailure | undefined;
     /** The failure for a non-2xx HTTP status. */
@@ -263,4 +284,6 @@ export declare abstract class ChatCompletionsAdapter implements ModelAdapter {
     /** The function tools this adapter sends for a request: none under `toolChoice: 'none'`. */
     toolsFor(request: ModelRequest): Array<Record<string, unknown>>;
 }
+/** The system line asking for the schema where the provider takes JSON mode only (takesStrictJsonSchema). */
+export declare function schemaInstruction(schema: unknown): string;
 export {};

package/dist/lib/models/chatCompletionsAdapter.js

@@ -36,7 +36,10 @@
  *     (replaysReasoningContent: Kimi) writes the response's reasoning_content
  *     as providerState on the part it preceded and sends it back on that
  *     assistant message within the current turn's tool loop, for the same
- *     provider and model only (ADR 0046).
+ *     provider and model only (ADR 0046). An adapter whose provider asks for
+ *     it on every past assistant message of a request with tools
+ *     (replaysReasoningOnEveryTurn: DeepSeek) sends it on all of them, an
+ *     empty string where none of its own is stored.
  *   - A turn that thought, or ran out of tokens, without a reply or a tool
  *     call is an error final (`<ID>_MAX_TOKENS`, `<ID>_EMPTY_RESPONSE`, ADR
  *     0027), carrying its usage. An adapter that opts in
@@ -382,6 +385,28 @@ export class ChatCompletionsAdapter {
     replaysReasoningContent(_model) {
         return false;
     }
+    /**
+     * Whether, on a request that carries `tools`, EVERY assistant message in
+     * the history (earlier turns' included, not only this turn's tool loop)
+     * carries `reasoning_content`: this adapter's own stored state for the
+     * same model where there is some, else an empty string, so the field is
+     * never missing. Default: never. Only meaningful beside
+     * replaysReasoningContent (DeepSeek, whose API returns 400 on a tool
+     * request missing a past turn's reasoning_content).
+     */
+    replaysReasoningOnEveryTurn(_model) {
+        return false;
+    }
+    /**
+     * Whether the provider enforces a strict `json_schema` response_format.
+     * Default: true. Where it takes JSON mode only (DeepSeek), an outputSchema
+     * goes as `response_format: json_object` and the schema rides in the
+     * system message instead; the engine validates the reply against it
+     * (lib/runtime/native/agentLoop.ts saveOutput).
+     */
+    takesStrictJsonSchema(_model) {
+        return true;
+    }
     /** A precondition the call cannot be made without (e.g. no API key), or undefined when ready. */
     missingRequirement() {
         return undefined;
@@ -684,7 +709,7 @@ export class ChatCompletionsAdapter {
             ...this.reasoningFields(model, request.reasoning),
             ...(tools.length > 0 ? { tools } : {}),
             ...(tools.length > 0 ? this.#toolChoice(choice, model, request.reasoning) : {}),
-            ...this.#responseFormat(request),
+            ...this.#responseFormat(request, model),
             ...this.extraBodyFields(request),
         };
         this.#nativeTools(request.nativeTools ?? [], body, model);
@@ -713,7 +738,9 @@ export class ChatCompletionsAdapter {
      * `outputFormat: 'json'` without a schema is JSON mode (ADR 0061); each
      * of Ollama, Kimi and the gateway takes it.
      */
-    #responseFormat(request) {
+    #responseFormat(request, model) {
+        if (request.outputSchema && !this.takesStrictJsonSchema(model))
+            return { response_format: { type: 'json_object' } };
         if (request.outputSchema) {
             return { response_format: { type: 'json_schema', json_schema: { name: 'response', strict: true, schema: toStrictJsonSchema(request.outputSchema) } } };
         }
@@ -752,7 +779,13 @@ export class ChatCompletionsAdapter {
         // span providers ask for it on. Earlier turns' state is left out: the
         // stored history is not what the model saw (tool payloads are elided
         // before storage), and replaying it bills it again as input (ADR 0046).
-        const turnStart = this.replaysReasoningContent(model) ? currentTurnStart(request.messages) : Infinity;
+        // An adapter whose provider wants it on every past assistant message of
+        // a tool request (DeepSeek) replays from the first, and fills the field.
+        const everyTurn = this.replaysReasoningContent(model) && this.replaysReasoningOnEveryTurn(model) && this.toolsFor(request).length > 0;
+        const turnStart = everyTurn ? -1 : this.replaysReasoningContent(model) ? currentTurnStart(request.messages) : Infinity;
+        // JSON mode only: the schema the provider cannot hold the reply to is asked for in the system message.
+        if (request.outputSchema && !this.takesStrictJsonSchema(model))
+            system.push(schemaInstruction(request.outputSchema));
         request.messages.forEach((message, index) => {
             switch (message.role) {
                 case 'system': {
@@ -817,7 +850,7 @@ export class ChatCompletionsAdapter {
                         messages.push({
                             role: 'assistant',
                             content: text || null,
-                            ...(reasoning.length > 0 ? { reasoning_content: reasoning.join('') } : {}),
+                            ...(reasoning.length > 0 ? { reasoning_content: reasoning.join('') } : everyTurn ? { reasoning_content: '' } : {}),
                             ...(calls.length > 0 ? { tool_calls: calls } : {}),
                         });
                     }
@@ -840,6 +873,10 @@ export class ChatCompletionsAdapter {
         console.warn(message);
     }
 }
+/** The system line asking for the schema where the provider takes JSON mode only (takesStrictJsonSchema). */
+export function schemaInstruction(schema) {
+    return `Reply with one JSON object, and nothing else, that matches this JSON Schema:\n${JSON.stringify(schema)}`;
+}
 /** A tool declaration as a function tool: the schema as written, or its strict form with `strict: true`. */
 function functionTool(tool) {
     return {

package/dist/lib/models/contract.d.ts

@@ -291,7 +291,7 @@ export interface Grounding {
 /** Configuration and installation failures any adapter reports before it calls. */
 type SetupErrorCode = 'MISSING_API_KEY' | 'ENDPOINT_MISCONFIGURED' | 'SDK_NOT_INSTALLED';
 /** The chat-completions failures, under the provider's id (the gateway names the upstream provider). */
-type ChatErrorCode = `${'MOONSHOT' | 'OLLAMA' | 'GEMINI' | 'ANTHROPIC' | 'OPENAI' | 'XAI'}_${'MAX_TOKENS' | 'EMPTY_RESPONSE' | 'UNREACHABLE'}` | 'MOONSHOT_MISSING_KEY' | 'MOONSHOT_HTTP_ERROR' | 'OLLAMA_HTTP_ERROR' | 'GATEWAY_NOT_CONFIGURED' | 'GATEWAY_KEY_MISSING' | 'GATEWAY_HTTP_ERROR';
+type ChatErrorCode = `${'MOONSHOT' | 'DEEPSEEK' | 'OLLAMA' | 'GEMINI' | 'ANTHROPIC' | 'OPENAI' | 'XAI'}_${'MAX_TOKENS' | 'EMPTY_RESPONSE' | 'UNREACHABLE'}` | 'MOONSHOT_MISSING_KEY' | 'MOONSHOT_HTTP_ERROR' | 'DEEPSEEK_MISSING_KEY' | 'DEEPSEEK_HTTP_ERROR' | 'OLLAMA_HTTP_ERROR' | 'GATEWAY_NOT_CONFIGURED' | 'GATEWAY_KEY_MISSING' | 'GATEWAY_HTTP_ERROR';
 /**
  * Gemini's codes: a candidate's finish reason, or the prompt's block reason,
  * is the code itself, as ADK's adapter reported it. GEMINI_ERROR is a failed

package/dist/lib/models/deepseekAdapter.d.ts

@@ -0,0 +1,127 @@
+/**
+ * lib/models/deepseekAdapter.ts — DeepSeek behind the engine's own model
+ * contract (lib/models/contract.ts, ADR 0048).
+ *
+ * WHY this file exists:
+ *   Model optionality is a primary driver of this framework: the agent YAML
+ *   declares `model`, and the registry routes it to the right provider.
+ *   DeepSeek V4 is the cheapest capable model with tool calling and a 1M
+ *   context on a first-party API (Flash at $0.15 / $0.60 per 1M off-peak),
+ *   and its thinking mode needs request-side care the gateway cannot give
+ *   it (reasoning_content back on every tool request, below), so it earns a
+ *   direct adapter rather than only the gateway path; any `deepseek-*` id
+ *   resolves to it (resolveAdapter, lib/models/adapterResolver.ts).
+ *
+ * WHY the chat-completions base (lib/models/chatCompletionsAdapter.ts):
+ *   DeepSeek's API is OpenAI Chat Completions at https://api.deepseek.com
+ *   (`/chat/completions`; it also serves a Responses API and an
+ *   Anthropic-format API, neither adding a capability the chat dialect lacks
+ *   here). The base provides tool calling, JSON mode, SSE streaming with
+ *   usage, image parts as base64 data URIs, `reasoning_content` surfaced as
+ *   thinking, and retries.
+ *
+ * HOW TO ENABLE:
+ *   1. Create a key at https://platform.deepseek.com/api_keys and put it in
+ *      .env as DEEPSEEK_API_KEY.
+ *   2. Set model: "deepseek-flash" (or any deepseek-* id) in your YAML.
+ *   The adapter is available when the key is set (logProviderStatuses()
+ *   reports it).
+ *   Optional: DEEPSEEK_BASE_URL for a proxy that speaks the same dialect.
+ *
+ * THE FAMILY (api-docs.deepseek.com › Models & Pricing, checked 2026-10-22;
+ *   USD per 1M tokens, off-peak; peak is exactly double):
+ *
+ *     model              context  max out  in (miss) / cache hit / out   use it for
+ *     ─────────────────────────────────────────────────────────────────────────────
+ *     deepseek-flash     1M       384K     $0.15 / $0.003 / $0.60        DEFAULT — DeepSeek-V4.1-Flash-1017:
+ *                                                                        vision, tools, thinking
+ *     deepseek-v4-pro    1M       384K     $0.66 / $0.022 / $1.98        DeepSeek-V4-Pro-0813: the deeper
+ *                                                                        tier; text only, no vision
+ *
+ *   Peak hours are 01:00–04:00 and 06:00–10:00 UTC on weekdays. The price
+ *   rows (db/migrations/0019_deepseek_kimi_pricing.sql) carry the PEAK
+ *   rates, so a budget never underestimates a call.
+ *   Retired but still accepted: `deepseek-v4-flash` and
+ *   `deepseek-v4-flash-vision-exp`, both served by V4.1-Flash and billed at
+ *   Flash's price. The pre-V4 `deepseek-chat` and `deepseek-reasoner` were
+ *   retired after 2026-07-24 (third-party reports); the 404 hint names the
+ *   current ids. With no direct key, MODEL_GATEWAY serves an id as
+ *   `deepseek/<id>` (lib/models/gateway.ts), the gateways' own catalog
+ *   permitting.
+ *
+ * REASONING (ADR 0047; api-docs.deepseek.com › Thinking Mode):
+ *   Both models think by default, at effort `high`. The switch is
+ *   `thinking: { type: "enabled" | "disabled" }` in the body, the depth
+ *   `reasoning_effort` (low | high | max). A request with no `reasoning`
+ *   sends neither: the vendor's default (`high`, the middle of three) is not
+ *   its slowest, so no effort is pinned in lib/config.ts. `none` (or a
+ *   budget of 0) sends `thinking: disabled` and no effort; any other level
+ *   sends `thinking: enabled` and its DeepSeek word: `medium` → `high`,
+ *   `xhigh` → `max` (a missing word rounds up, as on Kimi K3, ADR 0117;
+ *   DeepSeek's own server-side mapping would take `xhigh` as `high`), a
+ *   budget → the level that covers it. In thinking mode temperature,
+ *   presence_penalty and frequency_penalty are ignored without an error.
+ *
+ * THINKING WITH TOOLS (the one rule this adapter exists for):
+ *   When a request carries `tools`, the `reasoning_content` of ALL previous
+ *   assistant messages must be sent back, or the API returns 400; without
+ *   tools it is ignored. The adapter turns on the base's
+ *   replaysReasoningContent and replaysReasoningOnEveryTurn: the field rides
+ *   as providerState on the part that followed it (ADR 0046) and goes back
+ *   on every assistant message of a tool request, earlier turns included,
+ *   for the same model; where none of its own is stored (an earlier turn's
+ *   state dropped by the transcript projection, another model's turn) it is
+ *   sent as an empty string, so the field is never missing. Whether DeepSeek
+ *   accepts an empty string there is not verified live. The replayed text is
+ *   billed again as input, mostly at the cache-hit price.
+ *
+ * TOOL CHOICE: auto and none. Whether thinking mode honours a forced
+ *   `tool_choice` is not documented on the thinking-mode page and not
+ *   checked live, so `required` and a named tool are weakened to auto and
+ *   marked on the span (llm.tool_choice.weakened).
+ *
+ * LIMITATIONS:
+ *   - Structured output is JSON mode (`response_format: json_object`), not a
+ *     strict schema: an outputSchema goes as JSON mode with the schema asked
+ *     for in the system message (takesStrictJsonSchema), and the engine
+ *     validates the reply. Beside tools the schema goes as set_model_response.
+ *   - web_search: DeepSeek's Search and Fetch are separate per-request REST
+ *     APIs, not a chat request field, so the sentinel is dropped with a
+ *     warning, as on Kimi; `web_extract` works.
+ *   - Vision on deepseek-flash only; an image sent to deepseek-v4-pro is
+ *     refused by the API.
+ *   - Not run live: no DeepSeek key was available when this adapter was
+ *     written (2026-10-22). Every cell of its capability row is asserted
+ *     against the request body the adapter sends
+ *     (tests/capabilityMatrix.test.ts), and the reasoning replay in
+ *     tests/models.test.ts, all offline.
+ */
+import type { ReasoningSetting } from './contract.ts';
+import { ChatCompletionsAdapter } from './chatCompletionsAdapter.ts';
+import type { ChatFailure } from './chatCompletionsAdapter.ts';
+export declare const DEEPSEEK_BASE_URL = "https://api.deepseek.com";
+export interface DeepSeekAdapterOptions {
+    /** The model id as the YAML names it: "deepseek-*". */
+    model: string;
+    /** A caller's own key; default DEEPSEEK_API_KEY, read at call time. */
+    apiKey?: string;
+    /** Default: DEEPSEEK_BASE_URL in the environment, else https://api.deepseek.com. */
+    baseUrl?: string;
+}
+export declare class DeepSeekAdapter extends ChatCompletionsAdapter {
+    #private;
+    readonly provider = "deepseek";
+    constructor({ model, apiKey, baseUrl }: DeepSeekAdapterOptions);
+    protected endpointUrl(): string;
+    protected headers(): Record<string, string>;
+    /** reasoning_content goes back on the tool loop (see the header). */
+    protected replaysReasoningContent(_model: string): boolean;
+    /** ...and on every earlier assistant message of a request with tools, or DeepSeek returns 400. */
+    protected replaysReasoningOnEveryTurn(_model: string): boolean;
+    /** JSON mode only: no strict json_schema response_format. */
+    protected takesStrictJsonSchema(_model: string): boolean;
+    protected missingRequirement(): ChatFailure | undefined;
+    protected httpError(status: number, detail: string, model: string): ChatFailure;
+    /** The thinking switch and its effort (see the header). */
+    protected reasoningFields(model: string, setting: ReasoningSetting | undefined): Record<string, unknown>;
+}

package/dist/lib/models/deepseekAdapter.js

@@ -0,0 +1,157 @@
+/**
+ * lib/models/deepseekAdapter.ts — DeepSeek behind the engine's own model
+ * contract (lib/models/contract.ts, ADR 0048).
+ *
+ * WHY this file exists:
+ *   Model optionality is a primary driver of this framework: the agent YAML
+ *   declares `model`, and the registry routes it to the right provider.
+ *   DeepSeek V4 is the cheapest capable model with tool calling and a 1M
+ *   context on a first-party API (Flash at $0.15 / $0.60 per 1M off-peak),
+ *   and its thinking mode needs request-side care the gateway cannot give
+ *   it (reasoning_content back on every tool request, below), so it earns a
+ *   direct adapter rather than only the gateway path; any `deepseek-*` id
+ *   resolves to it (resolveAdapter, lib/models/adapterResolver.ts).
+ *
+ * WHY the chat-completions base (lib/models/chatCompletionsAdapter.ts):
+ *   DeepSeek's API is OpenAI Chat Completions at https://api.deepseek.com
+ *   (`/chat/completions`; it also serves a Responses API and an
+ *   Anthropic-format API, neither adding a capability the chat dialect lacks
+ *   here). The base provides tool calling, JSON mode, SSE streaming with
+ *   usage, image parts as base64 data URIs, `reasoning_content` surfaced as
+ *   thinking, and retries.
+ *
+ * HOW TO ENABLE:
+ *   1. Create a key at https://platform.deepseek.com/api_keys and put it in
+ *      .env as DEEPSEEK_API_KEY.
+ *   2. Set model: "deepseek-flash" (or any deepseek-* id) in your YAML.
+ *   The adapter is available when the key is set (logProviderStatuses()
+ *   reports it).
+ *   Optional: DEEPSEEK_BASE_URL for a proxy that speaks the same dialect.
+ *
+ * THE FAMILY (api-docs.deepseek.com › Models & Pricing, checked 2026-10-22;
+ *   USD per 1M tokens, off-peak; peak is exactly double):
+ *
+ *     model              context  max out  in (miss) / cache hit / out   use it for
+ *     ─────────────────────────────────────────────────────────────────────────────
+ *     deepseek-flash     1M       384K     $0.15 / $0.003 / $0.60        DEFAULT — DeepSeek-V4.1-Flash-1017:
+ *                                                                        vision, tools, thinking
+ *     deepseek-v4-pro    1M       384K     $0.66 / $0.022 / $1.98        DeepSeek-V4-Pro-0813: the deeper
+ *                                                                        tier; text only, no vision
+ *
+ *   Peak hours are 01:00–04:00 and 06:00–10:00 UTC on weekdays. The price
+ *   rows (db/migrations/0019_deepseek_kimi_pricing.sql) carry the PEAK
+ *   rates, so a budget never underestimates a call.
+ *   Retired but still accepted: `deepseek-v4-flash` and
+ *   `deepseek-v4-flash-vision-exp`, both served by V4.1-Flash and billed at
+ *   Flash's price. The pre-V4 `deepseek-chat` and `deepseek-reasoner` were
+ *   retired after 2026-07-24 (third-party reports); the 404 hint names the
+ *   current ids. With no direct key, MODEL_GATEWAY serves an id as
+ *   `deepseek/<id>` (lib/models/gateway.ts), the gateways' own catalog
+ *   permitting.
+ *
+ * REASONING (ADR 0047; api-docs.deepseek.com › Thinking Mode):
+ *   Both models think by default, at effort `high`. The switch is
+ *   `thinking: { type: "enabled" | "disabled" }` in the body, the depth
+ *   `reasoning_effort` (low | high | max). A request with no `reasoning`
+ *   sends neither: the vendor's default (`high`, the middle of three) is not
+ *   its slowest, so no effort is pinned in lib/config.ts. `none` (or a
+ *   budget of 0) sends `thinking: disabled` and no effort; any other level
+ *   sends `thinking: enabled` and its DeepSeek word: `medium` → `high`,
+ *   `xhigh` → `max` (a missing word rounds up, as on Kimi K3, ADR 0117;
+ *   DeepSeek's own server-side mapping would take `xhigh` as `high`), a
+ *   budget → the level that covers it. In thinking mode temperature,
+ *   presence_penalty and frequency_penalty are ignored without an error.
+ *
+ * THINKING WITH TOOLS (the one rule this adapter exists for):
+ *   When a request carries `tools`, the `reasoning_content` of ALL previous
+ *   assistant messages must be sent back, or the API returns 400; without
+ *   tools it is ignored. The adapter turns on the base's
+ *   replaysReasoningContent and replaysReasoningOnEveryTurn: the field rides
+ *   as providerState on the part that followed it (ADR 0046) and goes back
+ *   on every assistant message of a tool request, earlier turns included,
+ *   for the same model; where none of its own is stored (an earlier turn's
+ *   state dropped by the transcript projection, another model's turn) it is
+ *   sent as an empty string, so the field is never missing. Whether DeepSeek
+ *   accepts an empty string there is not verified live. The replayed text is
+ *   billed again as input, mostly at the cache-hit price.
+ *
+ * TOOL CHOICE: auto and none. Whether thinking mode honours a forced
+ *   `tool_choice` is not documented on the thinking-mode page and not
+ *   checked live, so `required` and a named tool are weakened to auto and
+ *   marked on the span (llm.tool_choice.weakened).
+ *
+ * LIMITATIONS:
+ *   - Structured output is JSON mode (`response_format: json_object`), not a
+ *     strict schema: an outputSchema goes as JSON mode with the schema asked
+ *     for in the system message (takesStrictJsonSchema), and the engine
+ *     validates the reply. Beside tools the schema goes as set_model_response.
+ *   - web_search: DeepSeek's Search and Fetch are separate per-request REST
+ *     APIs, not a chat request field, so the sentinel is dropped with a
+ *     warning, as on Kimi; `web_extract` works.
+ *   - Vision on deepseek-flash only; an image sent to deepseek-v4-pro is
+ *     refused by the API.
+ *   - Not run live: no DeepSeek key was available when this adapter was
+ *     written (2026-10-22). Every cell of its capability row is asserted
+ *     against the request body the adapter sends
+ *     (tests/capabilityMatrix.test.ts), and the reasoning replay in
+ *     tests/models.test.ts, all offline.
+ */
+import { ChatCompletionsAdapter, reasonsNotAtAll } from './chatCompletionsAdapter.js';
+import { trimTrailingSlashes } from './urls.js';
+import { credentialValue } from './credentialSource.js';
+export const DEEPSEEK_BASE_URL = 'https://api.deepseek.com';
+export class DeepSeekAdapter extends ChatCompletionsAdapter {
+    provider = 'deepseek';
+    #apiKey;
+    #baseUrl;
+    constructor({ model, apiKey, baseUrl }) {
+        super({ model });
+        this.#apiKey = apiKey;
+        this.#baseUrl = trimTrailingSlashes(baseUrl || process.env.DEEPSEEK_BASE_URL || DEEPSEEK_BASE_URL);
+    }
+    endpointUrl() {
+        return `${this.#baseUrl}/chat/completions`;
+    }
+    #key() {
+        return this.#apiKey ?? credentialValue('DEEPSEEK_API_KEY');
+    }
+    headers() {
+        return { Authorization: `Bearer ${this.#key() ?? ''}` };
+    }
+    /** reasoning_content goes back on the tool loop (see the header). */
+    replaysReasoningContent(_model) {
+        return true;
+    }
+    /** ...and on every earlier assistant message of a request with tools, or DeepSeek returns 400. */
+    replaysReasoningOnEveryTurn(_model) {
+        return true;
+    }
+    /** JSON mode only: no strict json_schema response_format. */
+    takesStrictJsonSchema(_model) {
+        return false;
+    }
+    missingRequirement() {
+        if (this.#key())
+            return undefined;
+        return { code: 'DEEPSEEK_MISSING_KEY', message: 'DEEPSEEK_API_KEY is not set in environment.' };
+    }
+    httpError(status, detail, model) {
+        const hint = status === 401
+            ? ' Check DEEPSEEK_API_KEY (platform.deepseek.com/api_keys).'
+            : status === 404
+                ? ` Is "${model}" a current DeepSeek id? The current ids are deepseek-flash and deepseek-v4-pro; deepseek-chat and deepseek-reasoner were retired after 2026-07-24.`
+                : '';
+        return {
+            code: 'DEEPSEEK_HTTP_ERROR',
+            message: `DeepSeek returned ${status}: ${detail.slice(0, 4000)}.${hint}`,
+        };
+    }
+    /** The thinking switch and its effort (see the header). */
+    reasoningFields(model, setting) {
+        if (setting === undefined)
+            return {}; // DeepSeek's default: thinking on, effort high
+        if (reasonsNotAtAll(setting))
+            return { thinking: { type: 'disabled' } };
+        return { thinking: { type: 'enabled' }, reasoning_effort: this.effortFor(model, setting) };
+    }
+}

package/dist/lib/models/endpoints.d.ts

@@ -11,7 +11,8 @@
  *   gemini     direct | vertex           Google Application Default Credentials
  *   anthropic  direct | bedrock | vertex AWS credential chain / Google ADC
  *   openai     direct | azure            AZURE_OPENAI_API_KEY, else Entra ID
- *   xai, moonshot, ollama  direct only (moonshot: MOONSHOT_BASE_URL for a proxy)
+ *   xai, moonshot, deepseek, ollama  direct only (moonshot, deepseek:
+ *              MOONSHOT_BASE_URL, DEEPSEEK_BASE_URL for a proxy)
  *
  * Configuration comes from the environment (`endpointFromEnv`) or, per
  * request, from the server's `credentials` plug point, which may return an

package/dist/lib/models/endpoints.js

@@ -11,7 +11,8 @@
  *   gemini     direct | vertex           Google Application Default Credentials
  *   anthropic  direct | bedrock | vertex AWS credential chain / Google ADC
  *   openai     direct | azure            AZURE_OPENAI_API_KEY, else Entra ID
- *   xai, moonshot, ollama  direct only (moonshot: MOONSHOT_BASE_URL for a proxy)
+ *   xai, moonshot, deepseek, ollama  direct only (moonshot, deepseek:
+ *              MOONSHOT_BASE_URL, DEEPSEEK_BASE_URL for a proxy)
  *
  * Configuration comes from the environment (`endpointFromEnv`) or, per
  * request, from the server's `credentials` plug point, which may return an
@@ -38,6 +39,7 @@ export const PLATFORMS_FOR = {
     openai: ['direct', 'azure'],
     xai: ['direct'],
     moonshot: ['direct'],
+    deepseek: ['direct'],
     ollama: ['direct'],
 };
 const PLATFORM_ENV = {
@@ -104,6 +106,8 @@ export function endpointFromEnv(provider, env = credentialEnv()) {
             return { ...base, ...(trimmed(env.OPENAI_BASE_URL) ? { baseURL: trimmed(env.OPENAI_BASE_URL) } : {}) };
         case 'moonshot/direct':
             return { ...base, ...(trimmed(env.MOONSHOT_BASE_URL) ? { baseURL: trimmed(env.MOONSHOT_BASE_URL) } : {}) };
+        case 'deepseek/direct':
+            return { ...base, ...(trimmed(env.DEEPSEEK_BASE_URL) ? { baseURL: trimmed(env.DEEPSEEK_BASE_URL) } : {}) };
         case 'openai/azure': {
             const endpoint = trimmed(env.AZURE_OPENAI_ENDPOINT);
             const key = trimmed(env.AZURE_OPENAI_API_KEY);

package/dist/lib/models/gateway.d.ts

@@ -4,7 +4,7 @@
  * WHY this file exists:
  *   A newcomer should be able to run every starter-pack syndicate with ONE
  *   credential when they choose to. A hosted gateway (Vercel AI Gateway,
- *   OpenRouter) fronts OpenAI, Anthropic, Google, xAI and Moonshot behind a single
+ *   OpenRouter) fronts OpenAI, Anthropic, Google, xAI, Moonshot and DeepSeek behind a single
  *   OpenAI-compatible endpoint, so a model id whose direct key is absent can
  *   still be served. This module owns that decision and nothing else.
  *
@@ -81,7 +81,8 @@ export declare function gatewayUsable(): boolean;
  * Gateways prefix every id with the upstream provider's slug and spell
  * Anthropic's version segment with a dot ("claude-sonnet-4-6" is
  * "anthropic/claude-sonnet-4.6" on both Vercel and OpenRouter). Gemini,
- * GPT, Grok and Kimi ids already carry dots, so only the prefix is added. An id
+ * GPT, Grok, Kimi and DeepSeek ids already carry dots (or need none), so only the
+ * prefix is added. An id
  * the mapper gets wrong is fixed in MODEL_GATEWAY_MODEL_MAP, not in code.
  */
 export declare function gatewayWireModel(model: string, gateway: GatewayInfo): string;

package/dist/lib/models/gateway.js

@@ -4,7 +4,7 @@
  * WHY this file exists:
  *   A newcomer should be able to run every starter-pack syndicate with ONE
  *   credential when they choose to. A hosted gateway (Vercel AI Gateway,
- *   OpenRouter) fronts OpenAI, Anthropic, Google, xAI and Moonshot behind a single
+ *   OpenRouter) fronts OpenAI, Anthropic, Google, xAI, Moonshot and DeepSeek behind a single
  *   OpenAI-compatible endpoint, so a model id whose direct key is absent can
  *   still be served. This module owns that decision and nothing else.
  *
@@ -52,14 +52,14 @@ export const GATEWAYS = {
         label: 'Vercel AI Gateway',
         baseUrl: 'https://ai-gateway.vercel.sh/v1',
         consoleUrl: 'https://vercel.com/ai-gateway',
-        slugs: { gemini: 'google', anthropic: 'anthropic', openai: 'openai', xai: 'xai', moonshot: 'moonshotai' },
+        slugs: { gemini: 'google', anthropic: 'anthropic', openai: 'openai', xai: 'xai', moonshot: 'moonshotai', deepseek: 'deepseek' },
     },
     openrouter: {
         id: 'openrouter',
         label: 'OpenRouter',
         baseUrl: 'https://openrouter.ai/api/v1',
         consoleUrl: 'https://openrouter.ai/keys',
-        slugs: { gemini: 'google', anthropic: 'anthropic', openai: 'openai', xai: 'x-ai', moonshot: 'moonshotai' },
+        slugs: { gemini: 'google', anthropic: 'anthropic', openai: 'openai', xai: 'x-ai', moonshot: 'moonshotai', deepseek: 'deepseek' },
     },
 };
 /**
@@ -124,7 +124,8 @@ function modelMapFromEnv() {
  * Gateways prefix every id with the upstream provider's slug and spell
  * Anthropic's version segment with a dot ("claude-sonnet-4-6" is
  * "anthropic/claude-sonnet-4.6" on both Vercel and OpenRouter). Gemini,
- * GPT, Grok and Kimi ids already carry dots, so only the prefix is added. An id
+ * GPT, Grok, Kimi and DeepSeek ids already carry dots (or need none), so only the
+ * prefix is added. An id
  * the mapper gets wrong is fixed in MODEL_GATEWAY_MODEL_MAP, not in code.
  */
 export function gatewayWireModel(model, gateway) {

package/dist/lib/models/gatewayAdapter.d.ts

@@ -12,7 +12,7 @@
  *
  * WHAT STAYS TRUE THROUGH THE GATEWAY:
  *   - Attribution. `provider` is the YAML id's provider (anthropic, openai,
- *     gemini, xai, moonshot), never "gateway", so the ledger and any
+ *     gemini, xai, moonshot, deepseek), never "gateway", so the ledger and any
  *     per-agent cost view keep the same provider column (ADR 0009). The
  *     transport is a separate span attribute: llm.transport = gateway:<id>.
  *   - Tool calling, structured output, reasoning (as `reasoning_effort`, the

package/dist/lib/models/gatewayAdapter.js

@@ -12,7 +12,7 @@
  *
  * WHAT STAYS TRUE THROUGH THE GATEWAY:
  *   - Attribution. `provider` is the YAML id's provider (anthropic, openai,
- *     gemini, xai, moonshot), never "gateway", so the ledger and any
+ *     gemini, xai, moonshot, deepseek), never "gateway", so the ledger and any
  *     per-agent cost view keep the same provider column (ADR 0009). The
  *     transport is a separate span attribute: llm.transport = gateway:<id>.
  *   - Tool calling, structured output, reasoning (as `reasoning_effort`, the

package/dist/lib/models/providerMap.d.ts

@@ -11,9 +11,10 @@
  * Model-name conventions (see DOCUMENTATION.md §7):
  *   claude-*   → anthropic     gpt-* / o<digit>* → openai
  *   grok-*     → xai           ollama/<model>    → ollama (local, keyless)
- *   kimi-*     → moonshot      everything else   → gemini (the default)
+ *   kimi-*     → moonshot      deepseek-*        → deepseek
+ *   everything else → gemini (the default)
  */
-export type ProviderId = 'gemini' | 'anthropic' | 'openai' | 'xai' | 'moonshot' | 'ollama';
+export type ProviderId = 'gemini' | 'anthropic' | 'openai' | 'xai' | 'moonshot' | 'deepseek' | 'ollama';
 interface ProviderInfo {
     /** Env var holding the API key; null = keyless (local). */
     keyEnv: string | null;

package/dist/lib/models/providerMap.js

@@ -11,7 +11,8 @@
  * Model-name conventions (see DOCUMENTATION.md §7):
  *   claude-*   → anthropic     gpt-* / o<digit>* → openai
  *   grok-*     → xai           ollama/<model>    → ollama (local, keyless)
- *   kimi-*     → moonshot      everything else   → gemini (the default)
+ *   kimi-*     → moonshot      deepseek-*        → deepseek
+ *   everything else → gemini (the default)
  */
 import { credentialValue } from './credentialSource.js';
 export const PROVIDERS = {
@@ -20,6 +21,7 @@ export const PROVIDERS = {
     openai: { keyEnv: 'OPENAI_API_KEY', label: 'OpenAI GPT' },
     xai: { keyEnv: 'XAI_API_KEY', label: 'xAI Grok' },
     moonshot: { keyEnv: 'MOONSHOT_API_KEY', label: 'Moonshot Kimi' },
+    deepseek: { keyEnv: 'DEEPSEEK_API_KEY', label: 'DeepSeek' },
     ollama: { keyEnv: null, label: 'Ollama (local)' },
 };
 /** Maps a model id to its provider. Unknown ids default to gemini, as
@@ -35,6 +37,8 @@ export function providerForModel(model) {
         return 'xai';
     if (/^kimi-/.test(model))
         return 'moonshot';
+    if (/^deepseek-/.test(model))
+        return 'deepseek';
     return 'gemini';
 }
 /** True when the provider's key is present (always true for local Ollama). */