feat(gateway): clean DeepSeek Harness requests for non-DeepSeek upstreams

[fylorn]

Requested by F · project thread

What this changes

Before: a DeepSeek Harness (dsh) request was forwarded as-is to any upstream, carrying dsh_* fields (including the whole session log), role: system entries in messages, tool_addition/tool_removal blocks, a budget-less thinking, and x-deepseek-harness-* headers. /v1/files was forwarded to whichever upstream was picked.

After: dsh requests (recognised by User-Agent: deepseek-harness/… or any dsh_* field) go to api.deepseek.com byte for byte; to any other upstream they are cleaned first. Requests record the session log size, and /v1/files answers 404.

Cleaning rules for a non-DeepSeek upstream:

	Same-format passthrough (tw_dialect::harness::clean)	Format conversion
top-level dsh_*	removed	not carried by the IR
role: system in Anthropic messages	appended to system in order	merged into system by the decoder (already)
tool_addition / tool_removal	dropped, listed as messages.content.tool_*	dropped, now listed
defer_loading on tools	removed, listed as tools.defer_loading	now listed
thinking.type: enabled without budget (Anthropic)	adaptive for adaptive Claude models, otherwise a budget_tokens from output_config.effort	handled by the encoder; Chat decoder now reads thinking.type
x-deepseek-harness-* headers	not forwarded	not forwarded
anthropic-beta: mid-conversation-tool-changes-*	that item removed, others kept	header not forwarded (already)

Drops are reported through the existing Translated event (from = to on passthrough, as the ChatGPT passthrough already does). When the upstream is DeepSeek and a conversion is needed anyway, the dsh_* fields are copied into the converted body.

RequestStarted and HistoryRow gain session_log_bytes (size of dsh_session_log). CONTROL_API_VERSION 22 → 23, store schema 20 → 21 (rebuilt, no migration). The gateway also reports client_hint: deepseek-harness for dsh's User-Agent. New msg code gw.files.unsupported.

Why

Only DeepSeek's official endpoint understands dsh's wire extensions (see docs/deepseek-llm-api-wire-extensions.md and packages/llm/llm-deepseek/src/serialize.ts upstream). Other upstreams reject unknown fields/blocks, Anthropic rejects enabled without a budget, and the session log (whole conversation, up to 8 MiB) should not reach an upstream that never asked for it. dsh uploads images to /v1/files first and falls back to inline base64 when that fails; the 404 is what triggers the fallback.

Why /files is 404 for every client, not only dsh

The task asked for 404 on the path itself. It is safe beyond dsh because the gateway could not serve the Files API correctly for anyone before this change:

• A /files call has no model, so routing sends it to the first candidate of the client's route: whichever upstream happens to be first, not the one that will later serve the request that references the file. With more than one upstream, failover, or a rule that routes by model, the returned file_id is unknown to the upstream that receives the generation request.
• Even with a single upstream, a later format conversion (e.g. Anthropic client → OpenAI upstream) cannot carry a file_id across vendors; the decoders already drop source.type: file and file parts as unconvertible.
• Every client in scope (Claude Code, Codex, OpenCode, dsh) sends images and documents inline; dsh is the only one that tries Files first, and it falls back on any non-2xx.

A clear 404 with a [ThinkWatch] message ("the gateway does not host files; send them inline") is better than a silent upload to an arbitrary upstream. If a real need for proxying Files appears, it needs upstream pinning by file id, which is a separate feature.

How it was verified

• crates/tw-gateway/tests/harness.rs, 9 end-to-end tests: dsh 0.1.7 Anthropic request to an Anthropic relay, to an OpenAI Chat upstream, and to DeepSeek; dsh 0.1.5 Chat request to an OpenAI upstream, to an Anthropic upstream, and to DeepSeek; conversion to DeepSeek carrying dsh_*; a non-dsh request is untouched; /v1/files, /files, /v1/files/{id} give 404 and never reach an upstream. The DeepSeek cases point the provider at http://api.deepseek.com through an HTTP proxy that is the fake upstream, so the host check is exercised for real and the body is compared byte for byte.
• Unit tests in tw_dialect::harness and official::is_deepseek_host (host spoofing), plus a client-hint test.
• cargo fmt --check, cargo clippy --workspace --all-targets -D warnings (locally on 1.94 with the pre-existing nonminimal_bool hit in convert.rs:276 allowed; it isn't from this change), cargo test --workspace all green, ./scripts/smoke.sh: 60 passed, 0 failed.
• No credential handling touched; stripped headers are dsh's anonymous user/session ids only.

Notes for review

• tw-dialect changes are additive (new harness module, new official::is_deepseek_host); decoders now list tools.defer_loading for any client that sets it (e.g. Claude Code's tool search) when converting, which is accurate but new.
• Chat passthrough leaves thinking in place: GLM, Kimi and others accept it.
• feat(quota): read the GLM Coding Plan quota for Z.ai and BigModel upstreams #204 also bumps CONTROL_API_VERSION to 23; both ship in the same release, so whichever merges second keeps 23 and merges both notes.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PQef3Cg2FVuc3u8w9qa18j