@algosuite/vo-mcp 0.2.0-beta.49 → 0.2.0-beta.50

package/README.md

@@ -1,5 +1,7 @@
 # @algosuite/vo-mcp
 
+> **Architecture mandate (ADR-004, 2026-08-16): thin runner, cloud brain.** This package must shrink to a thin executor + shim — spawn the agent, manage worktrees/pushes, hold credentials, carry the local half of the MCP transport. Prompt composition, routing, watcher/merge/repair decisions, policy tables and the consensus engine belong in `cloud-run/vo-control-plane` / `cloud-run/vo-moat-plane`, not here (this package is on the PUBLIC npm registry). Fixes may land here when that is the fastest way to unblock the loop, but every decision-making module in this bundle is migration debt: record it in the ADR-004 ledger and move it to the plane (HQ roadmap Phase 11). Do not add new decision logic here without a ledger row.
+
 AlgoHQ MCP server — the open protocol surface that exposes HQ's consensus and ratchet tool family to any MCP-capable LLM client (Claude Code, Claude Desktop, Cursor, Continue, Codex, etc.).
 
 The live AlgoHQ whiteboard is available to every MCP client through

package/dist/cli.js

@@ -1023,7 +1023,16 @@ function assertWithinByteCap(toolName, fieldName, value, maxBytes) {
     );
   }
 }
