Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
docs(catalog): document the wire reader, model-spec markers and custom wire
Jack Rudenko9bde383b1e92
diff --git a/CLAUDE.md b/CLAUDE.mdindex e9b88623..63560378 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -10,6 +10,7 @@ lives in `ROADMAP.md`.## Where the rationale lives — all files below are in `ai-docs/architecture/`- `routing.md` — `provider@model` syntax, every provider prefix, catalog-gathered route candidates and their tier order, `defaultProvider` as the fallback position, the derived picker provider list, `SUBSCRIPTION_PROVIDERS`, local models+- `wire.md` — every request built from the connection's catalog `wire` + route registry (no model-name rules anywhere); clamp / borrow-and-drop / try-in-turn; the first-run refusal trap; `+pro` vs the `+` chain separator; custom endpoints' declared wire; read before touching `connection-*.ts`, `wire-*.ts`, step 5w, or any limit/reasoning field- `adapters.md` — Layers 1–3, stream parsers, error classification and retry, the 400 remap, why Gemini tool schemas need `items` on every array- `network-recovery.md` — the two-tier connection hold: the DERIVED deadline (`API_TIMEOUT_MS`, not awatchdog), why tier 2 answers 503 and never 429, why the banner is magmux's `overlay` and never adiff --git a/ai-docs/architecture/README.md b/ai-docs/architecture/README.mdindex 85e1ba1e..0da7a4d2 100644--- a/ai-docs/architecture/README.md+++ b/ai-docs/architecture/README.md@@ -26,6 +26,7 @@ three earlier write-ups this material cites were lost.| [`predefined-endpoints.md`](predefined-endpoints.md) | The 25-vendor bundled catalog: credential-gated activation, the single registration seam, evidence tiers (all `probe`, none `live`), and the no-model-data rule | add a vendor to `providers/predefined-catalog.ts`, or change endpoint registration || [`onepassword.md`](onepassword.md) | SDK-only secret resolution, the FOUR causes of an identical denial error, the cross-process handshake lock, parent-side route pinning, and the config TUI tab | touch `providers/onepassword*.ts`, credential pre-hydration, or the 1Password TUI tab || [`keychain.md`](keychain.md) | The macOS Keychain backend: the 17ms-vs-28ms measurement that split presence from values, the two `security` behaviours that are traps (hex reads, a "secure" write that stores nothing and exits 0), and why no new `CredentialSource` member | touch `providers/keychain.ts`, `keychain-source.ts`, or the Providers tab's key write/delete |+| [`wire.md`](wire.md) | Every request from the connection's catalog `wire` and the route registry: the four-step pipeline, Jack's decisions where they diverge from the backend spec (clamp, borrow-and-drop, try in turn), the first-run refusal that stuck for a session, `+` doubling as the chain separator, name gates one layer down, custom endpoints' declared wire, the advisor and discovery on registry hosts | touch `connection-*.ts`, `wire-*.ts`, `declared-wire.ts`, `ComposedHandler` step 5w, an adapter's limit or reasoning fields, the advisor's request, or `+`/`#` model-spec markers || [`adapters.md`](adapters.md) | Layers 1–3 (FormatConverter / ModelTranslator / ProviderTransport), stream-parser selection, errors that ride an HTTP 200, and the `upstream_status` remap with its downstream readers | add a provider, model translator, or stream parser; or change error classification and retry || [`network-recovery.md`](network-recovery.md) | The two-tier connection hold: why the deadline is DERIVED from `API_TIMEOUT_MS` (measured 359.607 s, a default and not a watchdog), why the tier-2 status is 503 and never 429, why the banner is magmux's `overlay` and never a pane of ours (closing a pane wedged Claude Code), why its lease is renewed on its own tick and not by ladder events, the five sites where a network failure wore an auth status code, and why a pane child gets no watchdog | touch the retry ladder, `recovery/`, the tier-2 status, the recovery banner, or any `x-claudish-recovery` reader || [`behavior-layer.md`](behavior-layer.md) | Layer 4, the harness-convention SUPERVISOR: the rule engine, the four hooks, the 115-call plan-mode measurement it was built on, and opt-in telemetry | write a `behavior/` rule, or change harness-conformance handling |diff --git a/ai-docs/architecture/adapters.md b/ai-docs/architecture/adapters.mdindex b25249f9..eeedecba 100644--- a/ai-docs/architecture/adapters.md+++ b/ai-docs/architecture/adapters.md@@ -438,6 +438,11 @@ The exclusion rested on "a 503 cannot silently switch the user off a pinned mode## The catalog's endpoint contract has two halves (v9.0.7)+> **Superseded (10.5.0).** The gate, the name rule and the model-level `tokenParam` read+> described here are deleted. Every request is now built from its connection's `wire`+> ([`wire.md`](wire.md)). Kept for the history of why reading half a contract is worse+> than reading none.+`gpt-6-astra` was in the catalog and could not run. The child exited 1 on```diff --git a/ai-docs/architecture/custom-endpoints.md b/ai-docs/architecture/custom-endpoints.mdindex acbd978a..3797241a 100644--- a/ai-docs/architecture/custom-endpoints.md+++ b/ai-docs/architecture/custom-endpoints.md@@ -110,3 +110,19 @@ edit rather than a hunt for ternaries.Verified live against a header-inspecting mock — `authorization: null`, `x-api-key` **absentfrom the request entirely** (not empty), and a declared `headers: {"X-Team":"platform"}` stilldelivered, since for some gateways a custom header IS the credential.++## The declared wire (v10.5.0)++A custom endpoint has no catalog connection, so until v10.5.0 its request shape came from the+model NAME: a name-picked dialect (`enable_thinking` for anything matching `qwen`, a `thinking`+toggle for `glm-N.M ≥ 4.5`) and `OpenAIAPIFormat`'s `gpt-5`/`o1`/`o3`/`o4` token-field rule. That+is the guessing the catalog wire reader removed everywhere else ([`wire.md`](wire.md)).++An endpoint now declares a `wire` block (`CustomEndpointWireSchema`) in the catalog's own+vocabulary, and `declared-wire.ts` turns it into a connection that goes through the same step 5w+as a catalog connection. With no block the documented defaults apply: the transport's API,+`max_tokens` (`max_output_tokens` on Responses), and no reasoning field. The schema refuses a+`wire.api` the transport cannot speak (Messages on `openai`, Chat on `anthropic`).++Bundled vendors with a catalog route (`together`, `fireworks`) are built from the catalog wire+first; the other bundled rows take the declared defaults.diff --git a/ai-docs/architecture/wire.md b/ai-docs/architecture/wire.mdnew file mode 100644index 00000000..17c52c69--- /dev/null+++ b/ai-docs/architecture/wire.md@@ -0,0 +1,119 @@+# The wire reader: every request from the connection's `wire`++> How claudish decides the API, URL, output-limit field, reasoning encoding, mode and speed of+> a request: from the catalog's per-connection `wire` and the route registry, never from a+> model name. Read before touching `providers/connection-*.ts`, `providers/wire-*.ts`,+> `providers/declared-wire.ts`, `ComposedHandler` step 5w, an adapter's token or reasoning+> fields, or the advisor's request building.++Spec: Models Index `ai-docs/claudish-wire-requirements.md` (R1–R13) and+`ai-docs/claudish-catalog-3.7.0.md`. Plan and gap counts: `ai-docs/reports/wire-reader-plan-20261012.md`.++## Why it exists++Catalog 3.7.0 (live 2026-10-08) changed what the model-level `tokenParam` and `endpoints` mean:+they now describe the model OWNER's direct connection only. claudish 10.4.1 applied the+model-level field to every chat body on every host, so GPT and Grok chat requests to gateways+carried `max_output_tokens` (a Responses-only field): about 150 chat connections on generation+`g-20261012101007285-7770c36e`; `[email protected]` answered 400. Before that, months of+regressions came from name rules (`requiresResponsesApi`, `includes("codex")`, OpenCode family+lists, effort ladders by `gpt-5.x`) being falsified by each new model release.++## The pipeline++1. **Data** (`all-models-cache.ts`, `catalog-client.ts`). The refresh reads the slim model pages,+ the plans, and `queryModels?catalog=routes&generationId=<same>`; a different generationId+ restarts the whole refresh once. A 3.7.0 cache is rejected whole if any mapped connection lacks+ a wire, names a missing route profile, or has a known API without a base URL — a partial wire+ table would send some requests from data and the rest from nothing. Reads are memoized by mtime+ and size: the request path reads the 2.7 MB file per request.+2. **Connection** (`connection-resolver.ts`). The provider's exact route binding plus the exact+ wire id; never a family or sibling. It carries the wire, the registry profile, the model's+ VENDOR (catalog `provider`) and the owner's direct-connection wire.+3. **Handler** (`wire-handler.ts`, from `createHandlerForProvider` before any profile). Adapter by+ `wire.api`, URL from the registry (a user base-URL override is kept and logged), the provider's+ own transport only for auth and identity headers (Codex keeps its credential-decided host:+ OAuth → chatgpt.com, API key → api.openai.com).+4. **Request** (`ComposedHandler` step 5w → `wire-request.ts`). After every adapter has run, every+ field any of them may have emitted for the limit, reasoning, mode or speed is removed, then the+ wire's values are written at their RFC 6901 pointers.++## Decisions (Jack, 2026-10-12) and where they diverge from the backend spec++| Topic | Backend spec | claudish |+|---|---|---|+| Effort not in `effort.values` | refuse | clamp to the nearest published value, ties up |+| `tokenParam` / `reasoning` `unknown` | send nothing | try the owner's direct-connection value when it is on the SAME API; drop exactly those borrowed fields on the 400 that names them (`recoverBorrowedWireFields`) |+| `wire.status: unknown`, or model not published for the provider | APIs in fixed order | same (`TryInTurnHandler`): advance only on 404/405/protocol-400, remember the winner per generation |+| No catalog | wait or fail | local providers only; catalog providers wait, then refuse per request (below) |+| Pro / speed | `--mode`, `--speed` suggested | `model+pro`, `model#fast` |++`not_applicable` is an ANSWER, never borrowed over (Codex found the shaper treating it like+`unknown`). Mode and speed are never borrowed: they carry entitlement and price.++## Traps++- **Older claudish erases the registry.** Releases before 10.5.0 rewrite+ `cloud-models-catalog-v3.json` on every refresh without `routeRegistry` (measured 2026-10-14:+ an installed 10.4.1 in another session replaced the cache with a newer generation). The+ registry therefore also lives in a sidecar, `cloud-models-catalog-v3.routes.json`, attached on+ read when its generation matches; when it does not, `ensureRouteRegistryReady` fetches only+ `catalog=routes` for the cache's generation (1.4 s live, against 9.3 s for a full refresh).+- **The first run after an upgrade.** The old cache has no registry; the refresh that writes it+ measured 9.3 s, and the request path first waited 5 s and refused. The proxy caches handlers+ per model, so the refusal stuck for the whole session (`--probe gpt-6-sol` refused cx@, oai@ and+ zen@ while grok-4.7, built after the refresh, answered). Now: 30 s wait, then+ `CatalogPendingHandler`, which rebuilds per request and refuses only while the catalog is still+ missing. Never return a cached refusal for a transient state.+- **`+` is ALSO the route-chain separator** (`team` spawns `zgo@x+mm@y+or@z`). `parseModelChain`+ attaches a segment that is only a mode word to the spec before it; real chain elements always+ contain `@`. `-pro` (102 ids) and `-fast` (22) are real model ids; `>>` and `|` are shell+ operators (an unquoted `>>fast` silently redirects to a file). `#` is literal mid-word in bash+ and default zsh; with zsh `extendedglob` it fails loudly ("no matches found").+- **Markers travel per request** (`wireMarkerContext`, AsyncLocalStorage), never in a cached+ handler or a body: the native passthrough forwards the body verbatim.+- **A name gate one layer down.** Removing the dialect choice left two: the shared message+ converter added the Grok tool prompt for any id containing "grok", and the Gemini+ thought-signature middleware re-filtered itself by name after being selected from data. Both+ now read the connection's vendor (`setUpstreamVendor`, `alwaysHandle`). Search for the NAME+ check at every layer, not just the selector.+- **Codex's reasoning summary.** The wire does not publish `reasoning.summary`; the shaper drops+ the whole `reasoning` object. Claude Code's visible thinking needs it, so the Codex transport+ restores `summary: "auto"` where reasoning was sent.+- **Kimi Code `k3`.** Its `disable` is served by K2.8 Preview (`served_model_changes`). Reasoning+ stays on and the log says why, unless `--accept-served-model` (env+ `CLAUDISH_ACCEPT_SERVED_MODEL=1`) names the swap.++## Off-catalog requests++- **Custom endpoints** declare their wire (`config-schema.ts` `CustomEndpointWireSchema`); the+ documented default is the transport's API, `max_tokens` (`max_output_tokens` on Responses), no+ reasoning. They go through step 5w like a catalog connection (`declared-wire.ts`). LiteLLM and+ OpenRouter/Poe models the catalog does not publish get the same default.+- **Dynamic subscriptions** (`gk@`, `ag@`, `dv@`) publish no wire; the account decides what they+ serve. Only `gk@` names a dialect, explicitly in its profile (Grok effort with learn-on-400).+ Nothing picks a dialect by model name any more; `dialect-manager.ts` serves local models only.+ One model quirk no wire field describes stays, keyed on the catalog VENDOR: a `minimax` model+ on any connection gets the MiniMax dialect for its temperature clamp (its reasoning fields are+ overwritten by step 5w). Dropping it with the name dialects was caught in test review.+- **The advisor** resolves the same connection, follows `wire.api` (Chat, Responses, Messages or+ Gemini, non-streamed), takes its URL from the registry and shapes the body with the same step.+ The provider docs' endpoints remain only as the cold-catalog fallback, logged when used.+- **Discovery** (`model-discovery.ts`) lists models from the registry base + `/models` for a+ catalog-routed provider (OpenCode moved Zen to `opencode.ai/inference/v1` on 2026-10-12);+ a user base-URL override keeps the definition's path.+- **Vision** with a connection reads the catalog's `inputModalities` / `supportsVision`; unknown+ sends the image the user attached.++## Verification on record++- 1770 mapped connections on generation `g-20261012101007285-7770c36e`: every one carries a wire,+ every known API has a base URL, the registry covers every claudish route binding.+- Intercepted end-to-end capture of 19 connections, each body exactly the wire's+ (`ai-docs/sessions/…/p3-capture.ts`, gitignored).+- Live `--probe` (2026-10-12): every funded hop answered — `oai@gpt-6-sol` on `/v1/responses`,+ `[email protected]` on Responses, `kc@` on `api.kimi.ai`, `oc@` on `ollama.com/v1` with plain ids,+ `qtoken@` on the qwencloud host, `[email protected]` with `max_tokens`. Zen and Together+ answered 402 (account funds).+- `providers/no-name-rules.test.ts` scans every non-test source file (NUL-safe: `devin.ts` and+ `grok-effort-support.ts` contain NUL bytes) for the removed identifiers.diff --git a/docs/settings-reference.md b/docs/settings-reference.mdindex bedc7aa1..f6f54338 100644--- a/docs/settings-reference.md+++ b/docs/settings-reference.md@@ -22,6 +22,7 @@ All flags recognized by `parseArgs()` in `packages/cli/src/cli.ts`.| `--model` | `-m` | string | none (prompts interactively) | Model to use. Accepts `provider@model` syntax, legacy `prefix/model`, or bare model name for auto-detection || `--default-provider` | | string | none | Default provider for auto-routing (v7.0.0+). Overrides env var and config file. Valid: built-in provider names or custom endpoint names || `--config` | | path | none | Use this file as the run's ONLY config, replacing both the global and project config. Consumed before `parseArgs()` — see [Config File Override](#44-config-file-override---config) |+| `--accept-served-model` | | boolean | false | Allow a reasoning-off that the connection serves with a DIFFERENT model (catalog `served_model_changes`; e.g. Kimi Code `k3`: thinking off is served by K2.8 Preview). Without it reasoning stays on and the log says why. Env: `CLAUDISH_ACCEPT_SERVED_MODEL=1` (v10.5.0+) || `--model-opus` | | string | none | Model for Opus role (planning, complex tasks) || `--model-sonnet` | | string | none | Model for Sonnet role (default coding) || `--model-haiku` | | string | none | Model for Haiku role (fast tasks, background) |@@ -425,6 +426,21 @@ ll@my-model # LiteLLM proxy with auto catalog resolutionProvider part is **case-insensitive**. Shortcuts are resolved to canonical provider names.+**Request mode and speed markers (v10.5.0+).** A model spec may end in `+pro` and/or+`#<speed>` (`fast`, `priority`, `flex`, `ultrafast`, `standard`):++```+cx@gpt-6-sol+pro # reasoning mode pro+oai@gpt-6-sol#fast # fast speed tier (sent as the connection's native value, e.g. service_tier=priority)+oai@gpt-6-sol+pro#flex # both, in either order+```++A marker is only a REQUEST. Each catalog connection publishes which modes and speeds it offers+(`claudish --probe <model>` prints them); a value the connection does not offer is refused with+the list it does offer, never silently dropped or guessed. A faster tier can bill at a higher+rate. The markers need a catalog connection (or a custom endpoint); they are refused elsewhere.+`-pro`/`-fast` are NOT markers: `gpt-6-sol-pro` and `kimi-k3-fast` are separate models.+### 5.2 Provider Shortcuts#### Remote Providers@@ -669,6 +685,7 @@ For OpenAI- or Anthropic-compatible servers:| `authScheme` | `"bearer"`, `"x-api-key"` or `"none"` | no | Auth header scheme (default: `bearer`) || `modelPrefix` | string | no | Prepended to model name before sending to API || `models` | string[] | no | Restrict to listed models; omit to allow any |+| `wire` | object | no | How requests are built — see **Declaring the wire** below |Usage: `claudish --model [email protected] "task"`@@ -729,6 +746,38 @@ Full control over transport, auth, headers, and stream format:| `streamFormat` | string | no | Stream parser override (e.g., `"openai-sse"`, `"anthropic-sse"`) || `modelPrefix` | string | no | Prepended to model name || `models` | string[] | no | Restrict to listed models |+| `wire` | object | no | How requests are built — see **Declaring the wire** below |++### Declaring the wire (v10.5.0+)++claudish never chooses a request's output-limit field or reasoning parameters from the model+name. A catalog provider gets them from the cloud models catalog; a custom endpoint gets them+from its `wire` block, or from these documented defaults:++| Field | Default | Meaning |+|-------|---------|---------|+| `api` | the transport's API | `"chat-completions"`, `"responses"` (openai transport only) or `"anthropic-messages"` |+| `tokenParam` | `max_tokens` (`max_output_tokens` on Responses) | The output-limit field; `"none"` sends no limit |+| `reasoning` | nothing sent | `effort: { path, values?, default? }`, `enable: [{path, value}]`, `disable: [{path, value}]` |++Paths are RFC 6901 pointers into the request body. `effort.values` maps claudish's effort+names (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`) to the endpoint's own values;+when omitted, the names are sent as they are. A requested effort the endpoint does not list is+clamped to the nearest one it does. Example for a vLLM server running a Qwen thinking model:++```json+"wire": {+ "tokenParam": "max_tokens",+ "reasoning": {+ "enable": [{ "path": "/chat_template_kwargs/enable_thinking", "value": true }],+ "disable": [{ "path": "/chat_template_kwargs/enable_thinking", "value": false }]+ }+}+```++Before v10.5.0 claudish picked these from the model name (a Qwen name got `enable_thinking`,+a `gpt-5` name got `max_completion_tokens`); such an endpoint now needs the block above, or+`--model-params`, to keep that behaviour.### Environment variable expansion