Headless: max_tokens never sent on the wire; length-truncated tool calls are silently discarded (empty output, no error)

[DarkFlowSignals]

Version: 0.1.0-rc.7 (npm), headless profile, custom openai-completions provider (local mlx_vlm server).

Setup: Provider/model config sets maxTokens: 32768 and contextWindow: 262144, and the session's request/header event shows those values. However, the actual HTTP request contains no max_tokens field, so the server applies its own default completion cap (mlx_vlm: 2048 tokens).

What happens: Any assistant response longer than the server default - e.g. a write tool call for a 300+ line file - is truncated by the server with finish_reason: length. dsh records stopReason: length, drops the incomplete tool call, and ends the turn: the final assistant/message has empty content, stdout is empty, exit code 0. Nothing is written to disk and no error is surfaced. In agentic use this presents as "claimed done / silent no-op" on large file writes.

Repro: Point a headless profile at any OpenAI-compatible server with a default completion cap, then ask dsh to write a single file of 300+ unique lines supplied in the prompt. Observe empty output and no file. Raising the cap server-side (e.g. MLX_VLM_MAX_TOKENS=32768 for mlx_vlm) fully resolves it, confirming the cause.

Expected: (1) send the configured maxTokens as max_tokens in the request; (2) when a response ends with stopReason: length mid-tool-call, surface an error (or retry/continue) instead of silently discarding the turn.

The max_tokens fix was deliberately NOT in dsh at all: since dsh omits max_tokens from its API requests (its own config is client-side only), we raised the server's default cap instead - MLX_VLM_MAX_TOKENS=32768 as an env var in start-brain.sh - so any client that omits the field now gets a 32K ceiling instead of mlx_vlm's hidden 2048, which is what had been decapitating large tool calls.

Happy to provide the session .jsonl.zstd event trace.

[argszero]

Verified the chain in rc.8 (141eb6fef8) — one correction to the framing, then a precise gap localization and a zero-code test.

The harness side does forward the value (when configured per-model)

• catalog.ts:875-897 — a per-model maxTokens in the provider profile lands in both the pi-ai model capability and configuredMaxTokens (explicit-config-only map).
• adapter.ts:268-275 — resolveModel() exposes that explicit cap as defaultMaxTokens ("Only a cap the deployment configured is a request default; the catalog's maxTokens sizes the model and stops there").
• llm/src/index.ts:740-741 — resolveCallFor() defaults config.maxTokens from the adapter's defaultMaxTokens when the request names none, and :790-791 marks it adapterDefaults.maxTokens = true.
• agent.ts:446/454/484-497 — the seed config carries the agent-level maxTokens; the header event logs the resolved config, which is why you see maxTokens: 32768 in the request/header event; agent.ts:346 then passes that config through as the stream GenerateOptions.
• llm-pi-ai/src/adapter.ts:324 — ...options.maxTokens === undefined ? {} : { maxTokens: options.maxTokens } — the adapter hands the value to pi-ai's streamSimple.

So for a properly configured per-model maxTokens, the value does reach pi-ai. (The "strip" at agent.ts:56-60 only removes adapter-derived defaults from the next step's proposal — that's the "adapter will re-supply it" trust, not a drop on the current request.)

The omission is inside pi-ai's openai-completions wire layer

The wire field spelling is governed by pi-ai's OpenAICompletionsCompat.maxTokensField — the harness mirrors it as compat.maxTokensField with exactly two spellings (catalog.ts:118-121: max_tokens | max_completion_tokens, config.ts:238). Two candidate mechanisms (both pi-ai-side; pi-ai isn't vendored in this checkout, so I can't read the serialization itself):

1. Capability gating — mlx_vlm's /models almost certainly has no max_output_tokens, so discovery (discovery.ts:153) leaves the pi-ai model entry's own maxTokens capability undefined; if pi-ai gates the output-cap field on the capability (per the catalog.ts:784-786 comment, capability vs request-default are deliberately separate concepts), the value never reaches the wire even though the harness forwarded it.
2. Spelling/disposition — the endpoint's compat resolution may withhold or pick a spelling the server doesn't read.

Zero-code disambiguation

Set compat.maxTokensField: 'max_tokens' explicitly on the provider profile (config.ts:238). If the field then appears in the request, it was mechanism 2 (spelling/disposition); if it still doesn't, it's mechanism 1 (capability gate) and the fix belongs in pi-ai's compat defaults for custom openai-completions endpoints, not in the harness request path.

The silent no-op is by-design turn-end, but invisible

stopReason: length is a designed, sticky turn-end (agent.ts:285-290, :410 — once any step hits the ceiling, the turn ends and later steps keep max-tokens). Dropping the incomplete tool call is the same truncation seam as the wire family (#1519/#2169 truncated arguments) — here benign (no poisoning), but user-invisible: empty assistant content + exit 0. Worth a distinct signal: when a step ends at the cap with an in-flight tool call, surface a notice (e.g. "turn ended at max_tokens; tool call X dropped") instead of a bare empty success — that's a small, well-scoped improvement on the agent-loop side.

Happy to provide the exact request-config trace with line numbers if useful; the event trace you offered would confirm which mechanism (1 vs 2) holds.