melchizedek-agents 0.18.0 → 0.20.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "melchizedek-agents",
-  "version": "0.18.0",
-  "description": "A multi-model, multi-agent orchestration framework on Google ADK — YAML-defined syndicates, Supabase session persistence, pgvector long-term memory. Companion repo to the lyceumagents.com curriculum.",
+  "version": "0.20.0",
+  "description": "A multi-model, multi-agent orchestration framework — YAML-defined syndicates on the engine's own agent loop (Google ADK optional until 1.0), Supabase session persistence, pgvector long-term memory. Companion repo to the lyceumagents.com curriculum.",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -12,7 +12,7 @@
   "bugs": {
     "url": "https://github.com/jhwadman/melch-ai/issues"
   },
-  "//": "adk + genai are pinned exact in dev: newer genai minors change response part shapes and silently break the chat printer. Bump deliberately, verify a live run, then update the pin. adk itself is a PEER dependency — the consumer's app owns the ADK instance so the model registry is a singleton. The adk peer range is capped to the tested minor (~2.2.0): a new adk minor can pull a second genai copy, so the range widens only after a release is tested against it.",
+  "//": "adk + genai are pinned exact in dev: newer genai minors change response part shapes and silently break the chat printer. Bump deliberately, verify a live run, then update the pin. adk itself is an OPTIONAL PEER dependency since 0.20.0 (ADR 0102): the native runtime, the default, needs none of it; a consumer on MELCHIZEDEK_RUNTIME=adk installs it, and their app owns the ADK instance so the model registry is a singleton. lib/adkPeer.ts is the one module that loads it. The adk peer range is capped to the tested minor (~2.2.0): a new adk minor can pull a second genai copy, so the range widens only after a release is tested against it.",
   "engines": {
     "node": ">=22.6.0"
   },
@@ -35,6 +35,7 @@
     "./storage/postgres": "./dist/lib/storage/postgres/index.js",
     "./grounding": "./dist/lib/grounding.js",
     "./config": "./dist/lib/config.js",
+    "./model": "./dist/lib/model.js",
     "./models/*": "./dist/lib/models/*.js",
     "./tools": "./dist/lib/toolRegistry.js",
     "./tools/*": "./dist/lib/tools/*.js",
@@ -102,6 +103,7 @@
     "assistant:worker": "node --disable-warning=DEP0040 --experimental-strip-types scripts/assistant_worker.ts",
     "demo:models": "node --disable-warning=DEP0040 --experimental-strip-types scripts/demo_model_optionality.ts",
     "demo:direct": "node --disable-warning=DEP0040 --experimental-strip-types scripts/direct_call.ts",
+    "parity": "node --disable-warning=DEP0040 --experimental-strip-types scripts/parity_check.ts",
     "mcp:demo": "node --disable-warning=DEP0040 --experimental-strip-types scripts/demo_mcp_server.ts",
     "mcp:wiki": "node --disable-warning=DEP0040 --experimental-strip-types scripts/wiki/mcp_server.ts",
     "mcp:science": "node --disable-warning=DEP0040 --experimental-strip-types scripts/science_mcp_server.ts",
@@ -111,6 +113,7 @@
     "schema:gen": "node --disable-warning=DEP0040 --experimental-strip-types scripts/gen_syndicate_schema.ts",
     "start:a2a": "node --disable-warning=DEP0040 --experimental-strip-types scripts/a2a_server.ts",
     "test": "node --disable-warning=DEP0040 --experimental-strip-types --test tests/**/*.test.ts",
+    "fixtures:sessions:check": "node --disable-warning=DEP0040 --experimental-strip-types tests/fixtures/sessions/generate.ts --check",
     "init": "node --disable-warning=DEP0040 --experimental-strip-types scripts/init.ts",
     "db": "node --disable-warning=DEP0040 --experimental-strip-types scripts/db.ts",
     "registry": "node --disable-warning=DEP0040 --experimental-strip-types scripts/registry.ts",
@@ -165,6 +168,9 @@
     "@anthropic-ai/bedrock-sdk": {
       "optional": true
     },
+    "@google/adk": {
+      "optional": true
+    },
     "@anthropic-ai/vertex-sdk": {
       "optional": true
     },

package/skills/briefs/melchizedek-author.md

