[Bug] Catalog-backed pi-ai routes report no output reserve — compaction threshold lands 135k above the provider's admission limit

[Alnita-M]

Summary

On 0.1.7-rc.1, a session on a catalog-backed pi-ai provider (opencode-go) dies permanently at ~664k tokens, with no compaction and no warning.

compaction-basic already contains the 555b664b08 threshold fix:

floor(min(contextWindow × thresholdRatio, contextWindow − reservedCompletionTokens − headroomTokens))

But reservedCompletionTokens is 0 for this route, because the adapter never reports the value it actually sends. The threshold therefore lands at 800,000 while the provider's real input ceiling is 664,576 — a 135,424-token blind zone that the session must cross before compaction would ever fire. It cannot: crossing it is what kills the session.

Environment

item	value
DSH	desktop app (web GUI), profile packages 0.1.7-rc.1
route	opencode-go / deepseek-v4.1-flash, api: openai-completions, baseURL https://opencode.ai/zen/go/v1
provider config	apiKeyEnv: OPENCODE_GO_API_KEY only — no models[].maxTokens, no modelOverrides (the ordinary catalog case)
relevant packages	dsh-compaction-basic@0.1.7-rc.1, dsh-llm-pi-ai@0.1.7-rc.1, dsh-token-meter@0.1.7-rc.1
headroomTokens present?	yes (lib/index.js:21,63-64) → the fixed formula is in this build

Actual vs expected

Upstream's own message (captured from a different session on the same route):

This model's maximum context length is 1048576 tokens. However, you requested 1049068 tokens
(665068 in the messages, 384000 in the completion). Please reduce the length of the messages or completion.

real input ceiling = 1,048,576 − 384,000 = 664,576

A concrete crash, reconstructed from the session journal (session.v4.jsonl.zstd):

step	input tokens	result
last success	inputTokens 456 + cacheReadTokens 663,680 = 664,136	ok (440 below the ceiling)
next request	≈ 665,256 (previous completion 844 folded back + 246 tokens of tool output + envelope)	HTTP 400
every turn after	same oversized history, re-sent	400 within ~7 s, 7 consecutive failed turns

Root cause

dsh-compaction-basic resolves the reservation as:

reservedCompletionTokens = header.config.maxTokens ?? info.defaultMaxTokens ?? 0

dsh-llm-pi-ai only populates defaultMaxTokens when the provider profile explicitly declares models[].maxTokens (dsh-llm-pi-ai, model-info path). In the ordinary catalog case it reports nothing.

Meanwhile the sender side does use the catalog value: pi-ai sends max_tokens = options?.maxTokens ?? model.maxTokens, i.e. 384,000 for this model.

So the two halves disagree: the request reserves 384,000 tokens of the window, the budgeter assumes 0.

threshold = floor(min(1,000,000 × 0.8, 1,000,000 − 0 − 65,536)) = 800,000
real ceiling                                                  = 664,576
missing                                                       = 135,424

With O = 384,000 reported, the threshold would be min(800,000, 550,464) = 550,464 — which would work.

