Observability + per-provider progress
Observability + per-provider progress
These are server-side on the unified deliberation server, so every MCP host gets them -
not only Claude Code. Every DelegationResult carries ms (wall time) and the effective
reasoningEffort (a real value for HTTP providers; null for the Codex/Gemini CLIs, which
have no per-call knob); HTTP providers (Grok, OpenRouter) also include token usage.
panel + ask-one (visible per-provider progress)
ask-all is one tool call that fans out to N providers server-side - opaque until all
finish. The alternative, for hosts where that opacity hurts:
panel { expert?, for?, cwd? }returns{ providers: string[], omitted: string[], unavailable: {name, reason}[], needsLogin: string[] }- the EXACT setselectForAskAllwould dispatch (enabled, HEALTHY built-ins + eligible OpenRouter aliases, fanout cap applied), WITHOUT calling any provider.omittedis the fanout-cap drop list;unavailablenames enabled built-ins whose stat-onlyhealth()failed (codex CLI missing or no credential,agynot on PATH) with the reason, so a dead peer is never dispatched to fail. The same map feedsask-all,consensus, andconsensus-step(unavailableProviders[]ondispatch_peers; aprovider X unavailable: ...warning on theconsensustool). Read-only.ask-one { provider, prompt, expert?, cwd?, reasoningEffort?, files? }runs ONE provider named bypanel(resolved from the same selection set, so a pinnedopenrouter:<alias>works and a disabled/over-cap name returns{ error, panel }).- The pattern (
commands/ask-all.mdon Claude Code): callpanel, then issue oneask-oneper name in a single turn. The host runs them concurrently (parallel wall-time) and surfaces each result as it settles, so progress is visible per provider. The legacy single-callask-alltool is retained for back-compat / other hosts.
Why two paths: Claude Code does NOT render mid-call MCP notifications/message (verified),
but DOES surface each parallel tool result as it lands - so the per-provider tool path is
the progress lever there. Hosts that DO render server log notifications get live progress
from the single ask-all call too (next section).
MCP logging capability
The server declares the logging capability in initialize and accepts logging/setLevel.
During a fan-out it emits one notifications/message (level info, logger deliberation)
per provider as it settles, plus a dispatch_start. The payload carries event/provider/ms/
verdict metadata only - never prompt or response text (MCP logging security rule). A client
that raises its min level above info suppresses them.
Debug log (debug.enabled, OFF by default)
Set "debug": { "enabled": true } (optional "path") in config.json to append one
compact JSON line per provider call and per consensus round to
<XDG cache>/deliberation/debug.jsonl (override with debug.path or
DELIBERATION_DEBUG_LOG). The logger (core/debug-log.js) is INJECTED through core
(askAll / askOne / consensus / runToConvergence) and emitted at the source, so the
Claude host-arbiter path and the in-core provider-arbiter loop log identically - one code
path, every host. Records: timestamp, tool, provider, model, reasoning effort, ms,
HTTP token usage, and consensus round/verdict/converged/accepted-issue COUNT. A strict
ALLOWED_KEYS whitelist is applied on every write, so prompts, responses, and free-text
issue descriptions can never land in the file. Off by default; nothing is written unless
enabled.
A failed call also records errorCode: the low-level transport cause behind the coarse
errorKind, taken from the rejection's cause.code (UND_ERR_HEADERS_TIMEOUT,
ENOTFOUND, ECONNRESET, ...). Without it network conflated a DNS failure, a socket
reset, undici's own header ceiling and a local throw - four different fixes behind one
label - in the only place provider health is actually diagnosed. It is a bare errno /
undici symbol, never a message, so it is content-free like every other logged key.
In-session result cache
core/result-cache.js is an in-memory (process-lifetime) dedup cache wired to the advisory
ask-all / ask-one paths only (NOT the consensus loop). An identical re-ask (same
provider + model + reasoning effort + temperature + developer instructions + prompt + file
refs) returns the prior SUCCESS instantly with a cached:true marker. LRU-bounded (100) +
10-minute TTL; errors are never cached; file-bearing requests skip it (file content can
change under a path); session-revisit bypasses it (a revisit is a deliberate re-run).
doctor (health check)
server/mcp/doctor.js runs every check behind /deliberation:doctor; the read-only doctor
MCP tool returns its findings, so a host with only the npx server gets the same report. The
command adds one shell step: it prints the session dir the shell resolves and passes it as
shellSessionsDir, the one value the server cannot see.
check |
Source | Status |
|---|---|---|
server |
this server's location and server/mcp/package.json version |
ok (plugin root or standalone) |
config |
reads the config path, JSON.parse, then validateConfig (the runtime validator config.schema.json is tested against); unknown top-level keys are compared with the schema's properties; consensusWarnings and invalidModels |
warn missing file, fail unreadable / bad JSON / rejected, warn per unknown key or warning |
sessions.persist, debug.enabled |
resolved config | warn when off (Lens B / Lens A of analyze) |
host-cap |
MCP_TOOL_TIMEOUT in the server env |
warn below 600000 or not a number |
provider:codex / gemini / grok / openrouter |
the same stat-only health() probes panel uses; codex adds codex --version and its credential source (CODEX_ACCESS_TOKEN, auth.json, CODEX_API_KEY) |
warn unavailable or no codex login, info disabled in config |
gemini-agy-terms |
Gemini enabled, its provider is the Antigravity CLI (transport: "agy") and agy is on PATH |
warn with the section 6 terms quote; prefer a Gemini API key |
provider:ollama / lmstudio |
model records with that provider | info; endpoints are not probed |
sessions-dir |
the session store dir this server resolved | warn when missing |
sessions-path |
shellSessionsDir argument, only when passed |
fail on drift |
sessions-verdicts |
analyze meta, only with sessions.persist on |
info when records carry no per-opinion verdicts |
registrations |
plugin installs only: ~/.claude.json user-scope deliberation* entries |
warn when they shadow the plugin manifest |
The tool never starts a login, never writes and makes no network call; key values are never returned, only set/unset. A bad config is a finding, not an error.
analyze (run analytics + tuning advice)
core/analyze.js is pure (zero-dep, unit-tested); the read-only analyze MCP tool does the
IO and calls it. It answers "is my model panel pulling its weight?" from real measured data,
in two lenses that are never joined (the debug log and the session store share no run id):
- Lens A - timing/cost (debug log):
aggregateByModel-> per provider+model count, error rate, p50/p95/max latency, mean tokens (HTTP only), reasoning efforts + tools seen. The tool tail-reads the log (last ~1 MB by default;limitBytes, clamped to 32 MB) so a large file cannot bloat memory, and returns pre-aggregated stats, never raw lines. Latency covers successful calls only -okCallsis the percentile denominator, and a row with none reportsnullrather than0. A timeout is logged with its fullms, so counting errors as latency reported the timeout ceiling as model speed (and a0p95 would have made an all-error model the fastest-peer baseline). - Lens B - agreement (sessions):
aggregateAgreement-> per model, the share of its review verdicts that matched the run's FINAL verdict. Only consensus-loop records (which carry a final verdict) contribute votes; ask-all opinions are abstentions. This is the "uniqueness" proxy (a model that rarely dissents adds little), without reading opinion text or an LLM pass.
detectOutliers flags slow (relative to the fastest-peer baseline, or absolute) and
high-error models; recommend turns those + the agreement signal into advisory Suggestions
naming the exact config.json key (models.<id>.askAll, models.<id>.reasoningEffort,
providers.codex.reasoningEffort, routing.maxFanout). Gemini reasoning is flagged as external
(agy) since it is outside Deliberation's config. The tool writes nothing; /deliberation:analyze
renders it for humans and prints suggested edits without applying them. Needs debug.enabled
for Lens A and sessions.persist for Lens B; when the log is empty it returns
meta.insufficientData:true instead of fabricating numbers.
Scope controls. configuredOnly (default true) reports only models present in the
current config, so a retired model can no longer drive the headline numbers or earn a
"cut this" suggestion. OpenRouter rows match by alias against openrouter.models[]; native
rows (codex/gemini/grok) are dropped only on an explicit providers.<name>.enabled:false,
never on a model mismatch - auto-gemini-3 is a router alias, so the log records the
resolved model and pin-equality would hide every active row. Dropped rows are listed in
meta.excluded with a reason (not in config, rejected by config validation,
openrouter provider disabled, provider disabled); a config parse error skips the filter
entirely rather than reporting every model as unconfigured. since (30m/24h/7d/seconds,
max 10 years) windows both lenses, since recommend crosses "slow" with "rarely dissents"
in one suggestion and split windows would make that a mixed-period claim. meta.window
reports real coverage across both lenses, and meta.truncated reports whether a bound cut
the data short. meta.modelVariants flags providers seen running several model ids - a
prompt to look them up, deliberately not a claim about which is newer.
The engine reads the resolved config (openrouter.models[] with alias and snake_case
reasoning_effort, openrouter.maxFanout) while every suggestion names the on-disk path
(models.<id>.*, routing.maxFanout). Those are different namespaces on purpose; reading the
raw on-disk shape is what made the reasoningEffort suggestion silently dead in production.