melchizedek-agents 1.10.2 → 1.11.0

package/config/agents/syndicateSchema.yaml

@@ -269,6 +269,7 @@ orchestrator:
   #   gpt-* /o* → OpenAI        (OPENAI_API_KEY)
   #   grok-*    → xAI           (XAI_API_KEY)
   #   kimi-*    → Moonshot Kimi (MOONSHOT_API_KEY)
+  #   deepseek-* → DeepSeek     (DEEPSEEK_API_KEY)
   #   ollama/*  → local Ollama  (keyless)
   # Subagents inherit this if not set on their own config.
   model: "gemini-3.5-flash-lite"
@@ -443,14 +444,16 @@ orchestrator:
   #                           that effort; none is the model's off switch,
   #                           or low effort on Opus 5 and 5.5, Fable and
   #                           Mythos (ADR 0049)
-  #   gpt-*/o*, grok-*, kimi-*, ollama/*, a gateway
+  #   gpt-*/o*, grok-*, kimi-*, deepseek-*, ollama/*, a gateway
   #                         → reasoningEffort (an effort word; where the
-  #                           provider lacks one, its nearest setting above)
+  #                           provider lacks one, its nearest setting above;
+  #                           deepseek-* beside thinking enabled, and none
+  #                           as thinking disabled)
   # A budget is sent as-is to Gemini and to Claude 4.6 and earlier, and as
   # the smallest level that covers it everywhere else. Unset, each provider
   # keeps its default.
   # xhigh and max (ADR 0117) reach the models that take them: both on later
-  # claude-*, max on kimi-k3 (xhigh rounds up to it), xhigh on gpt-5.2 and
+  # claude-*, max on kimi-k3 and deepseek-* (xhigh rounds up to it), xhigh on gpt-5.2 and
   # later and grok-4.7. Elsewhere the model's highest setting is sent and
   # the span carries llm.reasoning.weakened; a gateway gets high.
   # Cannot be combined with generateContentConfig.thinkingConfig or
@@ -466,7 +469,8 @@ orchestrator:
     # Sampling temperature. Lower = more deterministic. Range: [0.0, 2.0]
     # ⚠ Do NOT set this on current Gemini models — they are tuned for their
     #   own default sampling and the knob is not part of their contract.
-    #   Set it only for claude-*, gpt-*, grok-*, kimi-*, or ollama/* agents.
+    #   Set it only for claude-*, gpt-*, grok-*, kimi-*, or ollama/* agents
+    #   (DeepSeek ignores it while thinking, its default).
     # temperature: 0.7
 
     # Nucleus sampling. Tokens sampled until cumulative prob = top_p.
@@ -504,7 +508,7 @@ orchestrator:
   # ── model_overrides ───────────────────────────────────────
   # [optional] A prompt nuance for one provider (ADR 0115). Keys are the
   # providers a model id routes to: gemini, anthropic, openai, xai,
-  # moonshot, ollama. Each holds ONE of:
+  # moonshot, deepseek, ollama. Each holds ONE of:
   #   instruction:         replaces the instruction on that provider
   #   instruction_append:  added after the instruction, after a blank line
   # Applied for the provider of this agent's model, before the skills

package/db/migrations/0019_deepseek_kimi_pricing.sql

