OpenRouter bridge
OpenRouter bridge
The OpenRouter bridge (server/openrouter/index.js) is a zero-dependency Node MCP server
that calls any OpenAI-compatible POST {apiBase}/chat/completions endpoint.
It is advisory-only - it cannot edit files or run shell commands.
Configuration file
The bridge and the fan-out commands (/ask-all, /consensus) read
~/.config/deliberation/config.json at call time - the canonical XDG path (Windows:
%APPDATA%\deliberation\config.json). Override the path with DELIBERATION_CONFIG. The file is stat-gated: the bridge re-reads it only when
the mtime changes, so edits to models, routing, or the providers.openrouter block
take effect immediately without restarting Claude Code or re-running /setup. Toggling a
built-in provider (codex / gemini / grok) still requires /setup to re-register
or de-register the MCP server.
Built-in panel (key only)
With OPENROUTER_API_KEY set (the env var named by providers.openrouter.apiKeyEnv) and
no OpenRouter model record in models, the resolved config gets three built-in records,
one per vendor:
| Record id | Model slug | Role |
|---|---|---|
glm-5-3-flashx |
z-ai/glm-5.3-flashx |
Default for a bare ask-openrouter / openrouter-default call |
gpt-6-1-sol |
openai/gpt-6.1-sol |
Panel voice |
gemini-3-8-flash |
google/gemini-3.8-flash |
Panel voice |
All three have askAll: true and consensus: true, so they fill the default
routing.maxFanout of 3 in ask-all and all vote in consensus. This also applies when
there is no config file at all.
- Enabled. A missing
providers.openrouterblock now means "on when the key is set".providers.openrouter.enabled: falseturns OpenRouter off, built-in panel included. The starter config that/setupwrites andconfig/config.default.jsonboth setenabled: false, so a user with that file opts in by setting it totrue. - Replaced, not merged. One valid
modelsrecord withprovider: "openrouter"(or noprovider) removes all three built-in records. Records forollama/lmstudiodo not count and are listed before the built-in records, so inask-allthey takerouting.maxFanoutslots first: with the default of 3, one local record leaves room for two built-in records. Raiserouting.maxFanoutto keep all three.consensusis not capped, so all three built-in records still vote there. - Default. A configured default (
default: trueon a record, orproviders.openrouter.defaultModel) wins overglm-5-3-flashx. - Arbiter. With
consensus.arbiter: "auto"and no CLI providers, the arbiter is the first healthy OpenRouter voice (glm-5-3-flashx), and the other two vote. - Visible.
openrouter-listmarks these recordsbuiltin: true;paneland results name themopenrouter:<record id>.
Concepts
The config has four top-level sections, each with one job:
providers- transport / connection only. Per provider:enabled(default true) plus auth/endpoint keys.enabled: falseturns the provider off for every tool:ask-all,consensus,paneland the expert tools leave it out, and a tool that names it (ask-gpt/ask-gemini/ask-grok/ask-openrouter,ask-one, and the standalonegemini,grokandopenrouterbridges with their-replytools) returnserrorKind: "disabled"without a network call or CLI spawn. The flag is read on every call, so editing the config applies without a restart. Only an explicitfalsedisables; a missing block or flag means enabled (for OpenRouter, a missing block with no key is a missing credential, notdisabled).providers.openrouteralso carries the OpenRouter-specific connection keys (apiBase,allowRawModel,defaultModel, per-calldefaults).models- named model records, keyed by id. Each record names itsproviderandmodelslug and sets routing flags. This is where you declare the models the panel uses.routing- global fan-out policy (maxFanout).consensus-arbiter(who synthesizes the consensus verdict) andblindVote(optional blind arbiter pre-vote; boolean, defaultfalse).
Config file schema (strict JSON, version must be 1):
{
"$schema": "https://raw.githubusercontent.com/antonbabenko/deliberation/master/config/config.schema.json",
"version": 1,
"providers": {
"codex": { "enabled": true },
"gemini": { "enabled": true },
"grok": { "enabled": true, "apiKeyEnv": "XAI_API_KEY" },
"openrouter": {
"enabled": true,
"apiKeyEnv": "OPENROUTER_API_KEY",
"apiBase": "https://openrouter.ai/api/v1",
"allowRawModel": false,
"defaultModel": "openai/gpt-4.1-mini",
"defaults": { "reasoningEffort": "high", "temperature": 0.2, "timeout": 120000 }
}
},
"models": {
"claude-arb": {
"provider": "openrouter",
"model": "anthropic/claude-3.7-sonnet",
"askAll": true,
"consensus": true,
"experts": ["architect"],
"reasoningEffort": "high",
"temperature": 0.2,
"timeout": 60000
}
},
"routing": { "maxFanout": 3 },
"consensus": { "arbiter": { "model": "claude-arb" }, "blindVote": true }
}providers.openrouter fields (connection only; these are OpenRouter-specific and
are not globalized):
| Field | Type | Default | Notes |
|---|---|---|---|
enabled |
boolean | true |
Whether OpenRouter participates. With no providers.openrouter block, on only when the key env var is set |
apiKeyEnv |
string | OPENROUTER_API_KEY |
Env var holding the API key |
apiBase |
string | https://openrouter.ai/api/v1 |
OpenAI-compatible base URL. Read once at startup |
allowRawModel |
boolean | false |
Allow raw slugs (not just configured records) |
defaultModel |
string | absent | Slug for the bare /ask-openrouter call |
defaults |
object | {} |
Per-call defaults: reasoningEffort, consensusReasoningEffort, temperature, timeout |
providers.ollama fields (connection only; OpenAI-compatible local or remote endpoint):
| Field | Type | Default | Notes |
|---|---|---|---|
enabled |
boolean | true |
Whether Ollama participates |
apiBase |
string | http://localhost:11434/v1 |
Ollama OpenAI-compatible base URL. Read once at startup |
apiKeyEnv |
string | absent (keyless) | Env var holding the API key if required |
timeout |
number (ms) | from providers.defaults.timeout |
Per-call wall-time ceiling in ms |
providers.lmstudio fields (connection only; OpenAI-compatible local endpoint):
| Field | Type | Default | Notes |
|---|---|---|---|
enabled |
boolean | true |
Whether LM Studio participates |
apiBase |
string | http://localhost:1234/v1 |
LM Studio OpenAI-compatible base URL. Read once at startup |
apiKeyEnv |
string | absent (keyless) | Env var holding the API key if required |
timeout |
number (ms) | from providers.defaults.timeout |
Per-call wall-time ceiling in ms |
models record fields (the map key is the record id, matching ^[a-z0-9-]+$ and not
the reserved openrouter-default):
| Field | Type | Default | Notes |
|---|---|---|---|
provider |
string | required | Supported: "openrouter", "ollama", "lmstudio" |
model |
string | required | Provider model slug (e.g. openai/gpt-4.1, llama3.3:70b) |
experts |
array or absent | absent = all 8 | [] = none / explicit-only; array = subset of the 8 expert keys |
askAll |
boolean | true |
Include this record in /ask-all fan-out when eligible |
consensus |
boolean | false |
Include this record in /consensus voting |
reasoningEffort |
string | from defaults |
Per-record override for ask calls (maps to wire reasoning_effort) |
consensusReasoningEffort |
string | from defaults |
Per-record override for consensus calls |
timeout |
number (ms) | from defaults |
Per-record override |
temperature |
number | from defaults |
Per-record override |
apiBase |
string | from provider |
Standalone bridge only; ignored by unified server |
apiKeyEnv |
string | from provider |
Standalone bridge only; ignored by unified server |
Standalone bridge auth rules & migration note
The standalone OpenRouter bridge (server/openrouter/index.js) serves
provider: "openrouter" model records only (rejecting non-OpenRouter models
with model-not-allowed). The bridge evaluates auth in this order:
apiKeyEnvis set on the model record: The bridge reads the environment variable named byapiKeyEnv. If unset or empty, noAuthorizationheader is sent. It never falls through to the provider key (OPENROUTER_API_KEY).- The record has no
apiBase, or itsapiBaseequalsor.apiBase(after stripping trailing slashes): The bridge uses the provider key (process.env[or.apiKeyEnv], defaulting toOPENROUTER_API_KEY). - Otherwise (custom
apiBasewithoutapiKeyEnv): The bridge sends no key (keyless proxy endpoint).
Important
Migration note (v3.31.0+): Previously, any model record with a custom
apiBasereceivedOPENROUTER_API_KEY. Starting with v3.31.0, records with a customapiBasedefault to keyless (Rule 3). Authenticated proxies must setmodels.<id>.apiKeyEnvto the name of the environment variable containing their key. Keyless proxies leave it unset.
Reply path session isolation:
When a session starts, the standalone bridge stores the session's alias,
effective apiBase, and the NAME of the environment variable chosen by Rule 1-3
(secrets are never stored in memory). Replies (openrouter-reply) reuse the
stored endpoint and re-read the environment variable at call time, so editing
the config file mid-session does not redirect existing reply threads. A reply
that explicitly specifies a different alias (compared by alias) or a raw model
is re-resolved from the live configuration.
On temperature: most Deliberation work is analytical - code review, debugging,
security audits, architecture and plan verdicts - where you want focused, repeatable
answers. Leave temperature unset and the field is omitted, so the provider default
applies (commonly around 1.0); set a low value (roughly 0.1-0.3) when you want
that focused, repeatable behavior. Raise it (roughly 0.6-0.9) only for generative
fan-out where spread across models is the point: brainstorming, naming, "give me 20
options". Keep it low for /consensus rounds; you want the models reasoning, not
improvising.
consensus.arbiter
consensus.arbiter names who synthesizes the verdict. Two forms:
- A shorthand string:
"auto"(default - pick a healthy voice, preferring an OpenRouter one),"host"(the host arbitrates; the server runs no arbiter pass), or a built-in provider name"codex"/"gemini"/"grok". - An object
{ "model": "<id>" }referencing amodelsrecord. The record can be any entry - even one withaskAll: falseandconsensus: false- which is the dedicated-arbiter case (an out-of-panel model that adjudicates without voting). Arbiter eligibility is independent of voting-panel membership.
A cross-host recommendation: a dedicated Claude record used only as the arbiter
({ "model": "claude-arb" }) lets a non-Claude host synthesize with a model that is not
one of the voting providers. An unusable arbiter (unknown shorthand, a { model } id that
is not configured, or a disabled provider) soft-degrades to "auto" with a warning - it
never hard-fails the config.
consensus.blindVote
consensus.blindVote is an optional boolean (default false). When true, the arbiter
ALSO answers the original question cold - with no peer opinions - to produce a
blindVerdict, fired in parallel with the peer fan-out (no extra round). The blind pass
reduces the arbiter anchoring on the peers' framing.
Constraints and behavior:
- Concrete / server-arbiter mode only. It runs only when a real arbiter pass runs
(
"auto", a built-in, or a{ model }record). In"host"mode the server runs no arbiter pass, so there is no blind pass either -blindVerdictisnull. - Cost. It adds one extra arbiter call (parallel, no extra round), which is why it is
off by default. The same key gates the per-round blind pass of the multi-round loop
(
runToConvergence): the loop records the blind text on the round but never reads it for convergence or in the arbiter prompts, so withblindVoteoff the round records(blind pass disabled)and skips the call. - Failure-isolated. A thrown blind pass yields
blindVerdict: nulland never fails the run.blindVerdictis alsonullwhenblindVoteis off or no arbiter exists. - Validation. A non-boolean value soft-degrades to
falsewith a warning - it never hard-fails the config.
Behavior source of truth: consensus() in core/orchestrate.js and the blindVote
validation in server/openrouter/config.js.
consensus.maxRounds
consensus.maxRounds is an optional positive integer (default 5) that caps the
server-side convergence loop used by the consensus and consensus-step tools (a per-call maxRounds overrides it).
The loop ends unresolved once it hits the cap without converging.
- Range.
1..50. A value above50is clamped to50with a warning; a non-integer or non-positive value is dropped (the default5applies) with a warning - it never hard-fails the config. - Scope. It governs only the multi-round loop tools. The one-shot
consensustool is a single arbiter pass and is unaffected. - Validation lives in
resolveConsensus(server/openrouter/config.js); the cap is enforced incore/consensus-loop.js.
consensus.maxWallMs
consensus.maxWallMs is an optional positive integer (default 1800000, 30 min) that sets
the global wall-time budget (ms) for the server-side provider-arbiter convergence loop (the
consensus tool). When the budget is spent the loop stops BEFORE starting the next round and
returns UNRESOLVED with stopReason: "budget-exhausted"; it never aborts an in-flight
provider call. The host-driven /consensus (consensus-step) path applies the same budget:
dispatch_peers ends the loop as UNRESOLVED with the same stopReason instead of starting
another fan-out once the budget, counted from init, is spent.
- Default.
1800000(30 min). A non-integer or non-positive value is ignored (no budget is applied) without failing the config. - Scope. Provider-arbiter
consensustool only. The host-drivenconsensus-steppath has no server-side wall clock; the host controls timing there. - The budget is forwarded to
runToConvergenceasopts.maxWallMsand checked incore/consensus-loop.jsat the start of each round (now() - startedAt >= maxWallMs).
camelCase config keys, wire mapping
Config keys are camelCase: reasoningEffort, temperature, timeout. The bridge sends
reasoning_effort on the wire; the camelCase -> wire mapping happens in one place - the
resolved layer in server/openrouter/config.js, which carries reasoning_effort on each
resolved record and on defaults. temperature and timeout pass through unchanged.
Which params apply on which path: the unified /ask-all, /consensus, and the
{ model: <id> } arbiter path apply a record's per-model reasoningEffort, temperature,
and timeout (forwarded with arg-wins precedence by pinAlias in core/registry.js). A
record's per-model apiBase and the providers.openrouter.defaults block apply only on the
standalone /ask-openrouter bridge path, because the unified server's OpenRouter provider
fixes apiBase / apiKeyEnv at construction. That is a pre-existing limitation, not a goal
of the arbiter feature.
Routing
/ask-all: includes all records whereaskAll !== falseand the record is eligible for the requested expert; capped torouting.maxFanoutrecords (default 3)./consensus: includes records whereconsensus === true; NOT subject tomaxFanout. A warning is logged when more than 3 records enter a consensus round (cost).openrouter-defaultis the reserved id for the baremcp__deliberation__openroutercall and/ask-openrouterwith no record specified. It resolves todefaultModel, is the single-shot fallback only, and is never included in fan-out or consensus.- Implementation tasks always route to Gemini - GPT, Grok, and OpenRouter are advisory-only.
Editor validation (VS Code, no extension)
The config carries a $schema key pointing at config/config.schema.json (JSON Schema draft
2020-12). VS Code's built-in JSON support reads that key and gives you validation,
autocomplete, and lint with no third-party extension - and it works on the user's real
config outside this repo, because the file itself carries $schema. The in-repo .vscode/
folder additionally wires a json.schemas mapping so example configs inside the repo
validate even without the $schema line.
Config validation (partial) and the openrouter-list contract
Validation is per-entry, not all-or-nothing. A single malformed models record
(bad id characters, reserved id, a provider other than openrouter/ollama/lmstudio,
missing model, unknown
expert, or a bad per-record override) no longer rejects the whole config - the bridge keeps
every valid record and collects the bad ones into invalidModels. Only top-level/schema
problems hard-fail the whole config: malformed JSON, a non-object root, an unsupported
version, or a non-integer/< 1 routing.maxFanout.
mcp__deliberation__openrouter-list returns (each delegate keeps the alias field, equal
to the record id, so selection and the wire stay stable):
{
"delegates": [ { "alias", "model", "experts", "askAll", "consensus", "default", "builtin", "reasoning_effort" } ],
"defaultModelSet": true,
"maxFanout": 3,
"maxFanoutHigh": false,
"invalidModels": [ { "index": 2, "alias": "qwen3.7-max",
"reason": "models id \"qwen3.7-max\" must match [a-z0-9-]+ ...",
"suggestedAlias": "qwen3-7-max" } ]
}builtinistrueon the records of the built-in panel (see Built-in panel) andfalseon records fromconfig.json.delegates(andselected/omitted) list onlyprovider: "openrouter"records; the standalone bridge cannot callollama/lmstudiorecords, so they appear only in the unified server's panel.invalidModelsis reported even when a provider is disabled, so a broken record is visible before you re-enable it.- On a hard config failure the object instead carries
error: "<message>"withdelegates: [](andinvalidModelsabsent/empty)./ask-alland/consensustreat theerrorform as "OpenRouter set EMPTY". invalidModels[].suggestedAliasis present only when a safe deterministic repair exists: id-format errors are sanitized to[a-z0-9-]+(e.g.qwen3.7-max->qwen3-7-max), and collisions get a free-Nsuffix. Suggestions are collision-checked against every existing id and the reservedopenrouter-default. Entries with no safe fix (missingmodel, unknown expert, non-openrouterprovider, reserved-id clash) have nosuggestedAlias.- The bridge never edits
config.json. The/ask-alland/consensuscommands surfaceinvalidModelsand offer Fix & proceed (default - apply eachsuggestedAliastoconfig.json, drop the unrepairable, re-list), Run valid only, or Skip all OpenRouter.
Authentication (optional)
The Authorization header is sent only when the key env var resolves to a non-empty
string. Keyless local endpoints (such as vLLM) work without a dummy key.
openrouter.ai returns HTTP 401 if the key is absent; local endpoints accept no-auth
requests.
apiBase override matrix
| Endpoint | apiBase value |
|---|---|
| OpenRouter | https://openrouter.ai/api/v1 (default) |
| HuggingFace Inference | https://router.huggingface.co/v1 |
| vLLM | http://localhost:8000/v1 |
Ollama and LM Studio do not go through this override. Configure them with their own
providers.ollama and providers.lmstudio blocks and provider: "ollama" /
provider: "lmstudio" model records (see the provider field tables above).
OpenRouter Presets (Routing & Cost Optimization)
OpenRouter allows defining presets that encapsulate model selection, provider routing preferences (e.g. sorting by price, filtering providers by data collection policy, enabling fallbacks), system prompt, and sampling parameters.
Deliberation supports specifying presets by ID or slug (e.g. cheapest-first, @preset/cheapest-first):
providers.openrouter.presetorproviders.openrouter.defaults.preset: Default preset applied to OpenRouter calls.models.<id>.preset: Per-model preset. A model record can specifypresetalone (delegating model selection to the preset) or alongside an explicitmodel(applying the preset's routing and parameter configuration to that specific model).- Request parameter
preset: Overrides presets per tool call (ask-openrouter,ask-one,consensus).
On the wire, callOpenRouter transmits "preset": "<slug>" (with any leading @preset/ stripped) in the chat completion request payload.
Cost & Routing Advantages:
- Price Sorting: Directs requests to the lowest-cost host for a model while retaining high availability.
- Data Privacy: Enforces policies like
data_collection: "deny"upstream without manual client-side proxying. - Resilience: Automatically falls back to secondary provider endpoints when a primary provider is down or throttling.
File attachment (text-inline only)
OpenRouter accepts {path} and {dir} entries only. file_id and file_url
entries are rejected (-32602). The mode field is coerced to "inline" regardless
of what is set - there is no upload path. Content is embedded as text blocks in the
request body.
Per-file cap: OPENROUTER_INLINE_MAX_BYTES (default 262144 = 256 KB).
Aggregate cap: OPENROUTER_INLINE_MAX_TOTAL_BYTES (default 1048576 = 1 MB).
Exceeding either cap returns a hard error with counts.
A {path} entry with headBytes (positive integer) is read head-only and truncated
instead of skipped: content plus the [truncated: first N of M bytes] marker stays
within the per-file cap, and the aggregate cap counts the truncated size.
headBytes on a {dir} entry or with mode: "upload" is rejected; {dir} keeps
maxBytes as its walk cap. A per-file cap of 64 bytes or less is too small for the
marker, so a headBytes read is refused with a note.
Session model persistence
A model alias is bound at the start of a session via mcp__deliberation__openrouter
and is preserved for the life of that threadId. -reply calls on the same thread
always use the same model.
Consensus cost model
Each consensus round historically used approximately N models x bundle tokens x rounds tokens.
To reduce token consumption and improve convergence efficiency:
- Multi-Round Context Digests (
core/consensus-loop.js): Rather than carrying full verbatim plans across rounds, earlier round history is compressed:- Older rounds (> 2 rounds ago) are summarized on a single line (
Round N: +X lines, -Y lines). - Recent rounds (last 2 rounds) format accepted, deferred (with reasons), and dismissed (with reasons) issues alongside the plan diff summary (
summarizePlanDiff). - Only the latest plan under review is displayed in full, bounding token growth to $O(1)$ across rounds.
- Older rounds (> 2 rounds ago) are summarized on a single line (
- Canonical Prefix Ordering (
server/openrouter/index.js): Static file context blocks (inlineBlocks) precede dynamic user prompt text in user messages. Sequential turns or calls sharing file attachments hit upstream KV prompt caches (e.g. Anthropic, DeepSeek, OpenAI), dramatically reducing input token costs. - Decoupled Reasoning Effort (
consensusReasoningEffort): Multi-round debates can use lighter reasoning tiers than single-shot questions, cutting reasoning token generation by settingconsensusReasoningEffortlower thanreasoningEffortin provider defaults or model definitions. - OpenRouter Presets (
preset): Routing rules configured in OpenRouter presets (e.g.cheapest-first) can sort upstream providers by price (sort: { by: "price" }) and enable fallback routing (allow_fallbacks: true), significantly lowering inference costs across debate rounds and advisory queries.
When more than 3 models participate, the bridge emits a warning with an estimated token count. There is no hard spend cap - the warning is informational only.
MCP tools
| Tool | Purpose |
|---|---|
mcp__deliberation__openrouter |
Start a new advisory session |
mcp__deliberation__openrouter-reply |
Continue a session (multi-turn via threadId) |
mcp__deliberation__openrouter-list |
List configured model aliases and their eligibility flags |
Error kinds
| errorKind | Meaning |
|---|---|
auth |
API key missing or rejected (HTTP 401/403) |
rate-limit |
HTTP 429 from upstream. Carries retryAfterMs when the response sent a Retry-After header |
timeout |
Request exceeded the configured timeout (headers and body read are covered) |
network |
Connection error or DNS failure |
empty |
Provider exited clean but returned a stub instead of an answer (see Answer floor) |
parse |
Response body could not be parsed |
upstream |
Non-2xx from the endpoint (other than auth/rate-limit) |
config |
Config file missing, invalid JSON, or schema violation |
disabled |
The provider is off in config (providers.<name>.enabled: false). Returned before any network call or CLI spawn; the message names the key and the config file. Not retried |
model-not-allowed |
OpenRouter: requested alias is not in the config, or a raw model was passed with allowRawModel:false, or no alias/model was given and no defaultModel is set. Gemini: agy rejected an operator-pinned --model id with invalid model selection (the shipped alias falls back instead - see the --model notes) |
unknown-thread |
-reply called with a threadId that does not exist |
unknown |
Catch-all for unclassified errors |
Retries
callProvider (core/orchestrate.js) retries a failed call exactly once, and only
for the kinds that actually self-heal:
| errorKind | Retried | Pause before the retry |
|---|---|---|
network |
yes | 1s - retrying in the same millisecond cannot help a transport fault, and just doubles the log rows for a deterministic one |
rate-limit |
yes | the response's Retry-After (delta-seconds or HTTP-date), else 2s; clamped to 30s so a hostile hint cannot stall a fan-out |
empty |
yes | none - a stub answer is cheap to redo |
upstream |
yes | none - a 5xx, or a generation the provider itself aborted; the request was fine |
| everything else | no | - |
timeout is deliberately not retried: the call may already have burned tokens, and
a slow-but-good answer would be thrown away. auth / config / parse do not self-heal.
There is no exponential backoff and no second retry.
Circuit breaker
The consensus loop drops a peer after CIRCUIT_BREAK_AFTER (2) consecutive failed
rounds, so one broken model cannot add its full per-call ceiling to every round. Any
success resets the streak; a peer that is not dispatched keeps its streak (not being
asked is not recovering).
Key rules and invariants pinned here:
- Substantive technical dissent never trips the breaker. Only transport/execution
faults (
isError: true) or malformed responses (verdict: nullor unrecognized) increment the error streak. Valid technical dissent (REQUEST_CHANGESorREJECT) resets the streak to 0, ensuring principled dissent is never silenced as a fault. - Every genuine error kind counts, not just
timeout. Transport errors (network,timeout,upstream,empty) and unparseable outputs count toward the streak. - Quorum floor ($N \ge 2$). Under
consensus.quorumFloor(default 2),checkConvergencerefuses convergence unlessresponding.length >= quorumFloor. Both drivers cap the configured value at the selected panel size at init (Math.min(panel, quorumFloor), at least 1), so a one-peer panel is still valid and needs that peer to respond. When circuit breaks drop surviving active providers below the quorum floor, the loop terminates withstopReason: "quorum-lost". - Mid-session peer substitution / identity drift prevention. In
consensus-step, round 1 locks ininitialPeerNames. Subsequent rounds strictly restrict candidates to this initial set, preventing unexpected provider injection mid-session. - Both drivers share one rule. The streak lives on
LoopState.errorStreakincore/consensus-loop.js(updateErrorStreak/trippedProviders), folded in byaddOpinions. The provider-arbiter driver (runToConvergence) and the host-driven one (consensus-step) both read it. Previously only the former had a breaker at all, which is exactly the path the/consensuscommand does not use.
consensus-step reports removals as droppedProviders[] on the dispatch_peers reply.
Only the NEWLY dropped are listed: a dropped peer's streak never decays, so the full
tripped set is identical on every later round, and the server (not the host model)
tracks what it has already announced. The set is also intersected with the round's
actual candidates, so a peer that tripped earlier and has since left the config is not
reported and does not keep dropped artificially non-empty.
If every peer is dropped, the call returns a terminal status: "unresolved" with
stopReason: "all-providers-circuit-broken" rather than looping on an empty fan-out. A
panel that is empty because the config has no eligible providers reports no-providers
instead - both drivers make that distinction.
A terminal stop from dispatch_peers happens BEFORE the round's fan-out, so the record
it persists takes the last COMPLETED round's opinions from history (the live
results were reset by the previous submitRevision) and reports the number of rounds
that finished, not the one about to start.
Wall-clock budget
consensus.maxWallMs (default 1 800 000 ms, 30 min) bounds a whole loop. It gates
starting a round and never interrupts a fan-out already in flight, so a legitimately
slow answer is always collected in full. On exhaustion the loop stops with
stopReason: "budget-exhausted". It applies to both drivers; consensus-step carries
the start time on its stored state, since it is a series of stateless calls with no
enclosing scope to hold it.
The provider-arbiter loop also stops with stopReason: "arbiter-revision-failed" when the
arbiter's revision leg returns no text (an error, a stub, a timeout): advancing with the
unchanged plan would only send the same plan to every peer and buy the same dissent again.
Timeouts
Every provider call is bounded. The ceiling resolves highest-first:
- the request's own
timeoutMs models.<id>.timeoutfor a pinned OpenRouter alias (merged into the request bycore/registry.js)providers.<name>.timeout- for OpenRouter this isproviders.openrouter.defaults.timeoutproviders.defaults.timeout- one knob for every provider- the adapter's built-in default: codex 600000, gemini 300000, grok 180000, openrouter 180000
The host has its own cap, and it wins. Some MCP hosts kill any tool call from the
outside: Claude Code on the web exports MCP_TOOL_TIMEOUT=60000, so every ceiling above is
unreachable there - the host reported tool "ask-grok" timed out after 60s and the provider's
own error path never ran (no errorKind, no message, nothing that named the cap; /consensus
could never survive a real review prompt). core/host-budget.js reads MCP_TOOL_TIMEOUT and
clamps the resolved ceiling to MCP_TOOL_TIMEOUT - 5000 ms (floor 1000) at every point a
ceiling is applied - the Codex provider's ask, and runGrok / runGeminiOnce /
callOpenRouter in the bridges, so the standalone /ask-* commands are covered too. A
timeout that fired because of the clamp carries the cap in its message
(Host MCP_TOOL_TIMEOUT=60000 caps every MCP tool call ... Raise MCP_TOOL_TIMEOUT ...);
a ceiling already under the cap is passed through untouched and carries no hint. One tool call
can also run several provider legs in SEQUENCE - a retry after a failure, the arbiter passes of a
consensus round, Gemini's post-timeout drain - and a per-leg clamp alone would hand each fresh
leg the whole cap again (the host still kills the call, just later). So the server takes the
clock at tool entry (before health probes and selection), and every leg is stamped with what is
LEFT of the cap (fitToHostBudget -> req.hostBudgetRemainingMs, a separate field so a shorter
configured ceiling still wins); the adapters' clamp reads it (clampToHostBudget(wanted, env, remaining)), callProvider skips a retry whose backoff plus leg would not fit (a 30s
Retry-After at 40s into a 60s cap is not even slept on), the Grok bridge passes the spent-down
value into its Files API uploads (GROK_UPLOAD_TIMEOUT_MS is bounded by it too, even when set to
0), its non-streaming fallback and its stale-file re-upload retry, the Gemini bridge into its
alias-drop retry, runToConvergence runs
every round on the same clock and stops with stopReason: "budget-exhausted" once the cap is
spent rather than starting 1s legs, and the Gemini bridge disables its post-timeout drain under
any host cap (graceWithinHostBudget) - the ceiling is hard there, so a drain only runs into the
kill. A server-side consensus run (peers, then arbiter, per round) therefore ends as
budget-exhausted or a timeout naming the cap under a 60s host rather than being killed - it
cannot fit; use the host-driven consensus-step (one fan-out per call) or raise the cap. It is not a config key - the cap is the host's. Claude Code resolves it per server as
config.timeout ?? MCP_TOOL_TIMEOUT ?? default (progress notifications never extend it), so
.claude-plugin/plugin.json declares "timeout": 1800000 on all four servers - the same 30 min
as consensus.maxWallMs and Claude Code's stdio idle window - and mirrors it into each server's
env as MCP_TOOL_TIMEOUT. The mirror is not optional: the server process inherits the host's
60000, and the clamp above would cut every ceiling to 55s under a 30-min host allowance.
test/plugin-manifest.test.js keeps the two numbers equal. A clamped timeout on a web host
now means an install older than that manifest (the CTF container seed pinned v3.14.8 two minutes
before v3.14.9 shipped, which is how "still 60s" was reported after the clamp landed) or a host
with no per-server timeout; /deliberation:doctor says so. Garbage or zero reads as "no cap".
The transport has its own ceiling. Node's fetch (undici) gives up after 300s
waiting for response headers (headersTimeout) and after 300s between body chunks
(bodyTimeout), and there is no public API to raise either. A configured timeout above
300s is therefore only reachable while bytes are actually flowing - which is why the
Grok bridge streams (see Grok streaming) and why OpenRouter survives
past 300s (its API emits processing keepalives). Both ceilings arrive as a bare
TypeError: fetch failed and are classified timeout (never retried) with
transportCode UND_ERR_HEADERS_TIMEOUT / UND_ERR_BODY_TIMEOUT; before that they
read as network, so a provider that merely thought for over five minutes was retried
into a second five-minute wait and still failed.
An abort reaches the classifier in two shapes and both must count as timeout: the
AbortError itself, and the WRAPPED form undici produces when the controller fires
during the body read - TypeError: terminated whose cause is a DOMException named
AbortError, where neither the name nor the message mentions aborting. Missing the
wrapped shape puts the bridge's OWN ceiling back in the retryable network bucket.
Levels 3 and 4 are read once at MCP startup (constructor args, like model and
reasoningEffort), so a change needs an MCP restart; the models map still hot-reloads.
This applies to both entry points. The unified server reads the resolved value in its
composition root; the standalone bridges that /ask-grok, /ask-gemini, and
/ask-openrouter call read it themselves (configuredTimeout() in the Grok and Gemini
bridges, the pick chain in the OpenRouter bridge). Wiring only the unified server would
leave those three commands pinned to their built-ins.
Two things the ceiling covers that are easy to get wrong:
- The response body, not just the headers. Both HTTP bridges keep the
AbortControllerarmed untilres.text()resolves. A slow body is a timeout, not anetworkerror. A non-abort body failure on an OK status (a mid-stream socket drop,TypeError: terminated) surfaces asnetworkand is retried; swallowing it left an empty body that then failedJSON.parseas the non-retryableparse. On an error status the body is only diagnostic, so the status is kept and the body reported empty. - A flowing SSE body. Observed on Node 22: once Grok's SSE chunks are flowing, aborting
the fetch's signal does NOT reliably error the body - chunks kept arriving 20s+ past the
abort - and a
for awaitloop holds the stream's lock, sores.body.cancel()from outside is refused. The ceiling was therefore unenforceable exactly when it mattered (a long reasoning answer), and the call ran until the host's own cap.core/sse.js readSseStream(body, onEvent, signal)now takes the call's signal, races everyreader.read()against it, and cancels the reader it owns, so the socket is actually released. A body withoutgetReader(test doubles) falls back tofor await. - A killed Codex child. The kill timer is authoritative, so a SIGKILL'd
codex execreportstimeouteven when it wrote nothing to stderr (stderr-substring classification would otherwise call itunknown- and anunknowncan never trip the circuit breaker).
Grok's Files API upload is bounded separately by GROK_UPLOAD_TIMEOUT_MS (default 120000,
0 disables it) - an upload is a fixed-size transfer, not a model run.
Grok streaming
The Grok bridge posts stream: true to /v1/responses and reads the reply as SSE.
The reason is the transport ceiling above, not progress reporting. xAI sends nothing
until a non-streaming answer is complete, so any grok-4.6 call that thought for more
than five minutes was killed by undici's 300s headersTimeout, surfaced as a bare
TypeError: fetch failed, and was then classified network - retryable - so the call
was billed for a second five-minute wait before failing anyway. providers.grok.timeout
above 300 000 could never be reached. Streaming puts the first byte on the wire in
seconds and every chunk resets the body timeout, so the bridge's own AbortController
becomes the real ceiling.
How the reply is consumed:
Framing lives in core/sse.js (provider-agnostic: split frames, return
{event, data}) and the xAI event semantics in server/grok/stream.js. The split is
deliberate - OpenRouter is still non-streaming and subject to the same ceiling, so the
transport half is written once rather than copied when it streams.
- The bridge branches on the response
Content-Type, not on the request. An upstream free to ignorestream: truestill works, and an error status (which carries a plain JSON body even on a streaming request) takes the existing diagnostic path. - Frames split on a blank line with any of the spec's line endings (LF, CRLF, CR).
Splitting on
"\n\n"alone never matched a CRLF stream at all: the buffer grew to hold the whole response and the end-of-stream flush handed every concatenated payload to one JSON parse, turning a good answer into an empty stream. - The event name is read from the JSON payload's
typewhen present and from the SSEevent:line otherwise, so a server that names events the spec's way is understood. response.completedcarries the same object a non-streaming call returns, so the parser,usagenormalization, and theoutputcapture thatgrok-replyreplays are unchanged. It is PREFERRED, not trusted: if its output cannot be parsed, the answer accumulated in theresponse.output_text.deltachunks is used instead of throwing.response.incompleteis a TRUNCATED answer (max tokens, content filter), not a failure - the non-streaming path returned its partial output, and discarding it would throw away work already paid for. Onlyresponse.failedanderrorbecomeupstream(retryable): an aborted generation is the upstream's problem, not a malformed reply.- A clean stream carrying no output at all is
empty(retryable), neverparse: the shape was fine, the content was missing. Whitespace-only output counts as none. The answer floor applies to the assembled text as before. - A stream carrying no event we RECOGNIZE is a different failure from one carrying no
answer, and it is the real hazard of streaming by default. The bridge retries that
case exactly once with
stream: false, so a drift in the event vocabulary degrades to the old behavior instead of taking Grok offline (and, inside/consensus, getting it circuit-broken off the panel). The fallback cannot recurse. - Set
GROK_STREAM=0to force the non-streaming request outright. That reinstates the 300s ceiling, so use it only to isolate a suspected streaming problem.
Answer floor (Gemini, Grok)
A provider stub is an error, not an answer. Both bridges enforce a floor so a stub fails as
errorKind: "empty" (retried once by callProvider) instead of reaching the caller as an
opinion - inside consensus a stub yields verdict: null and silently blocks convergence.
The rule lives in one place, core/answer-floor.js (stubReason(text, minChars)), and
both bridges call it: a trimmed reply is a stub when it is shorter than
GEMINI_MIN_ANSWER_CHARS / GROK_MIN_ANSWER_CHARS (default 1, i.e. empty), OR when it is
under 400 characters and opens with an intent phrase (I'll / I will / I'm going to /
Let me / First, I) followed by an exploration verb (begin, start, verify,
check, read, look, find, open, examine, inspect, review, explore, search,
scan, run, fetch, gather, walk, dig, investigate, analyse, take a look,
go through). The phrase alone is not enough - "I will.", "I'll go with option B because..."
and "Let me be clear: no." are complete answers - and a long answer that merely opens with
"I'll" is not a stub. The intent check is new for Gemini (it existed only in the Grok
bridge before); it also catches preambles that were long enough to clear the old 80-char
floor. 0 disables both checks. The failure carries the reason ("2 chars, below the 80-char
answer floor" / "51 chars that only announce intent"), and since
issue #180 (external) the unified error
envelope forwards it as message - before that, the operator saw only the coarse
errorKind: "empty" and had no way to tell a floor rejection from a transport fault.
Why not a length floor. The first version rejected anything under 80 characters. That
caught the 51-character Gemini preamble, but issue #180 showed the cost: the reporter's
smoke prompt Sag nur: ok made agy answer ok (2 characters, exit 0) and every
ask-gemini call failed as empty while agy itself worked by hand. A character count
cannot tell a terse answer from a stub; the opening phrase can, and it catches the observed
stubs of both providers. Operators who want the old hard floor set the variable to 80.
Gemini. agy sometimes exits 0 having printed only a preamble ("I will begin by finding the
repository directory...") instead of an answer. Any non-empty stdout used to count as a
full answer, so that stub reached the caller as a real opinion - and inside consensus it
silently blocked convergence with no diagnostic (parseReview yields verdict: null). A
stub now fails with errorKind: "empty", which callProvider retries once.
The floor applies on both the clean-exit and the soft-timeout drain path. Exempting the
drain would make validity timing-dependent - the same stub would fail when agy is fast and
pass when it is slow. A stub recovered after a soft timeout is not an answer either, so it
falls through to the hard timeout.
An opening-phrase check is still a proxy for "announced intent instead of answering" - the upgrade path is a structured-output check if providers ever return a parsed envelope.
Grok. grok-4.6 is agentic-trained and is reached through ONE /v1/responses call with
no tools declared. A prompt that mentions repositories or asks it to "verify the cited files"
(the expert prompts invite this "when you have filesystem access") can make it announce a
plan - I'll verify the cited files and edit anchors so the review is based on what's actually in the repo. - and end its turn as if a tool result were coming: status: "completed", zero
tool calls, a 99-162 character reply. Two guards, both in server/grok/index.js so the
standalone grok tool and the unified server share them:
buildInitialTurnsalways seeds a system turn ending with a fixed runtime note: no tools, no filesystem or repository access, no web, no further turns; attached files are reference material; answer completely now.grok-replycontinuations inherit it from the persisted turns.runGrokrejects the answer with.code = "empty"whenstubReasonsays so (above). An empty message body (""), which used to return as a silent success, is caught by the default floor of 1.