feat(config,drivers): per-agent and per-task reasoning mode for DeepSeek V4 and OpenRouter - #8083

Closes #7946.

Design decisions

Config surface. reasoning_mode = "none" | "low" | "high" | "max" was added as a field on the existing ThinkingConfig, not as a new top-level knob. That one struct is already the global [thinking] table in config.toml and the per-agent [thinking] table in agent.toml, so a single field gets both rungs and needs no new plumbing between the kernel and the driver. Per CLAUDE.md #5476 the per-agent knob is in agent.toml — KernelConfig has no agents field, so [agents.<name>.thinking] in config.toml would parse and reach no manifest.

Per-call field shape: a new reasoning_mode key, not a widened thinking. The boolean is in the wire contract of every existing client and a JSON true cannot grow a third value without breaking them. The two are also not redundant: thinking: false merely omits the reasoning opt-in, while reasoning_mode: "none" sends the provider's explicit non-think toggle — the difference between "we did not ask it to think" and "we asked it not to", which is the entire point on a model that reasons by default. When both keys are present reasoning_mode wins. Below the HTTP boundary the two collapse into one ThinkingOverride value so nothing downstream threads two parameters that can disagree.

Resolution order: per-call > per-agent > global > compiled default, the same shape CLAUDE.md documents for max_history_messages and session_mode. Mechanically: the manifest carries the agent's own table; the kernel backfills the global table only when the manifest has none (so a per-agent table wins by suppressing the backfill, not by merging); apply_thinking_override stamps the per-call value on last; whatever survives is copied onto the CompletionRequest.

medium is not a settable mode. It remains reachable only as the budget_tokens fallback bucket. A fifth rung whose only distinct meaning is "DeepSeek folds it into high" is a knob that does nothing on the provider that motivated the feature. TOML parsing rejects it explicitly rather than silently falling back.

Unset reasoning_mode changes nothing. A DeepSeek V4 body with no mode is byte-for-byte what it was before this PR, and the budget_tokens bucket remains the fallback everywhere it applied. DeepSeek ignores budget_tokens, so deriving an effort from the budget for V4 would have changed the wire shape of every existing V4 request without changing what the model does. Opting in is how behaviour changes.

Deliberately left to the UI: the dashboard agent-edit form and the TUI do not surface reasoning_mode. The issue lists UI exposure as optional and it is omitted to keep this PR reviewable.

Per-provider wire mapping

Resolved in one function, reasoning_wire_fields in openai.rs. The family comes from base_url, not the model id — openrouter/deepseek/deepseek-v4-pro and a direct deepseek-v4-pro are the same model behind two different dialects.

• No payload ever carries both reasoning_effort and reasoning.effort — OpenRouter answers HTTP 400 to one that does. The invariant is asserted exhaustively over every (family × echo policy × mode × budget × rejected) combination, not case by case, because a future branch that sets the wrong pair would otherwise surface only as a production 400 on one provider.
• none is expressed by omission on generic endpoints because OpenAI answers 400 to the literal reasoning_effort: "none"; max is clamped to high there because the OpenAI schema has no rung above it.
• The stale comment in openai.rs claiming "this API family rejects requests with unexpected reasoning fields" predated V4 and is corrected.
• Kimi/Moonshot (EmptyString policy) keeps forcing thinking: {"type":"disabled"} regardless of mode — that is a multi-turn tool_calls correctness requirement, not a preference.
• DeepSeek R1 (Strip) still gets nothing, in either dialect. The Strip check short-circuits ahead of the OpenRouter branch on purpose: without it, an R1 route through OpenRouter with a configured budget_tokens would have started receiving a reasoning.effort it never got before, changing the payload without changing the model (R1 reasons unconditionally and has no toggle). Caught on self-review and pinned by deepseek_r1_gets_no_reasoning_control_in_either_dialect.

Changes

