melchizedek-agents 0.18.0 → 0.19.0

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`).