+function subjectFromEnv(env = process.env) {
+  const code_task_id = (env["VO_CODE_TASK_ID"] ?? "").trim().slice(0, 120);
+  const repo = (env["VO_CODE_TASK_REPO"] ?? "").trim();
+  const subject = {};
+  if (code_task_id) subject.code_task_id = code_task_id;
+  if (repo && REPO_RE.test(repo) && repo.length <= 200) subject.repo = repo;
+  return subject.code_task_id || subject.repo ? subject : null;
+}
 function buildBaseEvent(args) {
+  const subject = args.subject === void 0 ? subjectFromEnv() : args.subject;
   return {
     schema_version: 1,
     event_id: args.eventId ?? randomUUID(),
@@ -1049,7 +1058,12 @@ function buildBaseEvent(args) {
     downstream_outcome: null,
     vo_mcp_version: VO_MCP_VERSION,
     consensus_engine_version: null,
-    cache_hit: false
+    cache_hit: false,
+    // OMIT the key when there is no subject (rather than `subject: null`): the
+    // ingest schema is `.strict()`, so an event with no subject stays valid on a
+    // sink that has not learned the field yet — only subject-carrying events
+    // depend on the sink being current (deploy ordering: sink before producer).
+    ...subject ? { subject } : {}
   };
 }
 function jsonContent(value) {
@@ -1115,6 +1129,16 @@ function aggregateEventTokenUsage(src, engineUsage) {
     total_cost_usd: anyCost ? costMicroUsd / 1e6 : null
   };
 }
+function trajectoryFromEngine(result, known = {}) {
+  const rounds = typeof result.token_usage?.rounds_counted === "number" && Number.isInteger(result.token_usage.rounds_counted) && result.token_usage.rounds_counted >= 0 ? result.token_usage.rounds_counted : null;
+  const called = result.fan_out_diagnostics?.models_called;
+  const turns = typeof called === "number" && Number.isInteger(called) && called >= 0 ? called : rounds !== null && rounds > 0 ? result.per_model_verdicts.length * rounds : null;
+  const sourceGrounded = result.citation_grade !== void 0 || result.low_confidence_sources !== void 0;
+  const tool_calls = typeof known.tool_calls === "number" && Number.isInteger(known.tool_calls) && known.tool_calls >= 0 ? known.tool_calls : sourceGrounded ? null : 0;
+  if (rounds === null && turns === null && tool_calls === null) return {};
+  const trajectory = { rounds, turns, tool_calls };
+  return { trajectory };
+}
 function toEventSynthesizedVerdict(src) {
   return {
     verdict: src.verdict,
@@ -1122,12 +1146,13 @@ function toEventSynthesizedVerdict(src) {
     reasoning_excerpt: sanitizeExcerpt(src.reasoning_excerpt)
   };
 }
-var VO_MCP_VERSION;
+var VO_MCP_VERSION, REPO_RE;
 var init_common = __esm({
   "src/tools/common.ts"() {
     "use strict";
     init_events_writer();
     VO_MCP_VERSION = readVoMcpVersion();
+    REPO_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/u;
   }
 });
 
@@ -2431,9 +2456,9 @@ var init_sync_config = __esm({
 });
 
 // src/cli.ts
-import { homedir as homedir8, hostname as hostname2 } from "node:os";
+import { homedir as homedir9, hostname as hostname2 } from "node:os";
 import { randomUUID as randomUUID6 } from "node:crypto";
-import { join as join14 } from "node:path";
+import { join as join15 } from "node:path";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/server.ts
@@ -2815,7 +2840,8 @@ async function handleCheckHollowTest(deps, rawInput, signal) {
     consensus_confidence: engineResult.synthesized_verdict.confidence,
     duration_ms: engineResult.duration_ms,
     consensus_engine_version: engineResult.engine_version,
-    ...aggregateEventTokenUsage(engineResult.per_model_verdicts, engineResult.token_usage)
+    ...aggregateEventTokenUsage(engineResult.per_model_verdicts, engineResult.token_usage),
+    ...trajectoryFromEngine(engineResult)
   };
   const payload = {
     verdict: engineResult.synthesized_verdict.verdict,
@@ -2999,7 +3025,8 @@ async function handleVerifyAnswer(deps, rawInput, signal) {
     consensus_confidence: engineResult.synthesized_verdict.confidence,
     duration_ms: engineResult.duration_ms,
     consensus_engine_version: engineResult.engine_version,
-    ...aggregateEventTokenUsage(engineResult.per_model_verdicts, engineResult.token_usage)
+    ...aggregateEventTokenUsage(engineResult.per_model_verdicts, engineResult.token_usage),
+    ...trajectoryFromEngine(engineResult)
   };
   const payload = {
     verdict: engineResult.synthesized_verdict.verdict,
@@ -3268,7 +3295,8 @@ async function handleConsensusJudgment(deps, rawInput, signal) {
     consensus_engine_version: engineResult.engine_version,
     per_model_verdicts: perModelForEvent,
     synthesized_verdict: synthForEvent,
-    ...aggregateEventTokenUsage(engineResult.per_model_verdicts, engineResult.token_usage)
+    ...aggregateEventTokenUsage(engineResult.per_model_verdicts, engineResult.token_usage),
+    ...trajectoryFromEngine(engineResult)
   };
   const payload = {
     verdict: engineResult.synthesized_verdict.verdict,
@@ -3483,7 +3511,8 @@ async function handleArchitectureReview(deps, rawInput, signal) {
     consensus_confidence: engineResult.synthesized_verdict.confidence,
     duration_ms: engineResult.duration_ms,
     consensus_engine_version: engineResult.engine_version,
-    ...aggregateEventTokenUsage(engineResult.per_model_verdicts, engineResult.token_usage)
+    ...aggregateEventTokenUsage(engineResult.per_model_verdicts, engineResult.token_usage),
+    ...trajectoryFromEngine(engineResult)
   };
   const escalationRequired = engineResult.escalation_required === true || engineResult.escalation_required === void 0 && engineResult.synthesized_verdict.dissent_summary !== null;
   const escalationReason = engineResult.escalation_reason ?? engineResult.synthesized_verdict.dissent_summary ?? "";
@@ -4971,7 +5000,8 @@ Produce the JSON dispatch plan now.`;
     consensus_engine_version: engineResult.engine_version,
     per_model_verdicts: toEventPerModelVerdicts(engineResult.per_model_verdicts),
     synthesized_verdict: toEventSynthesizedVerdict(engineResult.synthesized_verdict),
-    ...aggregateEventTokenUsage(engineResult.per_model_verdicts, engineResult.token_usage)
+    ...aggregateEventTokenUsage(engineResult.per_model_verdicts, engineResult.token_usage),
+    ...trajectoryFromEngine(engineResult)
   };
   deps.events.append(enrichedEvent);
   return jsonContent(envelope);
@@ -5673,6 +5703,7 @@ async function handleRejectAndRetry(deps, rawInput, _signal) {
 init_common();
 var TOOL_NAME18 = "vo_review_merge";
 var LIST_PATH = "/api/v1/admin/pr/list";
+var DEFAULT_REVIEW_REPO = "Algosuite-ai/Nexus";
 var ENGINE_GATE = "final-deep-verify";
 var EVENT_GATE = "merge-review";
 var UNAVAILABLE_REASON = "vo_review_merge needs cloud mode to fetch PR context \u2014 set VO_CONTROL_PLANE_URL + VO_CONTROL_PLANE_ADMIN_TOKEN in the MCP env. (It is read-only; it never merges.)";
@@ -5737,6 +5768,11 @@ async function handleReviewMerge(deps, rawInput, signal) {
   if (rawInput.notes !== void 0) normalizedInput.notes = rawInput.notes;
   const inputJson = JSON.stringify(normalizedInput);
   const key = deps.cache.keyFor(TOOL_NAME18, normalizedInput);
+  const subject = {
+    ...subjectFromEnv() ?? {},
+    repo: subjectFromEnv()?.repo ?? DEFAULT_REVIEW_REPO,
+    pr_number: prNumber
+  };
   const baseEvent = buildBaseEvent({
     tool: TOOL_NAME18,
     gateType: EVENT_GATE,
@@ -5744,7 +5780,8 @@ async function handleReviewMerge(deps, rawInput, signal) {
     inputExcerpt: inputJson.slice(0, 300),
     inputSizeBytes: bytesOf(inputJson),
     session: deps.session,
-    now: deps.now()
+    now: deps.now(),
+    subject
   });
   const emit = (payload2, eventExtra) => {
     deps.events.append(eventExtra ? { ...baseEvent, ...eventExtra } : baseEvent);
@@ -5846,7 +5883,8 @@ async function handleReviewMerge(deps, rawInput, signal) {
     consensus_engine_version: result.engine_version,
     per_model_verdicts: perModel,
     synthesized_verdict: synth,
-    ...aggregateEventTokenUsage(result.per_model_verdicts, result.token_usage)
+    ...aggregateEventTokenUsage(result.per_model_verdicts, result.token_usage),
+    ...trajectoryFromEngine(result)
   });
 }
 
@@ -8396,6 +8434,109 @@ function createConsensusFallbackClient(primary, fallback, options = {}) {
   };
 }
 
+// src/consensus/shadow-client.ts
+import { appendFileSync as appendFileSync2, chmodSync as chmodSync4, mkdirSync as mkdirSync8, renameSync, statSync as statSync7 } from "node:fs";
+import { homedir as homedir8 } from "node:os";
+import { dirname as dirname7, join as join14 } from "node:path";
+var DEFAULT_SHADOW_TIMEOUT_MS = 2e4;
+var SHADOW_RECEIPT_MAX_BYTES = 20 * 1024 * 1024;
+function defaultShadowReceiptPath(env = process.env) {
+  const p = (env["VO_MCP_MOAT_SHADOW_PATH"] ?? "").trim();
+  return p || join14(homedir8(), ".claude", "vo-mcp-moat-shadow.jsonl");
+}
+function appendShadowReceipt(receipt, path3 = defaultShadowReceiptPath()) {
+  try {
+    mkdirSync8(dirname7(path3), { recursive: true, mode: 448 });
+    try {
+      if (statSync7(path3).size > SHADOW_RECEIPT_MAX_BYTES) renameSync(path3, `${path3}.1`);
+    } catch {
+    }
+    appendFileSync2(path3, `${JSON.stringify(receipt)}
+`, "utf8");
+    try {
+      chmodSync4(path3, 384);
+    } catch {
+    }
+  } catch {
+  }
+}
+function summarize(result) {
+  if (result.ok) {
+    return {
+      ok: true,
+      verdict: result.synthesized_verdict.verdict,
+      confidence: result.synthesized_verdict.confidence,
+      ...result.receipt_id ? { receipt_id: result.receipt_id } : {}
+    };
+  }
+  return { ok: false, reason: result.reason };
+}
+async function runMoat(shadow, request, timeoutMs, linkCallerSignal) {
+  const callerSignal = linkCallerSignal ? request.signal : void 0;
+  if (callerSignal?.aborted) return { ok: false, reason: CANCELLED_REASON };
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  const onCallerAbort = () => controller.abort();
+  callerSignal?.addEventListener("abort", onCallerAbort, { once: true });
+  try {
+    const { signal: _ignored, ...rest } = request;
+    void _ignored;
+    return await shadow.run({ ...rest, signal: controller.signal });
+  } catch (err) {
+    return { ok: false, reason: `moat-shadow-threw: ${err instanceof Error ? err.message : String(err)}`.slice(0, 200) };
+  } finally {
+    clearTimeout(timer);
+    callerSignal?.removeEventListener("abort", onCallerAbort);
+  }
+}
+function createConsensusShadowClient(primary, shadow, options = {}) {
+  const authoritative = options.authoritative === true;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_SHADOW_TIMEOUT_MS;
+  const now = options.now ?? (() => Date.now());
+  const random = options.random ?? Math.random;
+  const samplePct = Math.min(100, Math.max(0, options.samplePct ?? 100));
+  const onReceipt = options.onReceipt ?? ((r) => appendShadowReceipt(r));
+  function receiptFor(request, local, moat, startedAt) {
+    const l = summarize(local);
+    const m = summarize(moat);
+    return {
+      ts: new Date(now()).toISOString(),
+      gate_type: request.gate_type,
+      mode: authoritative ? "authoritative" : "shadow",
+      local: l,
+      moat: m,
+      agree: l.ok && m.ok ? l.verdict === m.verdict : null,
+      duration_ms: Math.max(0, now() - startedAt)
+    };
+  }
+  return {
+    async run(request) {
+      const startedAt = now();
+      const primaryResult = await primary.run(request);
+      if (request.signal?.aborted || !primaryResult.ok && primaryResult.reason === CANCELLED_REASON) {
+        return primaryResult;
+      }
+      if (!primaryResult.ok || primaryResult.receipt_id) return primaryResult;
+      if (authoritative) {
+        const moatResult = await runMoat(shadow, request, timeoutMs, true);
+        try {
+          onReceipt(receiptFor(request, primaryResult, moatResult, startedAt));
+        } catch {
+        }
+        return moatResult.ok ? moatResult : primaryResult;
+      }
+      if (samplePct < 100 && random() * 100 >= samplePct) return primaryResult;
+      void runMoat(shadow, request, timeoutMs, false).then((moatResult) => {
+        try {
+          onReceipt(receiptFor(request, primaryResult, moatResult, startedAt));
+        } catch {
+        }
+      });
+      return primaryResult;
+    }
+  };
+}
+
 // src/consensus/local-credential-env.ts
 import { createRequire as createRequire2 } from "node:module";
 var require2 = createRequire2(import.meta.url);
@@ -8629,7 +8770,7 @@ init_common();
 function defaultCacheDbPath() {
   const env = process.env["VO_MCP_DB_PATH"];
   if (env && env.length > 0) return env;
-  return join14(homedir8(), ".claude", "vo-mcp-cache.db");
+  return join15(homedir9(), ".claude", "vo-mcp-cache.db");
 }
 async function probeEngineVersion() {
   try {
@@ -8717,6 +8858,16 @@ async function main() {
     consensus = createConsensusFallbackClient(localConsensus, cloudConsensus, {
       onFallback: (reason) => console.error(`[vo-mcp] local consensus unavailable (${reason}); using cloud moat fallback`)
     });
+    const moatAuthoritative = process.env["VO_CONSENSUS_MOAT_AUTHORITATIVE"] === "1";
+    if (moatAuthoritative || process.env["VO_CONSENSUS_MOAT_SHADOW"] === "1") {
+      const pctRaw = Number(process.env["VO_CONSENSUS_MOAT_SHADOW_PCT"] ?? "100");
+      const samplePct = Number.isFinite(pctRaw) ? Math.min(100, Math.max(0, pctRaw)) : 100;
+      const shadowedLocal = createConsensusShadowClient(localConsensus, cloudConsensus, { authoritative: moatAuthoritative, samplePct });
+      consensus = createConsensusFallbackClient(shadowedLocal, cloudConsensus, {
+        onFallback: (reason) => console.error(`[vo-mcp] local consensus unavailable (${reason}); using cloud moat fallback`)
+      });
+      console.error(`[vo-mcp] moat ${moatAuthoritative ? "AUTHORITATIVE" : `SHADOW (${samplePct}%)`} active \u2014 local verdicts also reach the moat verify path (receipts: ${defaultShadowReceiptPath()})`);
+    }
   } else if (!testClient && cloudConsensus) {
     console.error("[vo-mcp] fewer than 2 linked local providers; cloud moat consensus active");
     consensus = cloudConsensus;
@@ -8785,12 +8936,12 @@ if (process.argv[2] === "login") {
   const sessionId = randomUUID6();
   const appendSyncLog = async (line) => {
     try {
-      const { appendFileSync: appendFileSync2, mkdirSync: mkdirSync8 } = await import("node:fs");
-      const { join: join15 } = await import("node:path");
-      const { homedir: homedir9 } = await import("node:os");
-      const dir = join15(homedir9(), ".claude");
-      mkdirSync8(dir, { recursive: true });
-      appendFileSync2(join15(dir, "vo-mcp-sync.log"), `${line}
+      const { appendFileSync: appendFileSync3, mkdirSync: mkdirSync9 } = await import("node:fs");
+      const { join: join16 } = await import("node:path");
+      const { homedir: homedir10 } = await import("node:os");
+      const dir = join16(homedir10(), ".claude");
+      mkdirSync9(dir, { recursive: true });
+      appendFileSync3(join16(dir, "vo-mcp-sync.log"), `${line}
 `, "utf8");
     } catch {
     }