@antonbabenko/deliberation-mcp 3.3.0 → 3.5.0

package/dist/index.js

@@ -750,6 +750,243 @@ var require_prompts = __commonJS({
   }
 });
 
+// ../../core/analyze.js
+var require_analyze = __commonJS({
+  "../../core/analyze.js"(exports2, module2) {
+    "use strict";
+    var SLOW_FACTOR = 2;
+    var MIN_BASELINE_MS = 200;
+    var MIN_CALLS = 2;
+    var ABS_SLOW_MS = 12e4;
+    var HIGH_ERROR_RATE = 0.5;
+    var HIGH_AGREEMENT = 0.9;
+    var MIN_VOTES = 3;
+    var OR_PREFIX = "openrouter:";
+    function parseDebugLog(text) {
+      if (typeof text !== "string" || text.length === 0) return [];
+      const out = [];
+      for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        let obj;
+        try {
+          obj = JSON.parse(trimmed);
+        } catch {
+          continue;
+        }
+        if (obj && typeof obj === "object" && typeof obj.event === "string") {
+          out.push(
+            /** @type {DebugEvent} */
+            obj
+          );
+        }
+      }
+      return out;
+    }
+    function percentile(sorted, p) {
+      if (!sorted.length) return 0;
+      if (sorted.length === 1) return sorted[0];
+      const idx = p / 100 * (sorted.length - 1);
+      const lo = Math.floor(idx);
+      const hi = Math.ceil(idx);
+      if (lo === hi) return sorted[lo];
+      return sorted[lo] + (sorted[hi] - sorted[lo]) * (idx - lo);
+    }
+    function aggregateByModel(events) {
+      const groups = /* @__PURE__ */ new Map();
+      for (const e of Array.isArray(events) ? events : []) {
+        if (!e || e.event !== "provider_result" || typeof e.provider !== "string") continue;
+        const provider = e.provider;
+        const model = typeof e.model === "string" ? e.model : "";
+        const key = `${provider}|${model}`;
+        let g = groups.get(key);
+        if (!g) {
+          g = { provider, model, ms: [], errors: 0, calls: 0, tokens: [], efforts: /* @__PURE__ */ new Set(), tools: /* @__PURE__ */ new Set() };
+          groups.set(key, g);
+        }
+        g.calls += 1;
+        if (e.isError) g.errors += 1;
+        if (typeof e.ms === "number" && Number.isFinite(e.ms)) g.ms.push(e.ms);
+        const tot = e.usage && typeof e.usage.totalTokens === "number" ? e.usage.totalTokens : void 0;
+        if (typeof tot === "number" && Number.isFinite(tot)) g.tokens.push(tot);
+        g.efforts.add(e.reasoningEffort == null ? "n/a" : String(e.reasoningEffort));
+        if (typeof e.tool === "string") g.tools.add(e.tool);
+      }
+      const stats = [];
+      for (const g of groups.values()) {
+        const sorted = g.ms.slice().sort((a, b) => a - b);
+        const mean = sorted.length ? sorted.reduce((a, b) => a + b, 0) / sorted.length : 0;
+        stats.push({
+          provider: g.provider,
+          model: g.model,
+          calls: g.calls,
+          errors: g.errors,
+          errorRate: g.calls ? g.errors / g.calls : 0,
+          ms: {
+            p50: Math.round(percentile(sorted, 50)),
+            p95: Math.round(percentile(sorted, 95)),
+            max: sorted.length ? sorted[sorted.length - 1] : 0,
+            mean: Math.round(mean)
+          },
+          meanTokens: g.tokens.length ? Math.round(g.tokens.reduce((a, b) => a + b, 0) / g.tokens.length) : null,
+          reasoningEfforts: Array.from(g.efforts).sort(),
+          tools: Array.from(g.tools).sort()
+        });
+      }
+      stats.sort((a, b) => b.ms.p95 - a.ms.p95);
+      return stats;
+    }
+    function aggregateAgreement(records) {
+      const groups = /* @__PURE__ */ new Map();
+      for (const rec of Array.isArray(records) ? records : []) {
+        if (!rec || !Array.isArray(rec.opinions)) continue;
+        const finalVerdict = typeof rec.verdict === "string" ? rec.verdict : null;
+        for (const op of rec.opinions) {
+          if (!op || typeof op.provider !== "string") continue;
+          const provider = op.provider;
+          const model = typeof op.model === "string" ? op.model : "";
+          const key = `${provider}|${model}`;
+          let g = groups.get(key);
+          if (!g) {
+            g = { provider, model, votes: 0, agreed: 0, abstained: 0 };
+            groups.set(key, g);
+          }
+          const opVerdict = typeof op.verdict === "string" ? op.verdict : null;
+          if (finalVerdict && opVerdict) {
+            g.votes += 1;
+            if (opVerdict === finalVerdict) g.agreed += 1;
+          } else {
+            g.abstained += 1;
+          }
+        }
+      }
+      const out = [];
+      for (const g of groups.values()) {
+        out.push({
+          provider: g.provider,
+          model: g.model,
+          votes: g.votes,
+          agreed: g.agreed,
+          agreementRate: g.votes ? g.agreed / g.votes : null,
+          abstained: g.abstained
+        });
+      }
+      out.sort((a, b) => {
+        const ar = a.agreementRate == null ? Infinity : a.agreementRate;
+        const br = b.agreementRate == null ? Infinity : b.agreementRate;
+        return ar - br;
+      });
+      return out;
+    }
+    function detectOutliers(stats) {
+      const eligible = (Array.isArray(stats) ? stats : []).filter((s) => s.calls >= MIN_CALLS);
+      if (!eligible.length) return [];
+      const fastestP95 = Math.min(...eligible.map((s) => s.ms.p95));
+      const baseline = Math.max(fastestP95, MIN_BASELINE_MS);
+      const out = [];
+      for (const s of eligible) {
+        if (s.errorRate >= HIGH_ERROR_RATE) {
+          out.push({ provider: s.provider, model: s.model, kind: "high-error", detail: `${Math.round(s.errorRate * 100)}% of ${s.calls} calls errored` });
+        }
+        if (s.ms.p95 >= ABS_SLOW_MS) {
+          out.push({ provider: s.provider, model: s.model, kind: "slow-absolute", detail: `p95 ${s.ms.p95}ms (>= ${ABS_SLOW_MS}ms)` });
+        } else if (s.ms.p95 >= SLOW_FACTOR * baseline) {
+          out.push({ provider: s.provider, model: s.model, kind: "slow-relative", detail: `p95 ${s.ms.p95}ms vs fastest-peer baseline ${Math.round(baseline)}ms` });
+        }
+      }
+      return out;
+    }
+    function leverFor(provider) {
+      if (provider.startsWith(OR_PREFIX)) return { kind: "openrouter", alias: provider.slice(OR_PREFIX.length) };
+      if (provider === "codex" || provider === "gemini") return { kind: "external" };
+      if (provider === "grok") return { kind: "grok" };
+      return { kind: "unknown" };
+    }
+    function recommend(stats, agreement, config) {
+      const cfg = config && typeof config === "object" ? config : {};
+      const models = cfg.models && typeof cfg.models === "object" ? cfg.models : {};
+      const outliers = detectOutliers(stats);
+      const agreeBy = /* @__PURE__ */ new Map();
+      for (const a of Array.isArray(agreement) ? agreement : []) agreeBy.set(a.provider, a);
+      const out = [];
+      let slowOpenRouterCount = 0;
+      for (const o of outliers) {
+        if (o.kind === "high-error") {
+          const lever2 = leverFor(o.provider);
+          out.push({
+            target: lever2.kind === "openrouter" ? "deliberation" : "external",
+            subject: o.provider,
+            configKey: lever2.kind === "openrouter" ? `models.${lever2.alias}.askAll` : null,
+            action: lever2.kind === "openrouter" ? `set models.${lever2.alias}.askAll=false until it stabilizes` : `check the ${o.provider} credentials/CLI session`,
+            rationale: o.detail
+          });
+          continue;
+        }
+        const lever = leverFor(o.provider);
+        const agree = agreeBy.get(o.provider);
+        const rarelyDissents = !!(agree && agree.agreementRate != null && agree.votes >= MIN_VOTES && agree.agreementRate >= HIGH_AGREEMENT);
+        const valueNote = rarelyDissents ? ` It also agreed with the final verdict ${agree ? Math.round((agree.agreementRate || 0) * 100) : 0}% of ${agree ? agree.votes : 0} votes (rarely adds dissent), so it is the strongest cut candidate.` : "";
+        if (lever.kind === "openrouter") {
+          slowOpenRouterCount += 1;
+          const alias = typeof lever.alias === "string" ? lever.alias : "";
+          const entry = models[alias] && typeof models[alias] === "object" ? models[alias] : null;
+          const effort = entry && typeof entry.reasoningEffort === "string" ? entry.reasoningEffort : null;
+          if (effort && effort !== "low") {
+            out.push({ target: "deliberation", subject: o.provider, configKey: `models.${alias}.reasoningEffort`, action: `lower models.${alias}.reasoningEffort (currently ${effort})`, rationale: `Slowest in the panel (${o.detail}).${valueNote}` });
+          }
+          out.push({ target: "deliberation", subject: o.provider, configKey: `models.${alias}.askAll`, action: `set models.${alias}.askAll=false to drop it from /ask-all fan-out`, rationale: `In parallel fan-out, wall-time is the slowest model (${o.detail}).${valueNote}` });
+        } else if (lever.kind === "external") {
+          out.push({ target: "external", subject: o.provider, configKey: null, action: o.provider === "codex" ? "lower model_reasoning_effort in ~/.codex/config.toml (or pass it per-call)" : "lower the Gemini/agy reasoning setting", rationale: `Slowest in the panel (${o.detail}); its reasoning lever is outside deliberation's config.${valueNote}` });
+        } else {
+          out.push({ target: "deliberation", subject: o.provider, configKey: null, action: `consider whether ${o.provider} earns its latency in the panel`, rationale: `${o.detail}.${valueNote}` });
+        }
+      }
+      if (slowOpenRouterCount >= 2) {
+        const fanout = cfg.routing && typeof cfg.routing.maxFanout === "number" ? cfg.routing.maxFanout : null;
+        out.push({ target: "deliberation", subject: "panel", configKey: "routing.maxFanout", action: fanout ? `lower routing.maxFanout (currently ${fanout})` : "set routing.maxFanout to 1-2", rationale: `${slowOpenRouterCount} OpenRouter models are slow outliers; a smaller fan-out cuts cost and parallel wall-time.` });
+      }
+      return out;
+    }
+    function buildAnalysis(events, records, config, meta) {
+      const evs = Array.isArray(events) ? events : [];
+      const recs = Array.isArray(records) ? records : [];
+      const stats = aggregateByModel(evs);
+      const agreement = aggregateAgreement(recs);
+      const outliers = detectOutliers(stats);
+      const recommendations = recommend(stats, agreement, config);
+      return {
+        stats,
+        agreement,
+        outliers,
+        recommendations,
+        meta: {
+          logPath: meta && meta.logPath,
+          debugEnabled: !!(meta && meta.debugEnabled),
+          sessionsPersist: !!(meta && meta.sessionsPersist),
+          eventsParsed: evs.length,
+          sessionsRead: recs.length,
+          insufficientData: stats.length === 0
+        }
+      };
+    }
+    module2.exports = {
+      SLOW_FACTOR,
+      MIN_CALLS,
+      ABS_SLOW_MS,
+      HIGH_ERROR_RATE,
+      HIGH_AGREEMENT,
+      MIN_VOTES,
+      parseDebugLog,
+      percentile,
+      aggregateByModel,
+      aggregateAgreement,
+      detectOutliers,
+      recommend,
+      buildAnalysis
+    };
+  }
+});
+
 // ../../core/sessions.js
 var require_sessions = __commonJS({
   "../../core/sessions.js"(exports2, module2) {
@@ -4162,6 +4399,7 @@ var require_openrouter = __commonJS({
 var { makeRegistry, pinAlias } = require_registry();
 var { askAll, askOne, consensus, runToConvergence } = require_orchestrate();
 var { PROMPTS } = require_prompts();
+var analyzeCore = require_analyze();
 var ADVISORY = { readOnlyHint: true };
 var ASK_PROVIDER = { "ask-gpt": "codex", "ask-gemini": "gemini", "ask-grok": "grok", "ask-openrouter": "openrouter" };
 var EXPERTS = ["architect", "plan-reviewer", "scope-analyst", "code-reviewer", "security-analyst", "researcher", "debugger"];
@@ -4183,6 +4421,15 @@ function panelInputSchema() {
     }
   };
 }
+function analyzeInputSchema() {
+  return {
+    type: "object",
+    properties: {
+      sessions: { type: "integer", description: "How many recent session records to read for the agreement lens (default 50)." },
+      limitBytes: { type: "integer", description: "Tail size of the debug log to read, in bytes (default 1048576)." }
+    }
+  };
+}
 function askOneInputSchema() {
   return {
     type: "object",
@@ -4294,7 +4541,8 @@ function toolList() {
     { name: "consensus", description: "Run the FULL multi-round consensus convergence loop server-side with a provider arbiter (blind pass + peer fan-out -> adjudicate -> revise) and return the converged verdict. Default depth is `consensus.maxRounds` (config, default 5); pass `maxRounds` to override. Pass `synthesizeAlways:true` for a SINGLE arbiter synthesis pass instead of the loop (best for open questions, not plan convergence): it returns a free-text `synthesis` and `maxRounds` is ignored. Configure the arbiter via `consensus.arbiter` - a concrete provider/openrouter alias runs server-side; `host` mode returns the opinions for YOU to synthesize. Advisory; pass `expert` to apply a persona. NOTE (Claude Code): use the `/consensus` slash command for the transcript-visible host-arbiter loop (it drives `consensus-step`); this tool is the provider-arbiter path for any host.", inputSchema: consensusInputSchema(), annotations: ADVISORY },
     { name: "consensus-step", description: "Client-driven consensus loop where YOU (the host model) are the arbiter, one step per call: action=init (start, returns sessionId + blind prompt) -> record_blind (your pre-commit verdict) -> dispatch_peers (server fans out to the providers) -> submit_adjudication (your verdict + per-issue accept/dismiss/defer) -> submit_revision (your revised plan), looping until converged or consensus.maxRounds rounds (default 5). State is held server-side by sessionId. Advisory.", inputSchema: consensusStepInputSchema(), annotations: ADVISORY },
     { name: "panel", description: "Return the names of the providers `ask-all` WOULD dispatch for the current config + expert (enabled built-ins + eligible OpenRouter aliases, fanout cap applied), WITHOUT calling them. Use this to discover the panel, then issue one `ask-one` call per provider in parallel for visible per-provider progress. Advisory, read-only.", inputSchema: panelInputSchema(), annotations: ADVISORY },
-    { name: "ask-one", description: "Second opinion from ONE named provider in the active panel (e.g. `codex`, `gemini`, `grok`, `openrouter:<alias>` - get the names from `panel`). Returns the standard result envelope. Issue N of these in parallel (one per `panel` name) so each renders independently as it lands. Advisory, single-shot.", inputSchema: askOneInputSchema(), annotations: ADVISORY }
+    { name: "ask-one", description: "Second opinion from ONE named provider in the active panel (e.g. `codex`, `gemini`, `grok`, `openrouter:<alias>` - get the names from `panel`). Returns the standard result envelope. Issue N of these in parallel (one per `panel` name) so each renders independently as it lands. Advisory, single-shot.", inputSchema: askOneInputSchema(), annotations: ADVISORY },
+    { name: "analyze", description: "Analyze recent runs from the opt-in debug log (latency/tokens/reasoning-effort per model) plus the session store (verdict agreement rate), and return advisory tuning suggestions (disable a slow/redundant model in ask-all, lower an OpenRouter model's reasoning, adjust maxFanout). Two lenses reported side by side - timing and agreement are NOT joined (no shared run id). Suggestions are advisory; it writes nothing. Requires `debug.enabled` for the timing lens. Read-only. The `/deliberation:analyze` slash command renders this for humans.", inputSchema: analyzeInputSchema(), annotations: ADVISORY }
   ];
   for (const t of Object.keys(ASK_PROVIDER)) {
     tools.push({ name: t, description: `Single-provider second opinion via ${ASK_PROVIDER[t]} (advisory, single-shot). Pass \`expert\` to apply one of the expert personas.`, inputSchema: inputSchema(), annotations: ADVISORY });
@@ -4789,6 +5037,46 @@ function buildServer({ providers, getConfig, getConfigError, sessionsDir, notify
       return { error: /expected status/.test(msg) ? "unexpected-action-for-status" : "step-failed", detail: msg };
     }
   }
+  function runAnalyze(args) {
+    const fs = require("node:fs");
+    const cfg = getConfig() || {};
+    const dbg = cfg.debug || {};
+    const debugEnabled = !!dbg.enabled;
+    const logPath = typeof dbg.path === "string" && dbg.path || resolveDebugLogPath();
+    const limitBytes = Number.isInteger(args.limitBytes) && args.limitBytes > 0 ? args.limitBytes : 1024 * 1024;
+    let text = "";
+    try {
+      const fd = fs.openSync(logPath, "r");
+      try {
+        const size = fs.fstatSync(fd).size;
+        const start = size > limitBytes ? size - limitBytes : 0;
+        const len = size - start;
+        if (len > 0) {
+          const buf = Buffer.alloc(len);
+          fs.readSync(fd, buf, 0, len, start);
+          text = buf.toString("utf8");
+          if (start > 0) {
+            const nl = text.indexOf("\n");
+            if (nl >= 0) text = text.slice(nl + 1);
+          }
+        }
+      } finally {
+        fs.closeSync(fd);
+      }
+    } catch {
+    }
+    const events = analyzeCore.parseDebugLog(text);
+    const records = [];
+    const persist = persistEnabled();
+    if (persist) {
+      const n = Number.isInteger(args.sessions) && args.sessions > 0 ? args.sessions : 50;
+      for (const e of sessions.listSessions({ dir: sessionsDir }).slice(0, n)) {
+        const rec = sessions.readSession(e.id, { dir: sessionsDir });
+        if (rec) records.push(rec);
+      }
+    }
+    return analyzeCore.buildAnalysis(events, records, cfg, { logPath, debugEnabled, sessionsPersist: persist });
+  }
   async function call(name, args) {
     const namedExpert = EXPERTS.includes(name) ? name : void 0;
     const argExpert = typeof args.expert === "string" ? args.expert : void 0;
@@ -4818,6 +5106,9 @@ function buildServer({ providers, getConfig, getConfigError, sessionsDir, notify
       const result = await askOne(p, withPersona(req, expert), { logger: currentLogger(), tool: "ask-one", cache: resultCache });
       return jsonResult({ result });
     }
+    if (name === "analyze") {
+      return jsonResult(runAnalyze(args));
+    }
     if (name === "ask-all") {
       const { payload, parts } = await runAskAll(req, expert);
       const sid = persistRun("ask-all", req, expert, parts);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antonbabenko/deliberation-mcp",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "description": "Deliberation for Claude Code and any MCP host - GPT, Gemini, Grok, and OpenRouter expert subagents.",
   "mcpName": "io.github.antonbabenko/deliberation",
   "repository": { "type": "git", "url": "git+https://github.com/antonbabenko/deliberation.git", "directory": "server/mcp" },