fix(buzz-agent): budget summarizer reasoning separately so it cannot starve the handoff summary

[tlongwell-block]

Problem

The handoff summarizer sends max_tokens: 8192 (HANDOFF_MAX_OUTPUT_TOKENS) with no reasoning budget separation. On reasoning models, thinking tokens count against that cap: the model can spend the entire budget reasoning, length-stop with empty content, and summarize() — which only reads content — reports an empty summary. The handoff then degrades to lossy history truncation.

Observed on deepseek-v4-flash during a terminal-bench 2.1 run (tb21-solo-3, 89 tasks): 13 consecutive handoff attempts across 5 trials failed exactly this way (handoff returned empty summary; truncating), each burning ~3 minutes of full-cap reasoning, before a stochastically-short reasoning run finally fit. circuit-fibsqrt alone: 5 failures, 5 truncations, then success on attempt 6. video-processing failed its task by one frame after 3 context truncations.

Fix

openrouter_summary_body now grants reasoning its own equal-sized budget and excludes it from the response:

• reasoning.max_tokens = max_output_tokens — thinking gets a dedicated budget instead of competing with the summary text
• reasoning.exclude = true — reasoning is never in the response body; summarize() only reads content
• max_tokens = max_output_tokens * 2 — the total cap covers both budgets, so the text budget the caller asked for is actually available for text

Non-reasoning endpoints ignore the reasoning object. Deliberately not paired with provider.require_parameters, for the reasons documented at apply_openrouter_mutations (it hard-404s valid model ids).

The prior test openrouter_summary_carries_neither_reasoning_nor_provider asserted reasoning absent from the summary body — that assertion guarded against effort-based reasoning leaking in from config (the body is built independently of cfg, which is still true and still tested: reasoning.effort stays unset). Replaced with openrouter_summary_budgets_reasoning_separately_and_carries_no_provider.

Verification

• cargo test -p buzz-agent: 422 unit + 110 integration tests pass at bb2fedd
• cargo fmt / cargo clippy -p buzz-agent --all-targets: clean
• Not yet validated against a live OpenRouter reasoning endpoint — the failing scenario needs a long-context session to trigger organically. Evidence for the mechanism is from run artifacts (13/13 empty-summary length-stops on deepseek-v4-flash) and OpenRouter's documented reasoning.max_tokens/reasoning.exclude semantics.

[atishpatel]

Requesting one fix before merge.

Blocking — reserve the doubled OpenRouter completion cap in the handoff input budget. openrouter_summary_body now sends top-level max_tokens = 2 * max_output_tokens (16,384 for handoffs), because OpenRouter counts reasoning and visible text together there. But build_handoff_prompt still calls handoff_prompt_budget_bytes(..., HANDOFF_MAX_OUTPUT_TOKENS, ...), so it reserves only 8,192 tokens for output. At the maximum constructed prompt, the request can therefore be context_window - 8,192 input plus 16,384 output: 8,192 over the configured window. This invalidates handoff_prompt_budget_bytes's guarantee that it “should not build a prompt that exceeds the configured context window” and can make the summarizer itself context-reject precisely when handoff is needed. Please make the reservation reflect the provider's actual top-level completion cap (2x for OpenRouter, unchanged for other providers) and pin that join in a test.

On the prompt question: HANDOFF_SYSTEM_PROMPT does contain Stay under 8192 tokens. I do not think that recreates the original accounting bug after the wire budgets are fixed: reasoning.max_tokens = 8192 independently caps hidden reasoning, while top-level max_tokens = 16384 leaves another 8192 for visible content. The natural referent is the requested plain-text summary. Still, I suggest making it explicit — e.g. “Keep the visible plain-text summary under 8192 tokens” — and ideally deriving the number from HANDOFF_MAX_OUTPUT_TOKENS rather than maintaining a duplicated literal. That is robustness/clarity, not my blocking finding.

Evidence: reviewed and ran the focused wire-shape and prompt-budget tests at bb2feddee0a006c56e7c9d80bbf6d10ab805f0a4 with a clean worktree; both pass, which also shows the existing prompt-budget test does not cover the new 2x join.

[tlongwell-block]

@atishpatel Good catch — the blocking finding was real. The wire cap and the input reservation were computed in two different places and the first commit only moved one of them. Fixed in 5f53236:

Blocking issue — provider-aware output reservation. New summary_completion_cap(provider, budget) in llm.rs is now the single source of truth for what summarize() actually requests: 2× the text budget for OpenRouter (text + equal reasoning budget), unchanged for Anthropic/OpenAI/Databricks/DatabricksV2 (their summary bodies request the caller's budget as-is). Both openrouter_summary_body (wire cap) and build_handoff_prompt (input reservation) derive from it, so the two can't drift apart again.

Test pinning the join. openrouter_prompt_budget_reserves_doubled_completion_cap asserts estimate_tokens(budget + fixed) + actual_completion_cap <= window at the 1-byte/token upper bound — and additionally asserts the old single reservation observably violates that same join (so the test fails if anyone reverts to reserving only HANDOFF_MAX_OUTPUT_TOKENS). non_openrouter_completion_cap_is_the_callers_budget pins the other providers unchanged.

Prompt suggestion — taken. HANDOFF_SYSTEM_PROMPT is now a LazyLock<String> built with format!, reading "Keep the visible plain-text summary under {HANDOFF_MAX_OUTPUT_TOKENS} tokens." — no duplicated literal, explicit visible-text referent. Pinned by handoff_system_prompt_derives_limit_and_targets_visible_text.

One deliberate non-change: token_threshold (the handoff gate) still reserves cfg.max_output_tokens — that reservation is for the agent's own next completion, not the summarizer call, so the doubled cap doesn't apply there. The summarizer's window safety is what handoff_prompt_budget_bytes guards, which is now provider-aware.

Verified at 5f53236: full cargo test -p buzz-agent (425 unit + 110 integration) green, fmt/clippy clean.

[tlongwell-block]

Independently reviewed and live-tested at exact PR head 5f53236161a9b411a1ae1a7a9e4635e910b3ac12.

The revised design resolves the earlier blocker:

• OpenRouter summary requests set reasoning: { max_tokens: 8192, exclude: true } and a top-level completion cap of 16,384, leaving distinct budgets for hidden reasoning and visible summary text.
• summary_completion_cap() is shared by request construction and handoff-input budgeting, so the prompt cannot reserve only the visible-text half and drift from the wire allowance again.
• Other providers retain the original completion cap.
• The prompt now unambiguously constrains the visible plain-text summary to the derived 8,192-token limit.
• The normal handoff gate correctly continues reserving the agent response budget; the doubled allowance applies to the separate summarizer request.

Verification at that exact head:

• Built the release buzz-agent.
• Ran the full cargo test -p buzz-agent: 425 unit tests passed, plus all integration/doc suites (including 48 regression tests).
• Ran two real ACP sessions through OpenRouter with deepseek/deepseek-v4-flash-0731; forced proactive handoff produced non-empty summaries and both sessions continued into the next prompt, with no empty-summary fallback or logged errors.
• Sent a direct OpenRouter request using the PR's exact reasoning shape; the response contained visible content, omitted reasoning text, and reported 347 hidden reasoning tokens separately, confirming that the provider honors exclude: true in this configuration.

I found no remaining blocker.

GitHub will not let this authenticated account formally approve because it is also the PR author, so recording my independent approval verdict as a comment.