@@ -38,7 +38,8 @@ Agent block keys (orchestrator and each subagent):
 - `code_execution: gemini` lets a Gemini agent write and run Python in Google's sandbox (nothing runs on your machine). `context: { compact_after_tokens: 60000 }` on a delegate orchestrator summarizes a long conversation instead of overflowing it. `mode: task` on a workflow node makes its output its `finish_task` arguments.
 - `openapi:` a list of OpenAPI 3 spec files (relative to the syndicate file) whose operations become the agent's tools; only GET operations unless `operations` names others; `auth` reads `bearer_env` or `api_key: {env, in, name}` from the environment. Read `weather.yaml` for the worked example.
 - `mcp_server_url:` on a subagent: tools discovered from that MCP server at start (the melchizedek-serve skill).
-- `generateContentConfig:` per agent: `temperature`, `maxOutputTokens`, `responseMimeType: "application/json"` for structured output, `thinkingConfig: { thinkingLevel: MEDIUM, includeThoughts: false }` on Gemini models that think. Thinking tokens count against `maxOutputTokens`, so a thinking agent with long output needs a high ceiling (the Scribe uses 24576).
+- `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.
+- `generateContentConfig:` per agent: `temperature`, `maxOutputTokens`, `responseMimeType: "application/json"` for structured output. Thinking tokens count against `maxOutputTokens`, so a reasoning agent with long output needs a high ceiling (the Scribe uses 24576). `thinkingConfig` and `reasoningEffort` inside this block are the older, provider-specific spelling of `reasoning:`: some starter-pack examples still use them and they still load, but an agent that sets either beside `reasoning:` fails to load. New agents use `reasoning:`.
 - `outputSchema:` a JSON schema (types in upper case: `OBJECT`, `STRING`, `INTEGER`, `BOOLEAN`, `ARRAY`) the agent's reply must satisfy.
 - 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.
 
@@ -60,5 +61,5 @@ Validate and run:
 Editing a syndicate that is already serving:
 - `melchizedek-serve` compiles a syndicate when it is first requested and caches it for the life of the process; an edited file changes nothing until the server restarts. A deployment that boots agents from the Supabase agent registry (`registry:<id>`) serves the registry row, not the file, until the row is republished.
 
-IDENTIFIERS (verbatim): config/agents/, syndicateSchema.yaml, assets/minimal.yaml, syndicate_name, memory_system, internal-only, session-only, long-term, variables:, {{current_date}}, memory_extraction_rules:, dispatch:, default_route, route_overrides, workflow:, edges, nodes, ask_user, join, map, START, pipeline.yaml, orchestrator:, subagents:, description, model, instruction, tools:, mcp_server_url:, generateContentConfig:, outputSchema:, responseMimeType, thinkingConfig, maxOutputTokens, # tier:, npm test, npx melchizedek-doctor, npx melchizedek-chat --syndicate, loadSyndicate, gemini-3.8-flash, gemini-3.5-flash-lite, critic.yaml, scribe.yaml, tutor.yaml, patient_advocate.yaml
+IDENTIFIERS (verbatim): config/agents/, syndicateSchema.yaml, assets/minimal.yaml, syndicate_name, memory_system, internal-only, session-only, long-term, variables:, {{current_date}}, memory_extraction_rules:, dispatch:, default_route, route_overrides, workflow:, edges, nodes, ask_user, join, map, START, pipeline.yaml, orchestrator:, subagents:, description, model, instruction, tools:, mcp_server_url:, reasoning:, budget_tokens, config/agents/templates/, generateContentConfig:, outputSchema:, responseMimeType, thinkingConfig, reasoningEffort, maxOutputTokens, # tier:, npm test, npx melchizedek-doctor, npx melchizedek-chat --syndicate, loadSyndicate, gemini-3.8-flash, gemini-3.5-flash-lite, critic.yaml, scribe.yaml, tutor.yaml, patient_advocate.yaml
 LIMITS: the Node one-liner goes in a fenced bash block exactly as given. Body under 170 lines.

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, or local Ollama, which environment variable each needs, the gateway fallback, the doctor, and per-agent generation settings. Use when the user changes a model line, adds a provider key, sees 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, 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 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, `ollama/<model>` to a local Ollama, and everything else to Gemini (the ADK-native default).
+- 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 ADK-native default).
 - 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`, `ollama/qwen3:8b`.
