Deliberationv4.6.1

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.openrouter block now means "on when the key is set". providers.openrouter.enabled: false turns OpenRouter off, built-in panel included. The starter config that /setup writes and config/config.default.json both set enabled: false, so a user with that file opts in by setting it to true.
  • Replaced, not merged. One valid models record with provider: "openrouter" (or no provider) removes all three built-in records. Records for ollama / lmstudio do not count and are listed before the built-in records, so in ask-all they take routing.maxFanout slots first: with the default of 3, one local record leaves room for two built-in records. Raise routing.maxFanout to keep all three. consensus is not capped, so all three built-in records still vote there.
  • Default. A configured default (default: true on a record, or providers.openrouter.defaultModel) wins over glm-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-list marks these records builtin: true; panel and results name them openrouter:<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: false turns the provider off for every tool: ask-all, consensus, panel and the expert tools leave it out, and a tool that names it (ask-gpt / ask-gemini / ask-grok / ask-openrouter, ask-one, and the standalone gemini, grok and openrouter bridges with their -reply tools) returns errorKind: "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 explicit false disables; a missing block or flag means enabled (for OpenRouter, a missing block with no key is a missing credential, not disabled). providers.openrouter also carries the OpenRouter-specific connection keys (apiBase, allowRawModel, defaultModel, per-call defaults).
  • models - named model records, keyed by id. Each record names its provider and model slug 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) and blindVote (optional blind arbiter pre-vote; boolean, default false).

Config file schema (strict JSON, version must be 1):

json
{
  "$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:

  1. apiKeyEnv is set on the model record: The bridge reads the environment variable named by apiKeyEnv. If unset or empty, no Authorization header is sent. It never falls through to the provider key (OPENROUTER_API_KEY).
  2. The record has no apiBase, or its apiBase equals or.apiBase (after stripping trailing slashes): The bridge uses the provider key (process.env[or.apiKeyEnv], defaulting to OPENROUTER_API_KEY).
  3. Otherwise (custom apiBase without apiKeyEnv): The bridge sends no key (keyless proxy endpoint).

Important

Migration note (v3.31.0+): Previously, any model record with a custom apiBase received OPENROUTER_API_KEY. Starting with v3.31.0, records with a custom apiBase default to keyless (Rule 3). Authenticated proxies must set models.<id>.apiKeyEnv to 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 a models record. The record can be any entry - even one with askAll: false and consensus: 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 - blindVerdict is null.
  • 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 with blindVote off the round records (blind pass disabled) and skips the call.
  • Failure-isolated. A thrown blind pass yields blindVerdict: null and never fails the run. blindVerdict is also null when blindVote is off or no arbiter exists.
  • Validation. A non-boolean value soft-degrades to false with 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 above 50 is clamped to 50 with a warning; a non-integer or non-positive value is dropped (the default 5 applies) with a warning - it never hard-fails the config.
  • Scope. It governs only the multi-round loop tools. The one-shot consensus tool is a single arbiter pass and is unaffected.
  • Validation lives in resolveConsensus (server/openrouter/config.js); the cap is enforced in core/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 consensus tool only. The host-driven consensus-step path has no server-side wall clock; the host controls timing there.
  • The budget is forwarded to runToConvergence as opts.maxWallMs and checked in core/consensus-loop.js at 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 where askAll !== false and the record is eligible for the requested expert; capped to routing.maxFanout records (default 3).
  • /consensus: includes records where consensus === true; NOT subject to maxFanout. A warning is logged when more than 3 records enter a consensus round (cost).
  • openrouter-default is the reserved id for the bare mcp__deliberation__openrouter call and /ask-openrouter with no record specified. It resolves to defaultModel, 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):

jsonc
{
  "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" } ]
}
  • builtin is true on the records of the built-in panel (see Built-in panel) and false on records from config.json.
  • delegates (and selected/omitted) list only provider: "openrouter" records; the standalone bridge cannot call ollama/lmstudio records, so they appear only in the unified server's panel. invalidModels is 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>" with delegates: [] (and invalidModels absent/empty). /ask-all and /consensus treat the error form as "OpenRouter set EMPTY".
  • invalidModels[].suggestedAlias is 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 -N suffix. Suggestions are collision-checked against every existing id and the reserved openrouter-default. Entries with no safe fix (missing model, unknown expert, non-openrouter provider, reserved-id clash) have no suggestedAlias.
  • The bridge never edits config.json. The /ask-all and /consensus commands surface invalidModels and offer Fix & proceed (default - apply each suggestedAlias to config.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.preset or providers.openrouter.defaults.preset: Default preset applied to OpenRouter calls.
  • models.<id>.preset: Per-model preset. A model record can specify preset alone (delegating model selection to the preset) or alongside an explicit model (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:

  1. 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.
  2. 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.
  3. Decoupled Reasoning Effort (consensusReasoningEffort): Multi-round debates can use lighter reasoning tiers than single-shot questions, cutting reasoning token generation by setting consensusReasoningEffort lower than reasoningEffort in provider defaults or model definitions.
  4. 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: null or unrecognized) increment the error streak. Valid technical dissent (REQUEST_CHANGES or REJECT) 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), checkConvergence refuses convergence unless responding.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 with stopReason: "quorum-lost".
  • Mid-session peer substitution / identity drift prevention. In consensus-step, round 1 locks in initialPeerNames. 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.errorStreak in core/consensus-loop.js (updateErrorStreak / trippedProviders), folded in by addOpinions. 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 /consensus command 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:

  1. the request's own timeoutMs
  2. models.<id>.timeout for a pinned OpenRouter alias (merged into the request by core/registry.js)
  3. providers.<name>.timeout - for OpenRouter this is providers.openrouter.defaults.timeout
  4. providers.defaults.timeout - one knob for every provider
  5. 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 AbortController armed until res.text() resolves. A slow body is a timeout, not a network error. A non-abort body failure on an OK status (a mid-stream socket drop, TypeError: terminated) surfaces as network and is retried; swallowing it left an empty body that then failed JSON.parse as the non-retryable parse. 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 await loop holds the stream's lock, so res.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 every reader.read() against it, and cancels the reader it owns, so the socket is actually released. A body without getReader (test doubles) falls back to for await.
  • A killed Codex child. The kill timer is authoritative, so a SIGKILL'd codex exec reports timeout even when it wrote nothing to stderr (stderr-substring classification would otherwise call it unknown - and an unknown can 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 ignore stream: true still 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 type when present and from the SSE event: line otherwise, so a server that names events the spec's way is understood.
  • response.completed carries the same object a non-streaming call returns, so the parser, usage normalization, and the output capture that grok-reply replays are unchanged. It is PREFERRED, not trusted: if its output cannot be parsed, the answer accumulated in the response.output_text.delta chunks is used instead of throwing.
  • response.incomplete is 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. Only response.failed and error become upstream (retryable): an aborted generation is the upstream's problem, not a malformed reply.
  • A clean stream carrying no output at all is empty (retryable), never parse: 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=0 to 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:

  • buildInitialTurns always 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-reply continuations inherit it from the persisted turns.
  • runGrok rejects the answer with .code = "empty" when stubReason says so (above). An empty message body (""), which used to return as a silent success, is caught by the default floor of 1.

Rendered from TECHNICAL.md in the repository.

Type to search the site.