melchizedek-agents 1.10.2 → 1.11.0

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). */

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

@@ -26,7 +26,7 @@ export declare const isAboveHigh: (setting: ReasoningSetting | undefined) => set
  * The highest level the direct adapter for `model` sends as asked (ADR
  * 0117); a level above it goes as this one. `max` where every level
  * passes: Claude's adaptive generations (the Claude adapter sends its budget
- * generations `high`'s budget) and Kimi K3. OpenAI's GPT-5.2 and later and
+ * generations `high`'s budget), Kimi K3 and DeepSeek. OpenAI's GPT-5.2 and later and
  * grok-4.7 stop at `xhigh`; other OpenAI and Grok ids, Gemini and Ollama at
  * `high`. A gateway stops at `high` whatever the id (gatewayAdapter.ts).
  */

package/dist/lib/models/reasoning.js

@@ -44,7 +44,8 @@ function reasoningEffort(model, level) {
         case 'xai':
             return level === 'none' ? 'low' : level; // Grok 4.5/4.7 cannot stop reasoning
         case 'moonshot':
-            // K3 has low | high | max: a missing word rounds up.
+        case 'deepseek':
+            // K3 and DeepSeek have low | high | max: a missing word rounds up.
             return level === 'medium' ? 'high' : level === 'xhigh' ? 'max' : level;
         default:
             return level;
@@ -54,7 +55,7 @@ function reasoningEffort(model, level) {
  * The highest level the direct adapter for `model` sends as asked (ADR
  * 0117); a level above it goes as this one. `max` where every level
  * passes: Claude's adaptive generations (the Claude adapter sends its budget
- * generations `high`'s budget) and Kimi K3. OpenAI's GPT-5.2 and later and
+ * generations `high`'s budget), Kimi K3 and DeepSeek. OpenAI's GPT-5.2 and later and
  * grok-4.7 stop at `xhigh`; other OpenAI and Grok ids, Gemini and Ollama at
  * `high`. A gateway stops at `high` whatever the id (gatewayAdapter.ts).
  */
@@ -62,6 +63,7 @@ export function effortCeiling(model) {
     switch (providerForModel(model)) {
         case 'anthropic':
         case 'moonshot':
+        case 'deepseek':
             return 'max';
         case 'openai':
             return openAiTakesXhigh(model) ? 'xhigh' : 'high';

package/dist/lib/models/registry.js

@@ -23,7 +23,7 @@
  * resolves when an agent first calls it.
  */
 import { endpointFromEnv, endpointProblems, providerReady } from './endpoints.js';
-import { DEFAULT_CLAUDE_MODEL, DEFAULT_GEMINI_MODEL, DEFAULT_GPT_MODEL, DEFAULT_GROK_MODEL, DEFAULT_KIMI_MODEL, DEFAULT_OLLAMA_MODEL, } from '../config.js';
+import { DEFAULT_CLAUDE_MODEL, DEFAULT_GEMINI_MODEL, DEFAULT_GPT_MODEL, DEFAULT_GROK_MODEL, DEFAULT_KIMI_MODEL, DEFAULT_DEEPSEEK_MODEL, DEFAULT_OLLAMA_MODEL, } from '../config.js';
 import { geminiAdapterSetting, normalizeProvider, resolveAdapter } from './adapterResolver.js';
 import { gatewayConfig, gatewayProblem, gatewayUsable } from './gateway.js';
 import { PROVIDERS, providerForModel, providerKeyPresent, } from './providerMap.js';
@@ -105,6 +105,8 @@ function modelHint(provider) {
             return 'grok-*';
         case 'moonshot':
             return 'kimi-*';
+        case 'deepseek':
+            return 'deepseek-*';
         case 'ollama':
             return 'ollama/*';
         case 'gemini':
@@ -117,6 +119,7 @@ const DEFAULT_MODEL_FOR = {
     openai: DEFAULT_GPT_MODEL,
     xai: DEFAULT_GROK_MODEL,
     moonshot: DEFAULT_KIMI_MODEL,
+    deepseek: DEFAULT_DEEPSEEK_MODEL,
     ollama: DEFAULT_OLLAMA_MODEL,
 };
 /**

package/dist/lib/observability/tracer.d.ts

@@ -155,7 +155,7 @@ export declare function validTraceparent(value: unknown): string | undefined;
 export declare function callerSpanContext(traceparent: string | undefined): SpanContext | undefined;
 export declare function traceAgentRun(stream: AsyncIterableIterator<Event>, metadata: TraceMetadata): AsyncGenerator<Event, void, void>;
 export interface LlmCallMeta {
-    /** Provider id, e.g. 'anthropic', 'openai', 'xai', 'moonshot', 'ollama', 'gemini'. */
+    /** Provider id, e.g. 'anthropic', 'openai', 'xai', 'moonshot', 'deepseek', 'ollama', 'gemini'. */
     provider: string;
     /** The model id as declared in the agent YAML (e.g. 'ollama/qwen3:8b'). */
     model: string;

package/dist/lib/onboarding.js

@@ -106,6 +106,7 @@ const PROVIDER_CONSOLE = {
     openai: 'https://platform.openai.com/api-keys',
     xai: 'https://console.x.ai',
     moonshot: 'https://platform.moonshot.ai',
+    deepseek: 'https://platform.deepseek.com/api_keys',
 };
 const PREFIX = {
     gemini: 'gemini-* (and any id without another prefix)',
@@ -113,6 +114,7 @@ const PREFIX = {
     openai: 'gpt-*, o<digit>*',
     xai: 'grok-*',
     moonshot: 'kimi-*',
+    deepseek: 'deepseek-*',
 };
 const CLOUD_PROVIDERS = Object.keys(PROVIDER_CONSOLE);
 function providerKeyLines() {
@@ -154,7 +156,7 @@ export const LEVELS = [
     },
     {
         id: 'one-provider',
-        menu: "One provider's API key (Gemini, Anthropic, OpenAI, xAI or Moonshot)",
+        menu: "One provider's API key (Gemini, Anthropic, OpenAI, xAI, Moonshot or DeepSeek)",
         title: "One provider's API key",
         summary: "The model id's prefix picks the provider, and that provider's key funds it. One key runs every file whose agents all use that provider. A Gemini key runs the most shipped files and also powers long-term memory's embeddings.",
         env: providerKeyLines(),

package/dist/lib/syndicateSchema.d.ts

@@ -120,6 +120,10 @@ export declare const agentSchema: z.ZodObject<{
             instruction: z.ZodOptional<z.ZodString>;
             instruction_append: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
+        deepseek: z.ZodOptional<z.ZodObject<{
+            instruction: z.ZodOptional<z.ZodString>;
+            instruction_append: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
         ollama: z.ZodOptional<z.ZodObject<{
             instruction: z.ZodOptional<z.ZodString>;
             instruction_append: z.ZodOptional<z.ZodString>;
@@ -338,6 +342,10 @@ export declare const subagentSchema: z.ZodObject<{
             instruction: z.ZodOptional<z.ZodString>;
             instruction_append: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
+        deepseek: z.ZodOptional<z.ZodObject<{
+            instruction: z.ZodOptional<z.ZodString>;
+            instruction_append: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
         ollama: z.ZodOptional<z.ZodObject<{
             instruction: z.ZodOptional<z.ZodString>;
             instruction_append: z.ZodOptional<z.ZodString>;
@@ -562,6 +570,10 @@ export declare const syndicateSchema: z.ZodObject<{
                 instruction: z.ZodOptional<z.ZodString>;
                 instruction_append: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>>;
+            deepseek: z.ZodOptional<z.ZodObject<{
+                instruction: z.ZodOptional<z.ZodString>;
+                instruction_append: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
             ollama: z.ZodOptional<z.ZodObject<{
                 instruction: z.ZodOptional<z.ZodString>;
                 instruction_append: z.ZodOptional<z.ZodString>;
@@ -774,6 +786,10 @@ export declare const syndicateSchema: z.ZodObject<{
                 instruction: z.ZodOptional<z.ZodString>;
                 instruction_append: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>>;
+            deepseek: z.ZodOptional<z.ZodObject<{
+                instruction: z.ZodOptional<z.ZodString>;
+                instruction_append: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
             ollama: z.ZodOptional<z.ZodObject<{
                 instruction: z.ZodOptional<z.ZodString>;
                 instruction_append: z.ZodOptional<z.ZodString>;

package/dist/lib/syndicateSchema.js

@@ -146,6 +146,7 @@ const modelOverridesSchema = z
     openai: modelOverrideEntry.optional(),
     xai: modelOverrideEntry.optional(),
     moonshot: modelOverrideEntry.optional(),
+    deepseek: modelOverrideEntry.optional(),
     ollama: modelOverrideEntry.optional(),
 })
     .describe('Per-provider instruction, keyed by the provider of the agent\'s model id (lib/models/providerMap.ts). Applied at compile time before the skills index; not to fallback_model, and never to globalInstruction (ADR 0115).');

package/dist/lib/toolRegistry.js

@@ -56,7 +56,7 @@ const BUILTIN_TOOLS = {
     web_search: WEB_SEARCH_MARKER,
     // Deterministic complement to web_search: client-side URL → clean-text
     // reading (keyless — works on every provider, including local Ollama).
-    // augustin.yaml and librarian-style research agents declare it.
+    // current_events.yaml and librarian-style research agents declare it.
     web_extract: webExtractTool,
     // Gemini reads URLs in the conversation server-side; a no-op (reported as
     // dropped by the doctor) on other providers. lib/tools/nativeTools.ts.

package/dist/lib/tools/credentialEnv.js

@@ -17,7 +17,7 @@
 /** Prefixes and names of variables the framework itself reads: never an API credential. */
 const FRAMEWORK_ENV_PREFIXES = [
     'A2A_', 'SUPABASE_', 'DATABASE_', 'MCP_', 'MODEL_', 'MEMORY_', 'OTEL_', 'TELEMETRY_', 'MELCHIZEDEK_',
-    'GOOGLE_', 'GEMINI_', 'ANTHROPIC_', 'OPENAI_', 'AZURE_', 'AWS_', 'XAI_', 'MOONSHOT_', 'OLLAMA_', 'WIKI_',
+    'GOOGLE_', 'GEMINI_', 'ANTHROPIC_', 'OPENAI_', 'AZURE_', 'AWS_', 'XAI_', 'MOONSHOT_', 'DEEPSEEK_', 'OLLAMA_', 'WIKI_',
     'ALLOW_', 'OPENAPI_',
 ];
 const FRAMEWORK_ENV_NAMES = new Set(['PUBLIC_URL', 'HOST', 'PORT', 'PATH', 'HOME', 'NODE_OPTIONS', 'WEB_EXTRACT_CHAR_LIMIT', 'OAUTH_REDIRECT_URI', 'OAUTH_CALLBACK_IDENTITY']);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "melchizedek-agents",
-  "version": "1.10.2",
+  "version": "1.11.0",
   "description": "A multi-model, multi-agent orchestration framework — YAML-defined syndicates on the engine's own agent loop, Supabase or Postgres session persistence, pgvector long-term memory. Companion repo to the lyceumagents.com curriculum.",
   "type": "module",
   "license": "MIT",
@@ -104,7 +104,7 @@
     "syndicate:librarian": "node --disable-warning=DEP0040 --experimental-strip-types scripts/syndicate_chat.ts --syndicate librarian",
     "syndicate:scriptorium": "node --disable-warning=DEP0040 --experimental-strip-types scripts/syndicate_chat.ts --syndicate scriptorium",
     "syndicate:cartographers": "node --disable-warning=DEP0040 --experimental-strip-types scripts/syndicate_chat.ts --syndicate cartographers",
-    "syndicate:augustin": "node --disable-warning=DEP0040 --experimental-strip-types scripts/syndicate_chat.ts --syndicate augustin",
+    "syndicate:current-events": "node --disable-warning=DEP0040 --experimental-strip-types scripts/syndicate_chat.ts --syndicate current_events",
     "syndicate:scribe": "node --disable-warning=DEP0040 --experimental-strip-types scripts/syndicate_chat.ts --syndicate scribe",
     "syndicate:assistant": "node --disable-warning=DEP0040 --experimental-strip-types scripts/syndicate_chat.ts --syndicate assistant",
     "syndicate:harness": "node --disable-warning=DEP0040 --experimental-strip-types scripts/syndicate_chat.ts --syndicate harness",

package/skills/briefs/melchizedek-author.md

@@ -41,7 +41,7 @@ Agent block keys (orchestrator and each subagent):
 - `reasoning:` how hard the agent reasons, on any provider: `none`, `low`, `medium`, `high`, or `{ budget_tokens: 4096 }`. The compiler sends each provider the field it reads, so the setting survives a change to the `model:` line; unset keeps the provider's default. The templates in `config/agents/templates/` give a gathering or routing agent `none` and a synthesizing agent `low` or `medium`. What each level becomes per provider and per Claude model generation belongs to the melchizedek-models skill.
 - `sampling:` per agent: `temperature`, `top_p`, `max_output_tokens`, `stop`; each adapter sends the fields its provider takes. Thinking tokens count against `max_output_tokens`, so a reasoning agent with long output needs a high ceiling (the Scribe uses 24576).
 - `output:` what the agent answers in: `schema`, a JSON schema (types in upper case: `OBJECT`, `STRING`, `INTEGER`, `BOOLEAN`, `ARRAY`) the agent's reply must satisfy, and `mime`, `"application/json"` for JSON mode or `"text/plain"` (the default).
-- `model_overrides:` a prompt nuance for one provider, keyed `gemini`, `anthropic`, `openai`, `xai`, `moonshot` or `ollama`; each entry holds `instruction` (replaces the agent's instruction on that provider) or `instruction_append` (added after it). The entry for the provider of the agent's `model:` applies.
+- `model_overrides:` a prompt nuance for one provider, keyed `gemini`, `anthropic`, `openai`, `xai`, `moonshot`, `deepseek` or `ollama`; each entry holds `instruction` (replaces the agent's instruction on that provider) or `instruction_append` (added after it). The entry for the provider of the agent's `model:` applies.
 - `generateContentConfig:` and `outputSchema:` are the deprecated v1 spelling of `sampling:`, `output:` and `reasoning:`: they still load and behave the same, with one deprecation line per file, and an agent that sets a v2 key beside its v1 spelling fails to load. `npx melchizedek-codemod <file|dir>` rewrites a v1 file to v2, comments kept (`--check` only reports). New agents use the v2 keys.
 - Subagents receive one string argument, `query`, and see nothing else of the conversation. The orchestrator's instruction must say what to pass them, in full, every time.
 

package/skills/briefs/melchizedek-models.md

@@ -6,19 +6,19 @@ STRUCTURE (exact):
 Frontmatter, verbatim:
 ---
 name: melchizedek-models
-description: "Choose and wire a model for a Melchizedek agent: how a model id routes to Gemini, Claude, GPT, Grok, Kimi, or local Ollama, which environment variable each needs, the gateway fallback, the doctor, and per-agent settings such as how hard an agent reasons. Use when the user changes a model line, adds a provider key, wants an agent to think more or less, sees a missing-key error, Model not found or a gateway error, or asks which keys a syndicate needs."
+description: "Choose and wire a model for a Melchizedek agent: how a model id routes to Gemini, Claude, GPT, Grok, Kimi, DeepSeek, or local Ollama, which environment variable each needs, the gateway fallback, the doctor, and per-agent settings such as how hard an agent reasons. Use when the user changes a model line, adds a provider key, wants an agent to think more or less, sees a missing-key error, Model not found or a gateway error, or asks which keys a syndicate needs."
 ---
 Then `##` sections in this order: "How a model id routes", "Which key unlocks what", "Run with no key at all", "One key for every cloud provider", "Settings per agent", "Mixing providers in one syndicate", "Reading the errors".
 
 FACTS:
 How a model id routes:
-- The `model:` string's prefix names the provider: `claude-*` to Anthropic, `gpt-*` and `o<digit>*` to OpenAI, `grok-*` to xAI, `kimi-*` to Moonshot AI (Kimi), `ollama/<model>` to a local Ollama, and everything else to Gemini (the default, served by the engine's own Gemini adapter).
+- The `model:` string's prefix names the provider: `claude-*` to Anthropic, `gpt-*` and `o<digit>*` to OpenAI, `grok-*` to xAI, `kimi-*` to Moonshot AI (Kimi), `deepseek-*` to DeepSeek, `ollama/<model>` to a local Ollama, and everything else to Gemini (the default, served by the engine's own Gemini adapter).
 - There is no allowlist in the engine: any id a provider currently serves works as written. A new model is a one-line YAML change.
 - Ids verified in this deployment: `gemini-3.8-flash` (production), `gemini-3.5-flash-lite` (subagents, cost), `claude-sonnet-4-6`, `claude-opus-4-6`, `claude-haiku-4-5-20251001`, `gpt-5-mini`, `gpt-5`, `grok-4.7`, `kimi-k3`, `ollama/qwen3:8b`.
 - `gemini-2.5-flash` returns a 400 about tool call context circulation with the server-side tool flag the framework sets; use `gemini-3.8-flash` or newer.
 - Subagents inherit the orchestrator's `model` when they set none.
 Which key unlocks what:
-- `GOOGLE_GENAI_API_KEY` for Gemini (also the embedding model behind long-term memory); `ANTHROPIC_API_KEY`; `OPENAI_API_KEY`; `XAI_API_KEY`; `MOONSHOT_API_KEY` for Kimi; no key for `ollama/*`.
+- `GOOGLE_GENAI_API_KEY` for Gemini (also the embedding model behind long-term memory); `ANTHROPIC_API_KEY`; `OPENAI_API_KEY`; `XAI_API_KEY`; `MOONSHOT_API_KEY` for Kimi; `DEEPSEEK_API_KEY` for DeepSeek (`deepseek-flash`, the default, and `deepseek-v4-pro`, the deeper text-only tier; billed from a balance topped up first); no key for `ollama/*`.
 - A provider is available only when its key is present; a missing key shows the provider as disabled in the doctor and the startup log, and an agent on that provider fails its turn with an error naming the key (`ANTHROPIC_API_KEY is not set in environment.`).
 - `npx melchizedek-doctor` (clone: `npm run doctor`) reads every syndicate, resolves each agent's model under the current `.env`, and prints per agent: model, provider, which server-side search tools the path keeps or drops, and whether it is funded; per syndicate a verdict; and the variables that would unlock the most. `--json`, `--check` (exit 1 when any syndicate is blocked). Read-only, no key value printed.
 - The `# tier:` first line of every starter-pack file states its cost class (`keyless`, one provider name, or `multi-provider`); the doctor checks the claim against the models.
@@ -34,21 +34,22 @@ One key for every cloud provider (the gateway fallback):
 Settings per agent:
 - `reasoning:` on the agent block, beside `model:`, sets how hard the agent reasons: `none`, `low`, `medium`, `high`, `xhigh`, `max`, or `{ budget_tokens: 4096 }`. It reads the same on every provider; unset keeps the provider's default. The compiler sends each provider the field it reads: Gemini 3 and later get a thinking level (`none` is `MINIMAL`, then `LOW`, `MEDIUM`, `HIGH`); Gemini 2.x, and Claude 4.6 or older, get a thinking budget of 0, 2048, 8192 or 16384 tokens; every later Claude model gets adaptive thinking at an effort of `low`, `medium` or `high`, and `none` is that model's own off switch, sent at `low` effort; every other provider, and the gateway, gets an effort word, and where the provider lacks that word, its nearest setting above.
 - `xhigh` and `max` ask for more thought than `high`. They reach the models that take them: both on every later Claude model, `max` on Kimi K3 (where `xhigh` rounds up to it), and `xhigh` on GPT-5.2 and later and on grok-4.7. Every other model gets its highest setting instead, and the request's span carries `llm.reasoning.weakened`; the gateway gets `high` for any id. `npm run doctor -- --matrix` lists each path. Both cost more: `max` is Kimi K3's costliest effort.
+- DeepSeek thinks by default: `reasoning: none` turns thinking off, and the other levels go as DeepSeek's low, high or max (`xhigh` rounds up to max). While it thinks, DeepSeek ignores `temperature`. Structured output on DeepSeek is JSON mode (the engine asks for the schema in the system message and validates the answer), and `web_search` is dropped with a warning.
 - A `budget_tokens` value goes as written to Gemini and to Claude 4.6 or older, and as the smallest level that covers it everywhere else, later Claude models included. The effort word is always sent too, because the gateway can serve any cloud id; a direct provider ignores the field it does not read. Changing the `model:` line keeps the setting. Unset, a later Claude model keeps its own default: it thinks, except Opus 4.7 and 4.8, which think only when asked.
 - Four provider limits: on Claude 4.6 or older, the adapter raises a budget under 1024 to 1024, the least Anthropic takes; on every Claude model, the Anthropic SDK refuses a non-streaming request whose output ceiling passes about 21000 tokens, and the adapter sets that ceiling to at least the thinking budget plus 2048, so a `budget_tokens` above about 19000 fails a non-streaming turn, while the levels stay under it; on Claude Opus 5 and 5.5, Fable and Mythos, `none` is adaptive thinking at `low` effort, so a little thinking remains, because Opus 5.5, Fable and Mythos cannot turn thinking off and Opus 5's off switch can write a tool call as text that never runs; Gemini 2.5 Pro rejects a budget of 0, so `none` fails on it.
 - `sampling:` on any agent: `temperature` (where the provider still exposes it; never sent to Claude), `top_p`, `stop`, `max_output_tokens`; each adapter sends the fields its provider takes. Thinking tokens count against `max_output_tokens`, so a reasoning agent with long output needs room; the Claude adapter raises its own ceiling to the thinking budget plus 2048 tokens, on every Claude model. A level counts as its budget (2048, 8192 or 16384), so `high`, or a later Claude model that thinks by default, gets at least 18432.
 - `tool_choice:` says which tools the model may call: `auto` (the default), `none`, `required` (some tool), or `{ name: lookup }` (that one tool). It reads the same on every provider; where a provider rejects forcing a tool, the adapter sends a weaker choice and the span carries `llm.tool_choice.weakened`.
-- `model_overrides:` gives one provider its own prompt nuance, keyed `gemini`, `anthropic`, `openai`, `xai`, `moonshot` or `ollama`; each entry holds `instruction` (replaces the agent's instruction on that provider) or `instruction_append` (added after it). The entry for the provider of the agent's `model:` applies, and a `fallback_model` gets the same instruction.
+- `model_overrides:` gives one provider its own prompt nuance, keyed `gemini`, `anthropic`, `openai`, `xai`, `moonshot`, `deepseek` or `ollama`; each entry holds `instruction` (replaces the agent's instruction on that provider) or `instruction_append` (added after it). The entry for the provider of the agent's `model:` applies, and a `fallback_model` gets the same instruction.
 - `generateContentConfig:` is the deprecated, Gemini-shaped spelling of `sampling:`, `tool_choice:`, `output.mime` and `reasoning:` (as `thinkingConfig` and `reasoningEffort`). It still loads and behaves the same, with one deprecation line per file, but a `thinkingLevel` written for Gemini does nothing on Claude. An agent that sets a v2 key beside its v1 spelling fails to load. `npx melchizedek-codemod <file|dir>` rewrites a file to the v2 keys. Only `toolConfig.functionCallingConfig.mode: VALIDATED` and Gemini's dynamic budget (`thinkingBudget: -1`) still need `generateContentConfig:`; the codemod drops `includeThoughts`. `topK`, `seed`, the penalties, `candidateCount`, `safetySettings` and `includeThoughts` reach no provider; the Gemini adapter asks for the thought trace itself whenever `reasoning:` is not `none`.
 - The framework's own pattern: data-gathering subagents on a lite model with `reasoning: none` and a tight output cap; synthesis on the stronger model with `reasoning: low` or higher and room to reason. The templates in `config/agents/templates/` follow it.
 Mixing providers in one syndicate:
 - Any agent in a graph can run on a different provider; `model_zoo.yaml` declares one lightweight agent per provider, and in a clone `npm run demo:models` sends one prompt through each.
 - In code, `logProviderStatuses()` from `melchizedek-agents` reports which providers have a key (and, given a log function, logs a line per provider; it registers nothing); `resolveAdapter(modelId)` from `melchizedek-agents/model` returns the provider's adapter for any of these ids; in a clone `npm run demo:direct -- --model ollama/qwen3:8b hello` makes one model call with no YAML.
 Reading the errors:
-- `<KEY> is not set in environment.` for a `claude-*`, `gpt-*`, `grok-*` or `kimi-*` id: the provider's key is unset. Set it, or set the gateway pair.
+- `<KEY> is not set in environment.` for a `claude-*`, `gpt-*`, `grok-*`, `kimi-*` or `deepseek-*` id: the provider's key is unset. Set it, or set the gateway pair.
 - `GATEWAY_HTTP_ERROR ... 404/400`: the gateway rejected the mapped id; fix the name with `MODEL_GATEWAY_MODEL_MAP`.
 - `GATEWAY_KEY_MISSING`: `MODEL_GATEWAY` is set without `MODEL_GATEWAY_API_KEY`.
 - `OLLAMA_UNREACHABLE`: Ollama is not running (`ollama serve`) or the model is not pulled (`ollama list`).
 
-IDENTIFIERS (verbatim): model:, claude-*, gpt-*, grok-*, kimi-*, ollama/, gemini-3.8-flash, gemini-3.5-flash-lite, gemini-2.5-flash, kimi-k3, ollama/qwen3:8b, GOOGLE_GENAI_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, XAI_API_KEY, MOONSHOT_API_KEY, npx melchizedek-doctor, --json, --check, # tier:, ollama pull qwen3:8b, http://localhost:11434/v1, MODEL_GATEWAY, MODEL_GATEWAY_API_KEY, MODEL_GATEWAY_MODEL_MAP, MODEL_GATEWAY_BASE_URL, X-API-Key, reasoning:, budget_tokens, sampling:, max_output_tokens, model_overrides:, instruction_append, generateContentConfig:, thinkingConfig, reasoningEffort, thinkingLevel, includeThoughts, toolConfig, npx melchizedek-codemod, config/agents/templates/, model_zoo.yaml, npm run demo:models, logProviderStatuses, GATEWAY_HTTP_ERROR, GATEWAY_KEY_MISSING, OLLAMA_UNREACHABLE
+IDENTIFIERS (verbatim): model:, claude-*, gpt-*, grok-*, kimi-*, deepseek-*, ollama/, gemini-3.8-flash, gemini-3.5-flash-lite, gemini-2.5-flash, kimi-k3, ollama/qwen3:8b, GOOGLE_GENAI_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, XAI_API_KEY, MOONSHOT_API_KEY, DEEPSEEK_API_KEY, deepseek-flash, deepseek-v4-pro, npx melchizedek-doctor, --json, --check, # tier:, ollama pull qwen3:8b, http://localhost:11434/v1, MODEL_GATEWAY, MODEL_GATEWAY_API_KEY, MODEL_GATEWAY_MODEL_MAP, MODEL_GATEWAY_BASE_URL, X-API-Key, reasoning:, budget_tokens, sampling:, max_output_tokens, model_overrides:, instruction_append, generateContentConfig:, thinkingConfig, reasoningEffort, thinkingLevel, includeThoughts, toolConfig, npx melchizedek-codemod, config/agents/templates/, model_zoo.yaml, npm run demo:models, logProviderStatuses, GATEWAY_HTTP_ERROR, GATEWAY_KEY_MISSING, OLLAMA_UNREACHABLE
 LIMITS: the routing prefixes and what `reasoning:` becomes per provider may each be a short table. Body under 160 lines.