@@ -0,0 +1,48 @@
+-- ============================================================================
+-- 0019_deepseek_kimi_pricing — price rows for DeepSeek and Moonshot Kimi
+--                              (extends ADR 0136 and ADR 0139)
+-- ============================================================================
+-- Rows only, in 0017's column layout (USD per million tokens):
+--   input_per_mtok        an input token that is not a cache hit
+--   output_per_mtok       an output token (thinking included: NULL thinking
+--                         rate, so thinking prices at the output rate)
+--   cache_read_per_mtok   an input token read from the provider's cache
+--   cache_write_per_mtok  NULL: neither vendor bills a cache write, so a
+--                         written token prices as input
+--
+-- DeepSeek (lib/models/deepseekAdapter.ts): the PEAK rates. DeepSeek bills
+-- off-peak at half, and peak (01:00–04:00 and 06:00–10:00 UTC on weekdays)
+-- at exactly double the off-peak list; a flat row cannot say the hour, so
+-- it holds the higher rate and a budget never underestimates a call.
+-- Off-peak per 1M: deepseek-flash $0.15 in / $0.003 cache hit / $0.60 out;
+-- deepseek-v4-pro $0.66 / $0.022 / $1.98. Checked 2026-10-22 against
+-- api-docs.deepseek.com/quick_start/pricing. The retired deepseek-v4-flash
+-- and deepseek-v4-flash-vision-exp ids are still accepted, served by
+-- V4.1-Flash and billed at Flash's price, so they get Flash's row.
+--
+-- Moonshot Kimi (lib/models/kimiAdapter.ts): no row until now. The rates
+-- are the family table in the adapter's header (platform.moonshot.ai ›
+-- Model list, October 2026); verified_at stays NULL because this migration
+-- did not re-check them against the vendor's list (0015's convention: spend
+-- built on the row is a steering estimate until someone does).
+--
+-- New rows never overwrite a row that exists: an operator's own rates
+-- survive. Nothing secret, nothing personal. Idempotent; safe to re-run.
+-- ============================================================================
+
+INSERT INTO model_pricing (model, input_per_mtok, output_per_mtok, cache_read_per_mtok, cache_write_per_mtok, verified_at, source, note) VALUES
+  -- DeepSeek, peak rates (double the off-peak list).
+  ('deepseek-flash',               0.30, 1.20, 0.006, NULL, '2026-10-22', 'api-docs.deepseek.com/quick_start/pricing', 'DeepSeek first-party, checked 2026-10-22; PEAK rate (01:00-04:00 and 06:00-10:00 UTC weekdays), double the off-peak $0.15 / $0.003 / $0.60, held so budgets never underestimate'),
+  ('deepseek-v4-pro',              1.32, 3.96, 0.044, NULL, '2026-10-22', 'api-docs.deepseek.com/quick_start/pricing', 'DeepSeek first-party, checked 2026-10-22; PEAK rate (01:00-04:00 and 06:00-10:00 UTC weekdays), double the off-peak $0.66 / $0.022 / $1.98, held so budgets never underestimate'),
+  ('deepseek-v4-flash',            0.30, 1.20, 0.006, NULL, '2026-10-22', 'api-docs.deepseek.com/quick_start/pricing', 'DeepSeek first-party, checked 2026-10-22; retired id served by V4.1-Flash and billed at Flash price; PEAK rate, double the off-peak $0.15 / $0.003 / $0.60'),
+  ('deepseek-v4-flash-vision-exp', 0.30, 1.20, 0.006, NULL, '2026-10-22', 'api-docs.deepseek.com/quick_start/pricing', 'DeepSeek first-party, checked 2026-10-22; retired id served by V4.1-Flash and billed at Flash price; PEAK rate, double the off-peak $0.15 / $0.003 / $0.60'),
+  -- Moonshot Kimi, from the family table in lib/models/kimiAdapter.ts.
+  ('kimi-k3',                      3.00, 15.00, 0.30, NULL, NULL, 'platform.moonshot.ai (Model list, October 2026), via the family table in lib/models/kimiAdapter.ts', 'Moonshot first-party; not re-checked by this migration'),
+  ('kimi-k2.6',                    0.95,  4.00, 0.16, NULL, NULL, 'platform.moonshot.ai (Model list, October 2026), via the family table in lib/models/kimiAdapter.ts', 'Moonshot first-party; not re-checked by this migration'),
+  ('kimi-k2.7-code',               0.95,  4.00, 0.19, NULL, NULL, 'platform.moonshot.ai (Model list, October 2026), via the family table in lib/models/kimiAdapter.ts', 'Moonshot first-party; not re-checked by this migration'),
+  ('kimi-k2.7-code-highspeed',     1.90,  8.00, 0.38, NULL, NULL, 'platform.moonshot.ai (Model list, October 2026), via the family table in lib/models/kimiAdapter.ts', 'Moonshot first-party; not re-checked by this migration')
+ON CONFLICT (model) DO NOTHING;
+
+INSERT INTO melchizedek_schema_version (version, name)
+VALUES (19, '0019_deepseek_kimi_pricing')
+ON CONFLICT (version) DO NOTHING;

package/dist/lib/config.d.ts

@@ -77,6 +77,17 @@ export declare const DEFAULT_KIMI_MODEL = "kimi-k3";
  * override. Source: platform.moonshot.ai › Guides › Reasoning effort.
  */
 export declare const DEFAULT_KIMI_REASONING_EFFORT = "high";
