Deliberationv4.6.1

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 set selectForAskAll would dispatch (enabled, HEALTHY built-ins + eligible OpenRouter aliases, fanout cap applied), WITHOUT calling any provider. omitted is the fanout-cap drop list; unavailable names enabled built-ins whose stat-only health() failed (codex CLI missing or no credential, agy not on PATH) with the reason, so a dead peer is never dispatched to fail. The same map feeds ask-all, consensus, and consensus-step (unavailableProviders[] on dispatch_peers; a provider X unavailable: ... warning on the consensus tool). Read-only.
  • ask-one { provider, prompt, expert?, cwd?, reasoningEffort?, files? } runs ONE provider named by panel (resolved from the same selection set, so a pinned openrouter:<alias> works and a disabled/over-cap name returns { error, panel }).
  • The pattern (commands/ask-all.md on Claude Code): call panel, then issue one ask-one per 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-call ask-all tool 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 - okCalls is the percentile denominator, and a row with none reports null rather than 0. A timeout is logged with its full ms, so counting errors as latency reported the timeout ceiling as model speed (and a 0 p95 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.

Rendered from TECHNICAL.md in the repository.

Type to search the site.