• librefang-types: new ReasoningMode enum (serde snake_case, Serialize/Deserialize/JsonSchema, as_str/Display); new reasoning_mode: Option<ReasoningMode> field on ThinkingConfig with #[serde(default)] and a Default impl entry; new ThinkingOverride (Inherit / Enable / Disable / Mode) with resolve(Option<bool>, Option<ReasoningMode>) and From<Option<bool>>.
• librefang-llm-drivers: reasoning_wire_fields plus the three per-family vocabulary functions; new reasoning field on OaiRequest for OpenRouter's nested object; reasoning_wire_family() derived from base_url; the three reasoning fields of the outbound body now all come from the one resolver.
• librefang-llm-drivers: the bug(llm): a gateway that rejects reasoning_effort fails every turn and then opens the provider circuit breaker #7769 strip-and-retry in both complete() and stream() now clears both spellings, and the negative cache suppresses both, since an OpenRouter-routed body carries the nested object rather than the top-level field.
• librefang-kernel: thinking_override threaded as ThinkingOverride instead of Option<bool> through the message and streaming dispatch chains; pre-existing public entry points that take the boolean (the /think channel toggle, WebSocket) keep their signature and convert at the boundary via From. apply_thinking_override handles the four cases.
• librefang-kernel: send_message_streaming_with_incognito gained the override parameter. It previously passed a hardcoded None, so the SSE streaming endpoint silently dropped the per-call thinking override entirely — a per-task mode wired only into the buffered route would have been invisible to any streaming UI. Both routes now honour both keys.
• librefang-api: reasoning_mode on MessageRequest; both send_message and send_message_stream build the override with ThinkingOverride::resolve.
• librefang-api: redacted_config_json now emits thinking.reasoning_mode, so GET /api/config exposes what POST /api/config/set accepts. The every_writable_config_leaf_is_readable parity guard (GET /api/config omits config fields that PUT accepts — write-only settings are invisible in the dashboard #6596) caught the omission — without it the dashboard would render the field blank and read a successful save back as "not configured".
• Regenerated crates/librefang-api/tests/fixtures/kernel_config_schema.golden.json — the new ReasoningMode definition plus the ThinkingConfig property.
• Docs: new docs/architecture/reasoning-mode-resolution.md; [thinking] sections updated in docs/src/app/configuration/page.mdx, docs/src/app/configuration/features/page.mdx and both zh mirrors; librefang.toml.example (with its xtask/baselines/config.sha256 recomputed).
• Changelog fragment changelog.d/added/7946-per-agent-reasoning-mode.md.

Verification

Scoped to the four crates this PR touches. cargo clippy --workspace --all-targets was NOT run: the shared host ran out of disk during it (No space left on device while writing librefang-api's query cache), and the coordinator asked that it not be retried. CI runs the workspace-wide lane.

cargo check --workspace --lib                                        # clean
cargo clippy -p librefang-types       --all-targets -- -D warnings   # zero warnings
cargo clippy -p librefang-llm-drivers --all-targets -- -D warnings   # zero warnings
cargo clippy -p librefang-kernel      --all-targets -- -D warnings   # zero warnings
cargo clippy -p librefang-api         --all-targets -- -D warnings   # zero warnings
cargo test -p librefang-types                                        # 1031 + 5 + 49 + 3 + 4 + 2 passed, 0 failed
cargo test -p librefang-llm-drivers                                  # 657 lib + every integration bin passed, 0 failed
cargo test -p librefang-kernel                                       # KERNEL_TEST_RESULT
cargo test -p librefang-api --lib                                    # 1145 passed, 0 failed
cargo test -p librefang-api --test agents_routes_integration         # 72 passed, 0 failed
cargo test -p librefang-api --test config_schema_golden              # 1 passed (golden matches)
cargo test -p librefang-api --test openapi_spec_test                 # 2 passed (openapi.json regenerated, in sync)
cargo test -p librefang-api --test dead_route_audit_test             # 1 passed
cargo test -p librefang-api --test openapi_path_coverage_test        # 1 passed
python3 scripts/codegen-sdks.py                                      # SDKs regenerated, no diff
python3 scripts/check-changelog-attribution.py                        # OK

New tests:

Wire shape — crates/librefang-llm-drivers/src/drivers/openai.rs, each asserting the serialized body and what is absent as well as what is present:

• deepseek_v4_direct_none_mode_disables_thinking_on_the_wire
• deepseek_v4_direct_graded_modes_enable_thinking_with_effort (low / high / max)
• deepseek_v4_without_a_mode_keeps_the_pre_7946_wire_shape
• openrouter_routed_deepseek_uses_the_nested_reasoning_object (all four modes, max → xhigh)
• openrouter_falls_back_to_the_budget_bucket_without_a_mode
• generic_openai_compatible_model_maps_modes_to_top_level_effort
• explicit_mode_wins_over_the_budget_bucket
• kimi_disable_wins_over_an_explicit_reasoning_mode
• a_rejected_reasoning_control_suppresses_both_spellings
• deepseek_r1_gets_no_reasoning_control_in_either_dialect
• no_payload_ever_carries_both_reasoning_controls — the exhaustive mutual-exclusion guard

Resolution order — crates/librefang-kernel/src/kernel/tests.rs:

• test_reasoning_mode_global_reaches_an_agent_that_declares_nothing
• test_reasoning_mode_per_agent_beats_global
• test_reasoning_mode_per_call_beats_per_agent_beats_global
• test_reasoning_mode_per_call_creates_thinking_config_when_absent
• test_disable_and_mode_none_are_not_the_same_thing

Config / manifest surface — librefang-types:

• test_thinking_config_parses_reasoning_mode_from_toml, test_thinking_config_reasoning_mode_defaults_to_none, test_thinking_config_rejects_an_unknown_reasoning_mode, test_reasoning_mode_serde_spelling_matches_as_str, test_thinking_override_resolve_precedence
• test_manifest_thinking_reasoning_mode_round_trips_through_toml, test_manifest_thinking_without_reasoning_mode_stays_absent

API — crates/librefang-api/tests/agents_routes_integration.rs, #[tokio::test] against the production router:

• test_reasoning_mode_field_accepted_by_message_endpoint
• test_invalid_reasoning_mode_is_rejected — the conclusive one. MessageRequest does not deny unknown fields, so "accepted" alone would also pass for a typo'd key; a "banana" mode can only 422 if serde is genuinely parsing the field into ReasoningMode.
• test_reasoning_mode_omitted_and_legacy_thinking_boolean_still_work
• test_reasoning_mode_accepted_by_streaming_message_endpoint
• test_per_call_reasoning_mode_wins_over_the_legacy_boolean — asserts the override the handler builds, i.e. the injection site, per CLAUDE.md's warning that an Option::None default compiles silently while disabling the feature

Prompt-ordering determinism (#3298) does not apply: nothing added here reaches a prompt. The one map-shaped surface in the outbound body, extra_body, was already a BTreeMap, and the new reasoning field is a fixed-shape single-key object.

Human-only verification (live daemon + real provider)

Not run here — live daemon plus a real LLM is human-only per CLAUDE.md. The wire shape is pinned by unit tests, but only a real endpoint proves the provider accepts the payload.

Start the daemon the usual way (librefang + the start subcommand) with a real key configured, then:

DeepSeek V4 direct — non-think, then max:

curl -sS -X POST localhost:4545/api/agents/$AGENT/message \
  -H 'content-type: application/json' -H "authorization: Bearer $LIBREFANG_TOKEN" \
  -d '{"message":"What is 2+2? One word.","reasoning_mode":"none"}' | jq .
# expect: 200, no thinking trace, output_tokens close to the answer length

curl -sS -X POST localhost:4545/api/agents/$AGENT/message \
  -H 'content-type: application/json' -H "authorization: Bearer $LIBREFANG_TOKEN" \
  -d '{"message":"Plan a three-stage migration.","reasoning_mode":"max"}' | jq .
# expect: 200, a visible thinking trace, materially more output tokens than the run above

To confirm the bytes rather than the outcome, run the daemon with RUST_LOG=librefang_llm_drivers=trace and grep the request bodies for thinking / reasoning:

• none → "thinking":{"type":"disabled"} and no reasoning_effort
• max → "thinking":{"type":"enabled"} and "reasoning_effort":"max"

OpenRouter-routed — the mutual-exclusion case, which is the one that 400s if it regresses. Point an agent at openrouter/deepseek/deepseek-v4-pro with a real OPENROUTER_API_KEY:

for m in none low high max; do
  curl -sS -o /dev/null -w "$m -> %{http_code}\n" \
    -X POST localhost:4545/api/agents/$AGENT_OR/message \
    -H 'content-type: application/json' -H "authorization: Bearer $LIBREFANG_TOKEN" \
    -d "{\"message\":\"ping\",\"reasoning_mode\":\"$m\"}"
done
# expect 4x 200. A 400 means the body carried both reasoning_effort and reasoning.effort.
# On the wire, max must appear as "reasoning":{"effort":"xhigh"}.

Per-agent and global rungs — put [thinking] reasoning_mode = "none" in the agent's agent.toml and [thinking] reasoning_mode = "max" in config.toml, then:

curl -sS -X POST localhost:4545/api/config/reload -H "authorization: Bearer $LIBREFANG_TOKEN"
curl -sS -X POST localhost:4545/api/agents/$AGENT/message \
  -H 'content-type: application/json' -H "authorization: Bearer $LIBREFANG_TOKEN" \
  -d '{"message":"ping"}'
# expect the agent's "none" to win over the global "max"

Streaming route — the same body against /api/agents/{id}/message/stream, to confirm the per-call override now reaches the SSE path (it did not before this PR).

Deferred / out of scope

• Dashboard and TUI exposure — optional per the issue, omitted deliberately (above).
• Anthropic / Gemini / Ollama drivers still read budget_tokens and ignore reasoning_mode. Their wire control is a token budget rather than an effort enum, so honouring the mode there means inventing a mode→budget mapping that would silently change the budget existing Claude users already configured and pay for. That is a different provider family and a different behavioural risk than the issue describes, and it wants its own decision rather than a mapping picked here — flagging rather than deciding unilaterally, per CLAUDE.md. Stated explicitly in the architecture page's "Providers that ignore the mode" table so it is a documented boundary, not a surprise.
• The WebSocket chat path still carries the /think boolean only. Adding a mode there means changing the WS message envelope, which is the UI work above.
• openapi.json and both xtask/baselines/*.sha256 files are regenerated and committed here (cargo xtask codegen --openapi's underlying test, then shasum -a 256 — the same bytes schema-check gen writes). scripts/codegen-sdks.py produced no SDK diff. CI's openapi-drift lane should therefore find everything in sync.
• No dashboard or TUI change at all, including no i18n label. ConfigPage.tsx renders schema-driven config fields through t(config.fld_${key}, fieldLabelFallback(key)), so [thinking] reasoning_mode degrades to a humanized "Reasoning Mode" label rather than breaking; adding a key to en.json alone would trip locale-parity.test.ts.
• ⚠️ One dashboard gap a maintainer should decide on, because it can lose a setting rather than merely fail to show it. dashboard/src/lib/agentManifest.ts lists thinking in FORM_TOP_LEVEL_KEYS, so serializeManifestForm rebuilds the entire [thinking] table from its form model (agentManifest.ts:78-82 type, :537-542 write, :999-1003 parse). A key the form model does not hold is a key a dashboard agent-edit silently deletes from agent.toml — so an agent pinned to reasoning_mode = "none" would quietly revert to the provider default of thinking-on, and be billed for the reasoning. The fix is ~6 lines of preservation (carry it as an opaque string through parse and write, no UI), not the optional form field. I wrote it, then dropped it on instruction to keep this PR to the config-plus-wire surface, and because dashboard/node_modules is absent on this host so the vitest lane could not be run locally. Worth doing in the same cycle as the UI work, ahead of anyone setting the key and then editing that agent in the dashboard.