+- 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`; 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; no key for `ollama/*`.
 - A provider registers only when its key is present; a missing key logs the provider as disabled, and an agent on that provider fails with `Model not found`.
 - `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.
@@ -32,16 +32,20 @@ One key for every cloud provider (the gateway fallback):
 - Dials: `MODEL_GATEWAY_MODEL_MAP=<your id>=<the gateway's id>` renames an id the gateway rejects; `MODEL_GATEWAY_BASE_URL` points at a self-hosted proxy.
 - Telemetry attributes the call to the upstream provider and records the transport separately.
 Settings per agent:
-- `generateContentConfig:` on any agent: `temperature` (where the provider still exposes it), `maxOutputTokens`, `thinkingConfig: { thinkingLevel: MEDIUM, includeThoughts: false }` on Gemini models that think. Thinking tokens count against `maxOutputTokens`.
-- The framework's own pattern: data-gathering subagents on a lite model with a tight output cap; synthesis on the stronger model with a thinking level and room to reason.
+- `reasoning:` on the agent block, beside `model:`, sets how hard the agent reasons: `none`, `low`, `medium`, `high`, 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.
+- 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.
+- `generateContentConfig:` on any agent: `temperature` (where the provider still exposes it; never sent to Claude), `maxOutputTokens`. Thinking tokens count against `maxOutputTokens`, 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.
+- `thinkingConfig` and `reasoningEffort` inside `generateContentConfig:` are the older, provider-specific spelling of `reasoning:`. They still load, but each reaches only the providers that read it (a `thinkingLevel` written for Gemini does nothing on Claude). An agent that sets either beside `reasoning:` fails to load. `thinkingConfig` stays only for `includeThoughts: true`, which streams Gemini's thought trace and has no `reasoning:` form; such an agent sets its level inside `thinkingConfig` too (`thinkingLevel`) and leaves `reasoning:` out.
+- 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, `registerAvailableProviders()` from `melchizedek-agents` registers every provider whose key is present so a plain ADK `LlmAgent` can take any of these ids; in a clone `npm run demo:direct -- --model ollama/qwen3:8b hello` runs one agent with no YAML.
 Reading the errors:
-- `Model not found` for a `claude-*`, `gpt-*` or `grok-*` id: the provider's key is unset. Set it, or set the gateway pair.
+- `Model not found` for a `claude-*`, `gpt-*`, `grok-*` or `kimi-*` 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-*, ollama/, gemini-3.8-flash, gemini-3.5-flash-lite, gemini-2.5-flash, ollama/qwen3:8b, GOOGLE_GENAI_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, XAI_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, generateContentConfig:, maxOutputTokens, thinkingConfig, model_zoo.yaml, npm run demo:models, registerAvailableProviders, GATEWAY_HTTP_ERROR, GATEWAY_KEY_MISSING, OLLAMA_UNREACHABLE, Model not found
-LIMITS: the routing prefixes may be a short table. Body under 160 lines.
+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, generateContentConfig:, maxOutputTokens, thinkingConfig, reasoningEffort, thinkingLevel, includeThoughts, config/agents/templates/, model_zoo.yaml, npm run demo:models, registerAvailableProviders, GATEWAY_HTTP_ERROR, GATEWAY_KEY_MISSING, OLLAMA_UNREACHABLE, Model not found
+LIMITS: the routing prefixes and what `reasoning:` becomes per provider may each be a short table. Body under 160 lines.

package/skills/briefs/melchizedek.md

@@ -43,7 +43,7 @@ The starter pack (file → name → what it does → tier / extra requirement):
 Check the keys:
 - `npx melchizedek-doctor` (clone: `npm run doctor`) reads every syndicate the loader can see, resolves each agent's model to a provider under the current `.env`, and prints one table: agent, model, provider, which server-side tools the path keeps or drops, and whether the path is funded, with one verdict per syndicate and the variables that would unlock the most. Read-only; nothing sent, nothing written, no key value printed.
 - `--json` for machine-readable output; `--check` exits 1 when any syndicate is blocked.
-- Which key: GOOGLE_GENAI_API_KEY for gemini-* ids, ANTHROPIC_API_KEY for claude-*, OPENAI_API_KEY for gpt-*, XAI_API_KEY for grok-*, none for ollama/* (Ollama must be running, model pulled). Details and the gateway fallback: the melchizedek-models skill.
+- Which key: GOOGLE_GENAI_API_KEY for gemini-* ids, ANTHROPIC_API_KEY for claude-*, OPENAI_API_KEY for gpt-*, XAI_API_KEY for grok-*, MOONSHOT_API_KEY for kimi-*, none for ollama/* (Ollama must be running, model pulled). Details and the gateway fallback: the melchizedek-models skill.
 
 Run one:
 - Interactive: `npx melchizedek-chat --syndicate <name>` (clone: `npm run chat:syndicate -- --syndicate <name>`; every example also has an alias such as `npm run syndicate:tutor`). A banner shows the syndicate, orchestrator, subagents, and whether sessions and memory are in Supabase or in memory. Type `exit` to end the session; that is also when a long-term syndicate writes its memory.
@@ -60,7 +60,7 @@ Delegate a task from this agent:
 
 When something fails:
 - `Gemini API Key is not configured`: `.env` missing or GOOGLE_GENAI_API_KEY unset.
-- `Model not found` for a claude-*, gpt-* or grok-* id: that provider's key is not set, so the provider was not registered; the doctor names the variable.
+- `Model not found` for a claude-*, gpt-*, grok-* or kimi-* id: that provider's key is not set, so the provider was not registered; the doctor names the variable.
 - `OLLAMA_UNREACHABLE` for ollama/* ids: Ollama is not running, or the model is not pulled (`ollama list`).
 - `[400] Tool call context circulation is not enabled`: the agent's `model:` is too old for agent transfer; use `gemini-3.8-flash` or newer.
 - `Refusing to connect to private/loopback MCP host`: the SSRF guard; for a local MCP server set `ALLOW_PRIVATE_MCP=true` in `.env`.
@@ -68,5 +68,5 @@ When something fails:
 
 The other skills: melchizedek-author (design or edit a syndicate file), melchizedek-serve (A2A server and MCP in both directions), melchizedek-memory (Supabase sessions and long-term memory), melchizedek-models (model ids, providers, keys, the gateway), melchizedek-scribe (write documents from a brief with the Scribe).
 
-IDENTIFIERS (verbatim): config/agents/, config/agents/examples/, node_modules/melchizedek-agents/config/agents/examples/, MELCHIZEDEK_AGENTS_DIR, npx melchizedek-doctor, --json, --check, npx melchizedek-chat --syndicate, CHAT_STREAMING=false, --bind, --bindings, {{current_date}}, GOOGLE_GENAI_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, XAI_API_KEY, SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, ALLOW_PRIVATE_MCP=true, X_BEARER_TOKEN, scribe.yaml, tutor.yaml, augustin.yaml, syndicate.yaml
+IDENTIFIERS (verbatim): config/agents/, config/agents/examples/, node_modules/melchizedek-agents/config/agents/examples/, MELCHIZEDEK_AGENTS_DIR, npx melchizedek-doctor, --json, --check, npx melchizedek-chat --syndicate, CHAT_STREAMING=false, --bind, --bindings, {{current_date}}, GOOGLE_GENAI_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, XAI_API_KEY, MOONSHOT_API_KEY, SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, ALLOW_PRIVATE_MCP=true, X_BEARER_TOKEN, scribe.yaml, tutor.yaml, augustin.yaml, syndicate.yaml
 LIMITS: the starter-pack section is a bulleted list, one line per file, file name in backticks first. Body under 170 lines.

package/skills/melchizedek/SKILL.md

@@ -78,6 +78,7 @@ Provide keys in `.env` or in the environment:
 - `ANTHROPIC_API_KEY` for claude-* ids.
 - `OPENAI_API_KEY` for gpt-* ids.
 - `XAI_API_KEY` for grok-* ids.
+- `MOONSHOT_API_KEY` for kimi-* ids.
 - No key for ollama/* ids; start Ollama and pull the model.
 
 The `melchizedek-models` skill covers provider details and the gateway fallback.
@@ -147,7 +148,7 @@ CHAT_STREAMING=false npx melchizedek-chat --syndicate scribe -- "$(cat brief.md)
 ## When something fails
 
 - `Gemini API Key is not configured`: `.env` is missing or `GOOGLE_GENAI_API_KEY` is unset.
-- `Model not found` for a claude-*, gpt-*, or grok-* id: you did not set that provider's key, so the framework did not register the provider; run `npx melchizedek-doctor` to see the missing variable.
+- `Model not found` for a claude-*, gpt-*, grok-*, or kimi-* id: you did not set that provider's key, so the framework did not register the provider; run `npx melchizedek-doctor` to see the missing variable.
 - `OLLAMA_UNREACHABLE` for ollama/* ids: Ollama is not running, or you have not pulled the target model (`ollama list`).
 - `[400] Tool call context circulation is not enabled`: the agent uses a `model:` too old for agent transfer; update the agent to `gemini-3.8-flash` or newer.
 - `Refusing to connect to private/loopback MCP host`: the SSRF guard blocked the connection; for a local MCP server, set `ALLOW_PRIVATE_MCP=true` in `.env`.

package/skills/melchizedek-author/SKILL.md

@@ -45,7 +45,8 @@ Agent block keys for the orchestrator and each subagent:
 - `code_execution: gemini` lets a Gemini agent write and run Python in Google's sandbox (nothing runs on your machine). `context: { compact_after_tokens: 60000 }` on a delegate orchestrator summarizes a long conversation instead of overflowing it. `mode: task` on a workflow node makes its output its `finish_task` arguments.
 - `openapi:` a list of OpenAPI 3 spec files (relative to the syndicate file) whose operations become the agent's tools; only GET operations unless `operations` names others; `auth` reads `bearer_env` or `api_key: {env, in, name}` from the environment. Read `weather.yaml` for the worked example.
 - `mcp_server_url:`: URL on a subagent to discover MCP tools at start. The melchizedek-serve skill covers MCP servers.
-- `generateContentConfig:`: per-agent options: `temperature`, `maxOutputTokens`, `responseMimeType: "application/json"`, and `thinkingConfig: { thinkingLevel: MEDIUM, includeThoughts: false }` on Gemini models that think. Thinking tokens count against `maxOutputTokens`. The Scribe uses 24576 for `maxOutputTokens`.
+- `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. Leave it unset to keep the provider's default. The templates in `config/agents/templates/` give a gathering or routing agent `none` and a synthesizing agent `low` or `medium`. The melchizedek-models skill covers what each level becomes per provider and per Claude model generation.
+- `generateContentConfig:`: per-agent options: `temperature`, `maxOutputTokens`, `responseMimeType: "application/json"`. Thinking tokens count against `maxOutputTokens`, so a reasoning agent with long output needs a high ceiling. The Scribe uses 24576 for `maxOutputTokens`. `thinkingConfig` and `reasoningEffort` inside this block are the older, provider-specific spelling of `reasoning:`. Some starter-pack examples still use them and they still load, but an agent that sets either beside `reasoning:` fails to load. Write new agents with `reasoning:`.
 - `outputSchema:`: a JSON schema using uppercase types (`OBJECT`, `STRING`, `INTEGER`, `BOOLEAN`, `ARRAY`) that the agent reply must satisfy.
 
 Subagents receive one string argument, `query`, and see nothing else of the conversation. The orchestrator instruction must state what to pass them in full every time.

package/skills/melchizedek-author/assets/minimal.yaml

@@ -34,6 +34,7 @@ orchestrator:
         3. <Compose the reply from what came back.>
       </execution_framework>
     </prompt_instructions>
+  reasoning: low                    # none | low | medium | high, on any provider (melchizedek-models)
   generateContentConfig:
     maxOutputTokens: 4096
 
@@ -47,6 +48,7 @@ subagents:
     instruction: |
       You are Worker. <The one job, its inputs, and the exact shape of the
       report you return.>
+    reasoning: none                 # a gathering agent; raise it when the job is judgment
     generateContentConfig:
       maxOutputTokens: 2048
     # For structured output put the schema HERE, on a leaf with no tools —

package/skills/melchizedek-models/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: melchizedek-models
-description: "Choose and wire a model for a Melchizedek agent: how a model id routes to Gemini, Claude, GPT, Grok, or local Ollama, which environment variable each needs, the gateway fallback, the doctor, and per-agent generation settings. Use when the user changes a model line, adds a provider key, sees 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, 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 Model not found or a gateway error, or asks which keys a syndicate needs."
 ---
 
 ## How a model id routes
@@ -12,6 +12,7 @@ The runtime reads the prefix of each `model:` string to select the provider:
 | `claude-*` | Anthropic |
 | `gpt-*`, `o<digit>*` | OpenAI |
 | `grok-*` | xAI |
+| `kimi-*` | Moonshot AI (Kimi) |
 | `ollama/<model>` | Local Ollama |
 | Everything else | Gemini (ADK-native default) |
 
@@ -26,6 +27,7 @@ The deployment verifies these ids:
 - `gpt-5-mini`
 - `gpt-5`
 - `grok-4.7`
+- `kimi-k3`
 - `ollama/qwen3:8b`
 
 The framework sets a server-side tool flag that triggers a 400 error about tool call context circulation on `gemini-2.5-flash`. Use `gemini-3.8-flash` or newer instead.
@@ -39,6 +41,7 @@ Each provider requires a distinct environment variable in your `.env` file or pr
 - Anthropic: `ANTHROPIC_API_KEY`
 - OpenAI: `OPENAI_API_KEY`
 - xAI: `XAI_API_KEY`
+- Moonshot AI (Kimi): `MOONSHOT_API_KEY`
 - Ollama: no key for `ollama/*`
 
 The runtime registers a provider only when its matching key is present. When you omit the key, the runtime logs the provider as disabled, and any agent on that provider halts with `Model not found`.
@@ -104,12 +107,26 @@ The runtime telemetry attributes every call to the upstream provider and records
 
 ## Settings per agent
 
+Set how hard an agent reasons with `reasoning:` on the agent block, beside `model:`. It takes `none`, `low`, `medium`, `high`, or `{ budget_tokens: 4096 }`, and reads the same on every provider. Leave it unset to keep the provider's default. The compiler sends each provider the field that provider reads:
+
+| Provider | What `reasoning:` becomes |
+| --- | --- |
+| Gemini 3 and later | a thinking level: `none` is `MINIMAL`, then `LOW`, `MEDIUM`, `HIGH` |
+| Gemini 2.x, and Claude 4.6 or older | a thinking budget of 0, 2048, 8192 or 16384 tokens |
+| Every later Claude model | adaptive thinking at an effort of `low`, `medium` or `high`; `none` is the model's own off switch, sent at `low` effort |
+| Every other provider, and the gateway | an effort word; where the provider lacks that word, its nearest setting above |
+
+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. Because the gateway can serve any cloud id, the effort word is always sent as well, and a direct provider ignores the field it does not read. Change the `model:` line and the setting carries over. Unset, a later Claude model keeps its own default: it thinks, except Opus 4.7 and 4.8, which think only when asked.
+
+Four limits apply. 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. 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. 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: 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.
+
 You can configure generation parameters under `generateContentConfig:` on any agent in the syndicate YAML:
-- `temperature`: controls randomness where the provider still exposes the parameter.
-- `maxOutputTokens`: caps total token generation.
-- `thinkingConfig`: sets reasoning parameters on Gemini models that think, such as `{ thinkingLevel: MEDIUM, includeThoughts: false }`. Thinking tokens count against `maxOutputTokens`.
+- `temperature`: controls randomness where the provider still exposes the parameter. The Claude adapter never sends it.
+- `maxOutputTokens`: caps total token generation. Thinking tokens count against it, 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.
+
+`thinkingConfig` and `reasoningEffort` inside `generateContentConfig:` are the older, provider-specific spelling of `reasoning:`. They still load, but each reaches only the providers that read it: a `thinkingLevel` written for Gemini does nothing on Claude. An agent that sets either beside `reasoning:` fails to load. Keep `thinkingConfig` only for `includeThoughts: true`, which streams Gemini's thought trace and has no `reasoning:` form. Such an agent sets its level inside `thinkingConfig` too, with `thinkingLevel`, and leaves `reasoning:` out.
 
-The framework's own pattern places data-gathering subagents on a lite model with a tight output cap, while assigning synthesis tasks to a stronger model with a thinking level and room to reason.
+The framework's own pattern places data-gathering subagents on a lite model with `reasoning: none` and a tight output cap, while synthesis runs on a stronger model with `reasoning: low` or higher and room to reason. The templates in `config/agents/templates/` follow it.
 
 ## Mixing providers in one syndicate
 
@@ -131,7 +148,7 @@ npm run demo:direct -- --model ollama/qwen3:8b hello
 
 When a model fails to run, consult the error message:
 
-- `Model not found`: The provider's key is unset for a `claude-*`, `gpt-*`, or `grok-*` id. Set the required provider key, or supply `MODEL_GATEWAY` and `MODEL_GATEWAY_API_KEY`.
+- `Model not found`: The provider's key is unset for a `claude-*`, `gpt-*`, `grok-*`, or `kimi-*` id. Set the required provider key, or supply `MODEL_GATEWAY` and `MODEL_GATEWAY_API_KEY`.
 - `GATEWAY_HTTP_ERROR ... 404/400`: The gateway rejected the mapped id. Fix the name with `MODEL_GATEWAY_MODEL_MAP`.
 - `GATEWAY_KEY_MISSING`: You set `MODEL_GATEWAY` without `MODEL_GATEWAY_API_KEY`. Set `MODEL_GATEWAY_API_KEY` in your `.env` file.
 - `OLLAMA_UNREACHABLE`: Ollama is not running (`ollama serve`) or you have not pulled the requested model (`ollama list`).