Skip to content

Commit fa42662

Browse files
feat(opencode): research-backed agent tuning (#225)
* fix(opencode): rename max_iterations to steps The OpenCode agent schema uses `steps` for iteration caps; `max_iterations` is not a recognized field and was being silently passed through to the provider as an opaque option, leaving every agent effectively unbounded. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> * feat(opencode): tune small_model, instructions, plan temperature - small_model: route lightweight calls (title generation) to gemini-3-flash-preview, already used by the review agent - instructions: explicit AGENTS.md reference; auto-discovery would find it anyway, this just documents the dependency - plan agent: temperature 0.3 → 0.1 to match the docs' recommended 0.0-0.2 range for planning/analysis work Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> * chore(opencode): disable autoupdate Nix manages the package version via the nixpkgs derivation, so OpenCode's runtime self-update has nothing to write to (read-only /nix/store). This silences the update check / "update available" prompts and avoids the network call. The nixpkgs derivation does not suppress this on its own — it only sets OPENCODE_DISABLE_MODELS_FETCH for the model registry, not the binary auto-updater. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> * fix(opencode): tune sampling params to match model card recommendations Every agent was running with temperature 0.1-0.2, but the model cards for all three configured models (Kimi K2.6, DeepSeek V4 Flash, Gemini 3 Flash) explicitly recommend temp=1.0 with model-specific top_p, and warn that lower temps cause repetition / looping / degraded reasoning. These are the same anti-patterns Qwen has below 0.3. - build (Kimi K2.6, primary): 1.0 / top_p 0.95 thinking-mode profile - plan (Kimi K2.6, primary): 0.6 / top_p 0.95 instant-mode profile - debug (Kimi K2.6, subagent): 0.6 / top_p 0.95 instant-mode profile - explore (DeepSeek V4 Flash): 1.0 / top_p 1.0 V4 model card guidance - review (Gemini 3 Flash, prev): unset Google strongly recommends keeping Gemini 3 default 1.0 Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> * fix(opencode): task-aware sampling pass — reasoning, top_p, steps, small_model Per-role tuning derived from each provider's model card and OpenRouter's reasoning-tokens spec. Three parallel research agents (one per configured model) converged on the same field convention (`reasoningEffort` camelCase scalar) and the values below. small_model: gemini-3-flash-preview → gemini-2.5-flash-lite OpenCode's schema makes small_model a string with no per-call overrides, so titles/summaries always run with Gemini 3 Flash's default thinking_level=high — wasteful for 5-token title generation. flash-lite has no reasoning overhead, GA not preview, ~75% cheaper for aux calls. Per-agent changes (all bumped from previously-too-tight steps caps): build (Kimi K2.6, primary) top_p 0.95 → 1.0 (mirror Moonshot's SWE-bench harness exactly) steps 25 → 50 (Moonshot's published max-steps=50) + reasoningEffort = "high" plan (Kimi K2.6, primary) temperature 0.6 → 1.0 (was uncommitted; thinking-mode profile) steps 15 → 20 + reasoningEffort = "xhigh" (most reasoning-bound role; highest leverage knob in the whole config) debug (Kimi K2.6, subagent) temperature 0.6 → 1.0 (was uncommitted; thinking-mode profile) steps 15 → 30 + reasoningEffort = "high" (hypothesis-driven test/observe loops) explore (DeepSeek V4 Flash, subagent) steps 10 → 20 + reasoningEffort = "high" (NOT xhigh — Think Max requires ≥384K context and burns ~95% of budget on reasoning; wrong for a blocking subagent) review (Gemini 3 Flash Preview, subagent) steps 10 → 20 + reasoningEffort = "high" Temperature stays unset by design — Google explicitly warns that any override below default 1.0 causes "looping or degraded performance, particularly with complex reasoning tasks." Operational watch-out: anomalyco/opencode#24190 reports DeepSeek V4 multi-turn tool calls with reasoning enabled may return 400s due to reasoning_details not being round-tripped (related: #4367). If this fires on the explore subagent, the workaround is reasoningEffort = "none". Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> * fix(opencode): correct schema/passthrough issues found in source-level audit Three parallel research agents — one auditing the JSON schema, one comparing against community configs, one reading OpenCode's source for the reasoning passthrough — surfaced four corrections to the previous commit. The previous values were correct in spirit, but the field names and structure didn't actually do what they claimed. theme → tui.json The root config schema has additionalProperties: false and the docs state theme/keybinds moved to a sibling tui.json. Runtime currently accepts it via fallback but strict validators reject. Fix: write ~/.config/opencode/tui.json with { "theme": "dracula" } and drop the field from opencode.json. reasoningEffort → options.reasoning.effort Confirmed against packages/opencode/src/provider/transform.ts and the OpenRouter AI SDK provider tests: agent-level reasoningEffort is normalised onto agent.options.reasoningEffort, then spread into providerOptions.openrouter.reasoningEffort — which OpenRouter silently ignores (only the nested reasoning: { effort } object is recognised). The wrapping options = { reasoning = { effort = "..."; }; } is the shape that actually propagates to the request body. - build, plan, debug, explore: switched to options.reasoning.effort. - review: reasoningEffort dropped entirely. transform.ts:875-877 hardcodes reasoning: { effort: "high" } unconditionally for any gemini-3* model regardless of agent setting, so any per-agent setting is redundant. permission.write removed Per the schema and docs, "write" is not a canonical permission key. The wildcard block was being silently absorbed by additionalProperties and doing nothing. File writes are gated by the "edit" permission, which already denies them where applicable. build top_p 1.0 → 0.95 OpenCode auto-injects temp=1.0, top_p=0.95 for kimi-k2.6 (per transform.ts model-specific defaults), matching Moonshot's official K2.6 model card. The previous 1.0 mirrored the SWE-bench harness but overrode the smarter built-in default. 0.95 brings build into line with the rest of the Kimi agents and the OpenCode/Moonshot consensus. Known limitations (not in this commit): - For Kimi K2.6 via OpenRouter, OpenCode has no client-side "thinking-on" toggle (auto-thinking is gated to @ai-sdk/anthropic only, transform.ts:914-922). The options.reasoning.effort value propagates to OpenRouter, which forwards it to Moonshot, but the underlying behaviour depends on Moonshot's gateway honouring it. - DeepSeek V4 Flash multi-turn tool calls via OpenRouter still has open issues anomalyco/opencode#24569 and #24722 around reasoning_content not being round-tripped. Workaround if 400s fire on the explore subagent: drop options.reasoning.effort entirely. - Verification command: OPENCODE_LOG_LEVEL=DEBUG opencode run --agent build "say hi" \ 2>&1 | grep -iE 'temperature|top_p|reasoning' Expect to see reasoning: { effort: "..." } in the outgoing request, not reasoningEffort: "..." at the top level. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> * docs(opencode): document research findings, references, and gotchas Add comprehensive in-file documentation so future readers can understand WHY each value was chosen without re-running the research. Captures: * Verification recipe — OPENCODE_LOG_LEVEL=DEBUG command plus `opencode debug agent <name>` for inspecting resolved per-agent settings. * Primary references — schema URL, agents/config/permission docs, OpenCode source (transform.ts is the canonical location for model defaults and the reasoning passthrough whitelist), OpenRouter reasoning-tokens guide. * Open issues to monitor — DeepSeek V4 multi-turn 400s (#24569, #24722), Kimi/Qwen variants exclusion (#23334 / PR #23335), subagent variants runtime application (#21632), TUI reasoning visibility (#18634), with a 2026-04-28 snapshot date. * Conventions block — explains the four cross-cutting rules (Kimi sampling profile, options.reasoning.effort vs reasoningEffort, steps Infinity default, permission.write being a no-op key) before the agent blocks so each agent's comment can stay focused on its specifics. * Per-section comments — each top-level field and each agent gets a rationale block citing the model card / source line / community precedent that justifies its values, plus model-specific caveats (Kimi has no client-side thinking toggle; DeepSeek V4 may 400 on multi-turn; Gemini 3 hardcodes reasoning effort=high). No behaviour change — only comments. Flake check passes; serialised opencode.json is byte-identical since Nix strips comments at evaluation. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> --------- Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
1 parent bac265a commit fa42662

1 file changed

Lines changed: 207 additions & 15 deletions

File tree

‎modules/home-manager/opencode.nix‎

Lines changed: 207 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,77 @@
1+
# OpenCode configuration — research-backed agent tuning.
2+
# ============================================================================
3+
#
4+
# Verification (run after `darwin-rebuild switch` on a host with this enabled):
5+
#
6+
# OPENCODE_LOG_LEVEL=DEBUG opencode run --agent build "say hi" 2>&1 \
7+
# | grep -iE 'temperature|top_p|reasoning'
8+
#
9+
# Expect `reasoning: { effort: "..." }` in the outgoing request body.
10+
# A bare top-level `reasoningEffort: "..."` is silently DROPPED by OpenRouter
11+
# (only the nested `reasoning.effort` shape is recognised).
12+
#
13+
# Inspecting merged config:
14+
# opencode debug agent build # resolved per-agent settings
15+
# opencode debug config # merged top-level config
16+
#
17+
# ----------------------------------------------------------------------------
18+
# Primary references:
19+
# Schema: https://opencode.ai/config.json
20+
# Agent docs: https://opencode.ai/docs/agents/
21+
# Config docs: https://opencode.ai/docs/config/
22+
# Permission docs: https://opencode.ai/docs/permissions/
23+
# OpenCode source: https://github.com/sst/opencode
24+
# (packages/opencode/src/provider/transform.ts holds the
25+
# model-specific default temperature/top_p, plus the
26+
# reasoning-passthrough whitelist that excludes Kimi /
27+
# DeepSeek-V4 / MiniMax / GLM / Qwen)
28+
# OpenRouter: https://openrouter.ai/docs/guides/best-practices/reasoning-tokens
29+
#
30+
# ----------------------------------------------------------------------------
31+
# Open issues to monitor (snapshot 2026-04-28):
32+
# anomalyco/opencode#24569 + #24722 DeepSeek V4 reasoning_content not
33+
# round-tripped → 400 on multi-turn
34+
# tool calls. If `explore` fires this,
35+
# drop its options.reasoning.effort.
36+
# anomalyco/opencode#23334 / PR #23335 Proposes lifting the Kimi/Qwen
37+
# exclusion from variants() so that
38+
# the reasoning passthrough actually
39+
# reaches Kimi via OpenRouter.
40+
# anomalyco/opencode#21632 Subagent variants parsed but not applied at
41+
# runtime in v1.4.0+.
42+
# anomalyco/opencode#18634 reasoningEffort=xhigh not visible in TUI/export.
43+
#
44+
# ----------------------------------------------------------------------------
45+
# Conventions used below:
46+
#
47+
# * `temperature` and `top_p` for Kimi K2.6 follow Moonshot's thinking-mode
48+
# profile (1.0 / 0.95). Moonshot LOCKS the temperature to the active mode
49+
# on its official API (thinking=1.0, instant=0.6); OpenRouter relays
50+
# without erroring but the recommendation still stands. OpenCode also
51+
# auto-injects 1.0/0.95 for any kimi-k2.5/2.6/k2-thinking model in
52+
# transform.ts, so the explicit values are documentation-equal-to-default.
53+
# https://huggingface.co/moonshotai/Kimi-K2.6
54+
# https://platform.kimi.ai/docs/guide/use-kimi-k2-thinking-model
55+
#
56+
# * `options.reasoning.effort` (NOT bare `reasoningEffort`). OpenCode
57+
# normalises agent-level `reasoningEffort` into
58+
# providerOptions.openrouter.reasoningEffort, which OpenRouter silently
59+
# ignores. The nested `options.reasoning.effort` form lands at
60+
# providerOptions.openrouter.reasoning.effort — the shape OpenRouter
61+
# actually consumes (verified in OpenRouterTeam/ai-sdk-provider source
62+
# and tests).
63+
#
64+
# * `steps` defaults to Infinity if unset (`agent.steps ?? Infinity` in
65+
# packages/opencode/src/session/prompt.ts). Always cap explicitly.
66+
# Community range observed across 12+ public configs: 4 to 400; this
67+
# config sits on the conservative side of normal.
68+
#
69+
# * `permission.write` is NOT a canonical permission key per the schema;
70+
# it's silently absorbed by additionalProperties and does NOTHING. The
71+
# `edit` permission already gates the {edit, write, patch} tool group
72+
# per OpenCode docs.
73+
# ============================================================================
74+
175
{
276
config,
377
lib,
@@ -16,68 +90,186 @@ in
1690
config = lib.mkIf cfg.enable {
1791
home.packages = [ pkgs.opencode ];
1892
home.file.".config/opencode/themes/dracula.json".source = "${inputs.opencode-dracula-theme}/dracula.json";
93+
94+
# tui.json — theme, keybinds, TUI settings.
95+
# The root opencode.json schema has additionalProperties:false and rejects
96+
# `theme` at top level. Modern strict validators flag it; runtime currently
97+
# accepts via fallback but the canonical placement is a sibling tui.json.
98+
home.file.".config/opencode/tui.json".text = builtins.toJSON {
99+
theme = "dracula";
100+
};
101+
19102
home.file.".config/opencode/opencode.json".text = builtins.toJSON {
20103
"$schema" = "https://opencode.ai/config.json";
21-
theme = "dracula";
104+
105+
# Nix manages the package version. The nixpkgs derivation does NOT
106+
# suppress this on its own — only OPENCODE_DISABLE_MODELS_FETCH is set
107+
# there. Without this opt-out, OpenCode tries to self-update its binary
108+
# in /nix/store (read-only) and emits "update available" notices.
109+
autoupdate = false;
110+
111+
# Default model for any agent that doesn't override.
112+
# Kimi K2.6 chosen for long-horizon agentic work — Moonshot's design
113+
# target is 200-300 sequential tool calls and a 4000-step horizon, with
114+
# benchmark numbers achieved at temp=1.0, top_p=1.0 (build mirrors model
115+
# card 0.95 instead of benchmark 1.0; both are valid, 0.95 matches
116+
# OpenCode's auto-default).
117+
# https://openrouter.ai/moonshotai/kimi-k2.6 (~$0.74 in / $4.65 out per Mtok, 256k ctx)
22118
model = "openrouter/moonshotai/kimi-k2.6";
119+
120+
# small_model — title generation, conversation summarisation, lightweight
121+
# auxiliary calls. OpenCode schema makes this a STRING ONLY: no per-call
122+
# parameter overrides are possible (verified against
123+
# https://opencode.ai/config.json — the field is `{type: "string",
124+
# $ref: "model-schema.json#/$defs/Model"}`).
125+
#
126+
# Gemini 2.5 Flash Lite chosen because:
127+
# 1. Same provider family as the review agent's Gemini 3 Flash.
128+
# 2. No reasoning overhead — using gemini-3-flash-preview here would
129+
# route every 5-token title through thinking_level=high (Gemini 3's
130+
# hardcoded default in OpenCode's transform.ts:875-877), wasteful at
131+
# $3.00 per Mtok output.
132+
# 3. GA, not preview. ~$0.10 in / $0.40 out per Mtok.
133+
# https://openrouter.ai/google/gemini-2.5-flash-lite
134+
small_model = "openrouter/google/gemini-2.5-flash-lite";
135+
136+
# AGENTS.md auto-discovery walks up from cwd anyway; listing it
137+
# explicitly documents the dependency for any custom rules in the file.
138+
instructions = [ "AGENTS.md" ];
139+
23140
agent = {
141+
142+
# ----------------------------------------------------------------
143+
# build — primary implementation agent (full coding/edit/bash).
144+
# Sampling: Kimi K2.6 thinking-mode profile (Moonshot model card).
145+
# steps=50 matches Moonshot's published max-steps multi-step eval
146+
# ceiling. Community precedent: arvinmi=50, pshevche=80, ushiradineth
147+
# builder=80 (Kimi-class build agents typically sit 50-100).
148+
# ----------------------------------------------------------------
24149
build = {
25150
description = "Full-featured coding agent for implementation and complex changes. Writes code, runs tests, manages files, and executes system commands. Use for: building features, bug fixes, large refactors, dependency updates, and any task requiring code modifications.";
26151
mode = "primary";
27152
model = "openrouter/moonshotai/kimi-k2.6";
28-
temperature = 0.2;
29-
max_iterations = 25;
153+
temperature = 1.0;
154+
top_p = 0.95;
155+
# KIMI CAVEAT: OpenCode has no client-side thinking-on toggle for
156+
# Kimi via OpenRouter — auto-thinking is gated to @ai-sdk/anthropic
157+
# only (transform.ts ~lines 914-922). This value propagates as
158+
# `reasoning: { effort: "high" }` in the request body; whether
159+
# thinking actually engages depends on the OpenRouter→Moonshot
160+
# gateway honouring it. See issue #23334 for proposal to lift the
161+
# Kimi exclusion in variants().
162+
options = {
163+
reasoning = { effort = "high"; };
164+
};
165+
steps = 50;
30166
};
167+
168+
# ----------------------------------------------------------------
169+
# plan — primary, read-only architecture/design.
170+
# Most reasoning-bound role in the config — gets `xhigh` (≈95% of
171+
# max_tokens budget allocated to reasoning per OpenRouter spec).
172+
# Kimi's underlying API is binary thinking on/off, so xhigh likely
173+
# maps to "high" upstream — that's still the right intent.
174+
# ----------------------------------------------------------------
31175
plan = {
32176
description = "Architecture and planning specialist. Analyzes code, designs solutions, and creates implementation plans without modifying files. Use for: system design, code review preparation, technical decisions, refactoring strategies, and understanding complex codebases.";
33177
mode = "primary";
34178
model = "openrouter/moonshotai/kimi-k2.6";
35-
temperature = 0.3;
36-
max_iterations = 15;
179+
temperature = 1.0;
180+
top_p = 0.95;
181+
options = {
182+
reasoning = { effort = "xhigh"; };
183+
};
184+
steps = 20;
37185
permission = {
38-
write = { "*" = "deny"; };
39186
edit = { "*" = "deny"; };
40187
bash = { "*" = "deny"; };
41188
};
42189
};
190+
191+
# ----------------------------------------------------------------
192+
# explore — subagent, read-only codebase navigator.
193+
# DeepSeek V4 Flash chosen for cheap fast retrieval ($0.14/$0.28
194+
# per Mtok). Model card mandates temp=1.0, top_p=1.0 across ALL
195+
# modes — explicitly supersedes the legacy V3 per-task table that
196+
# said coding=0.0. Lower values (the GPT/Claude habit) are
197+
# documented anti-patterns for V4.
198+
# https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash
199+
# ----------------------------------------------------------------
43200
explore = {
44201
description = "Fast codebase navigator for discovery and analysis. Searches files, finds references, maps dependencies, and answers questions about code structure. Use for: understanding unfamiliar codebases, finding functions/classes, tracing data flows, and locating configuration.";
45202
mode = "subagent";
46203
model = "openrouter/deepseek/deepseek-v4-flash";
47-
temperature = 0.1;
48-
max_iterations = 10;
204+
temperature = 1.0;
205+
top_p = 1.0;
206+
# NOT xhigh — that maps to DeepSeek "Think Max" which requires
207+
# ≥384K context (393,216 per the vLLM recipe) and burns ~95% of the
208+
# token budget on reasoning. Wrong for a blocking subagent that a
209+
# primary is waiting on.
210+
#
211+
# WATCH-OUT: anomalyco/opencode#24569 + #24722 (open) report 400s
212+
# on V4 multi-turn tool calls when reasoning is enabled, because
213+
# reasoning_content is not round-tripped via OpenRouter. If this
214+
# fires on real usage, drop the options block and accept Non-think
215+
# mode for explore.
216+
options = {
217+
reasoning = { effort = "high"; };
218+
};
219+
steps = 20;
49220
permission = {
50-
write = { "*" = "deny"; };
51221
edit = { "*" = "deny"; };
52222
bash = { "*" = "deny"; };
53223
read = { "*" = "allow"; };
54224
glob = { "*" = "allow"; };
55225
grep = { "*" = "allow"; };
56226
};
57227
};
228+
229+
# ----------------------------------------------------------------
230+
# review — subagent, code quality + security review.
231+
# No temperature/top_p — Google explicitly warns that any override
232+
# below default 1.0 causes "looping or degraded performance,
233+
# particularly with complex reasoning tasks." Defaults: 1.0/0.95.
234+
# https://ai.google.dev/gemini-api/docs/gemini-3
235+
#
236+
# No options.reasoning.effort either — OpenCode's transform.ts
237+
# (~lines 875-877) unconditionally hardcodes
238+
# `reasoning: { effort: "high" }` for any gemini-3* model.
239+
# Setting it here would be silently redundant.
240+
# ----------------------------------------------------------------
58241
review = {
59242
description = "Code quality and security reviewer. Identifies bugs, security vulnerabilities, performance issues, and style violations. Use for: PR reviews, security audits, best practice enforcement, and spotting potential edge cases or anti-patterns.";
60243
mode = "subagent";
61244
model = "openrouter/google/gemini-3-flash-preview";
62-
temperature = 0.1;
63-
max_iterations = 10;
245+
steps = 20;
64246
permission = {
65-
write = { "*" = "deny"; };
66247
edit = { "*" = "deny"; };
67248
bash = { "*" = "deny"; };
68249
read = { "*" = "allow"; };
69250
glob = { "*" = "allow"; };
70251
grep = { "*" = "allow"; };
71252
};
72253
};
254+
255+
# ----------------------------------------------------------------
256+
# debug — subagent, troubleshooting with bash.
257+
# steps=30 sized for diagnostic loops (test → observe →
258+
# re-hypothesise → test). Community qa/diagnostic agents on
259+
# Kimi-class typically 50-80; 30 is conservative within that band
260+
# while still well above plan/build's read-only ceiling.
261+
# ----------------------------------------------------------------
73262
debug = {
74263
description = "Diagnostic specialist for troubleshooting and investigation. Runs tests, inspects logs, reproduces issues, and analyzes error patterns. Use for: debugging failures, investigating performance issues, analyzing test results, and diagnosing system problems.";
75264
mode = "subagent";
76265
model = "openrouter/moonshotai/kimi-k2.6";
77-
temperature = 0.1;
78-
max_iterations = 15;
266+
temperature = 1.0;
267+
top_p = 0.95;
268+
options = {
269+
reasoning = { effort = "high"; };
270+
};
271+
steps = 30;
79272
permission = {
80-
write = { "*" = "deny"; };
81273
edit = { "*" = "deny"; };
82274
bash = { "*" = "allow"; };
83275
read = { "*" = "allow"; };

0 commit comments

Comments
 (0)