+/**
+ * Default DeepSeek model used when a deepseek-* model is requested but no
+ * specific identifier is provided. Requires DEEPSEEK_API_KEY
+ * (lib/models/deepseekAdapter.ts). deepseek-flash (DeepSeek-V4.1-Flash) is
+ * the cheap tier with vision, at $0.15 / $0.60 per 1M off-peak;
+ * deepseek-v4-pro is the deeper, text-only tier at about four times that
+ * (the family table and peak pricing are in the adapter's header).
+ * No reasoning effort is pinned: DeepSeek's own default is `high`, the
+ * middle of its three levels (low | high | max), not its slowest.
+ */
+export declare const DEFAULT_DEEPSEEK_MODEL = "deepseek-flash";
 /**
  * Model calls one turn may make, subagents included, when the syndicate sets
  * no `max_steps`. A runaway tool loop stops here instead of at the provider's

package/dist/lib/config.js

@@ -78,6 +78,17 @@ export const DEFAULT_KIMI_MODEL = 'kimi-k3';
  * override. Source: platform.moonshot.ai › Guides › Reasoning effort.
  */
 export const DEFAULT_KIMI_REASONING_EFFORT = 'high';
+/**
+ * Default DeepSeek model used when a deepseek-* model is requested but no
+ * specific identifier is provided. Requires DEEPSEEK_API_KEY
+ * (lib/models/deepseekAdapter.ts). deepseek-flash (DeepSeek-V4.1-Flash) is
+ * the cheap tier with vision, at $0.15 / $0.60 per 1M off-peak;
+ * deepseek-v4-pro is the deeper, text-only tier at about four times that
+ * (the family table and peak pricing are in the adapter's header).
+ * No reasoning effort is pinned: DeepSeek's own default is `high`, the
+ * middle of its three levels (low | high | max), not its slowest.
+ */
+export const DEFAULT_DEEPSEEK_MODEL = 'deepseek-flash';
 /**
  * Model calls one turn may make, subagents included, when the syndicate sets
  * no `max_steps`. A runaway tool loop stops here instead of at the provider's

package/dist/lib/doctor.js

@@ -178,6 +178,7 @@ export const CONSOLE_URLS = {
     openai: 'https://platform.openai.com/api-keys',
     xai: 'https://console.x.ai',
     moonshot: 'https://platform.moonshot.ai',
+    deepseek: 'https://platform.deepseek.com/api_keys',
     ollama: 'https://ollama.com',
 };
 // ── Discovery ────────────────────────────────────────────────────────────────
@@ -603,6 +604,7 @@ const PROBE_ID = {
     openai: 'gpt-x',
     xai: 'grok-x',
     moonshot: 'kimi-x',
+    deepseek: 'deepseek-x',
     ollama: 'ollama/x',
 };
 /**

package/dist/lib/loadSyndicate.d.ts

@@ -149,7 +149,7 @@ export interface AgentYamlConfig {
      * appended after a blank line, for the provider of the model the agent runs
      * on. Applied at compile time, before the skills index; not for fallback_model.
      */
-    model_overrides?: Partial<Record<'gemini' | 'anthropic' | 'openai' | 'xai' | 'moonshot' | 'ollama', {
+    model_overrides?: Partial<Record<'gemini' | 'anthropic' | 'openai' | 'xai' | 'moonshot' | 'deepseek' | 'ollama', {
         instruction?: string;
         instruction_append?: string;
     }>>;

package/dist/lib/model.d.ts

@@ -30,6 +30,8 @@ export { ChatCompletionsAdapter } from './models/chatCompletionsAdapter.ts';
 export type { ChatCompletionsAdapterOptions } from './models/chatCompletionsAdapter.ts';
 export { KimiAdapter } from './models/kimiAdapter.ts';
 export type { KimiAdapterOptions } from './models/kimiAdapter.ts';
+export { DeepSeekAdapter } from './models/deepseekAdapter.ts';
+export type { DeepSeekAdapterOptions } from './models/deepseekAdapter.ts';
 export { OllamaAdapter } from './models/ollamaAdapter.ts';
 export type { OllamaAdapterOptions } from './models/ollamaAdapter.ts';
 export { GatewayAdapter } from './models/gatewayAdapter.ts';

package/dist/lib/model.js

@@ -23,6 +23,7 @@ export { GptAdapter } from './models/gptAdapter.js';
 export { GrokAdapter } from './models/grokAdapter.js';
 export { ChatCompletionsAdapter } from './models/chatCompletionsAdapter.js';
 export { KimiAdapter } from './models/kimiAdapter.js';
+export { DeepSeekAdapter } from './models/deepseekAdapter.js';
 export { OllamaAdapter } from './models/ollamaAdapter.js';
 export { GatewayAdapter } from './models/gatewayAdapter.js';
 export { GeminiAdapter } from './models/geminiAdapter.js';

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>;
+}