Journal confirms the consequence: zero compaction/* events in a 1,617-event session, and no contextPressure alert before the crash.

Secondary defect (why the safety net also misses)

The provider returned an opaque 400 body, {"error": {"model": "deepseek-v4.1-flash"}}. The openai SDK renders it as 400 {"model":"deepseek-v4.1-flash"}. That string matches none of the context-overflow patterns, so the failure is classified INVALID_REQUEST rather than CONTEXT_WINDOW_EXCEEDED — and compaction-basic's overflow-recovery listener never runs.

Even when the same provider does return recognisable wording (another session got the full message above and was correctly classified CONTEXT_WINDOW_EXCEEDED), the turn still ended in error, so recovery is not a reliable fallback here either (see also #23 — retainTokens = 0 in the overflow branch).

Workaround that works

Give the route an explicit maxTokens so the request envelope carries it:

# profiles/<name>/cordis.patch.yml, inside the existing `- id: llm-pi-ai` entry
      opencode-go:
        apiKeyEnv: OPENCODE_GO_API_KEY
        modelOverrides:
          deepseek-v4.1-flash:
            maxTokens: 65536

Effect:

	before	after
max_tokens sent	384,000	65,536
real ceiling	664,576	983,040
reservation O	0	65,536
threshold	800,000 (unreachable)	800,000 (fires 183k before the wall)

This matches the design note's wording — "O is taken from the effective envelope's maxTokens" — so the envelope is the intended knob.

Suggested fixes

1. dsh-llm-pi-ai: report the catalog maxTokens as defaultMaxTokens even when the profile does not declare it. The adapter already sends that value, so it owns it.
2. dsh-compaction-basic: clamp O to what the adapter actually sends for the route, instead of treating "unknown" as 0.
3. Load-time guard: compare contextWindow − O − headroomTokens against the adapter's real per-request max_tokens; fail loudly when the threshold would sit above the provider's admission limit.

References

• compaction-basic: default thresholdRatio 0.8 can never trigger when the per-request output reserve is large (sessions die before first compaction) #6671 — same failure family (default ratio cannot trigger when the output reserve is large)
• Compaction threshold is scaled against the full context window, so it can sit above what the provider admits #5123 — threshold scaled against the full window
• official design note: .agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.zh.md (states O semantics)
• dsh yyds :) #22 in the community-maintained unfixed-issues list (marked fixed by 555b664b08; this report is the residual)

(Posting here because the repository has no issue tracker.)

[argszero]

The arithmetic here checks out, and one measured detail decides which of the levers can work — worth stating before the adapter is patched.

The reserve only moves the threshold above a threshold of its own. compaction-basic computes

threshold = floor(min(W x ratio, W - O - H))

with ratio = 0.8 and H = 65536 (dsh-compaction-basic@0.2.1-rc.3, lib/types/types.d.ts:9,11). The second term can only win once O > W x (1 - ratio) - H, i.e. O > 0.2W - 65536. At W = 1,000,000 that is 134,464 tokens: a reserve of 4k, 16k, 32k or 100k changes the threshold by exactly zero, because the ratio term keeps it at 800,000.

Measured on the shipped rc.3 (lib/index.js:124-134, transcribed — the package exports only BasicCompactionEngine and does not ship src/), cross-checked by hand:

reserve O	threshold (W = 1,000,000)
0 … 134,464	800,000
150,000	784,464
200,000	734,464
270,464	664,000

Two consequences.

1. Suggested fix 1 does work, and its size is why. Reporting the catalog 384,000 as defaultMaxTokens gives min(800,000, 1,000,000 - 384,000 - 65,536) = 550,464, safely below 664,576. But the small override in the workaround does not move the threshold at all — maxTokens: 65536 leaves it at 800,000. That workaround is effective for a different reason than it appears: lowering max_tokens from 384,000 to 65,536 raises the provider's real input ceiling to 983,040, so the existing 800,000 threshold now fires 183k early. Both rows of the before/after table are right; only the mechanism differs, and it matters for anyone generalising the override to a route with a smaller window.

2. There is a second lever the report does not name. contextWindow is a per-model field on the same override entry (packages/llm/llm-pi-ai/src/config.ts:303-306, shared by models and modelOverrides at 22ddee3). Declaring contextWindow: 830000 on this route lands the threshold below the ceiling with the sent envelope untouched:

min(830,000 x 0.8, 830,000 - 0 - 65,536) = min(664,000, 765,184) = 664,000

On fix 1, a semantic note. dsh-llm/src/types.ts:431 defines defaultMaxTokens as "the adapter-configured per-request output cap materialized when callers omit one", and pi-ai does materialize the catalog value (options?.maxTokens ?? model.maxTokens), so reporting it is consistent with that wording. catalog.ts:841's distinction ("a cap the deployment chose" vs a generation cap) asks a different question — deployment intent vs catalog capability — which is why this reads as a deliberate gap rather than an oversight. Fixes 2 and 3 both need that question answered explicitly, so it may be worth settling it first.

On fix 3 as a third-party plugin. I began building one and stopped, on two findings. The reserve is already a per-model operator knob — modelOverrides.<id>.maxTokens, alongside contextWindow — so a plugin publishing the same number would duplicate a supported setting instead of closing a gap. And the check fix 3 describes needs the value the adapter actually sends, which LlmResolvedModelInfo does not carry: resolveModelInfo reports context and defaultMaxTokens only. A guard built on it could compare the threshold against the declared window, never against the route's real admission limit — precisely the comparison that would have caught this. So fix 3 belongs where the envelope is built, next to adapter.ts:331-338.