@algosuite/vo-mcp 0.2.0-beta.7 → 0.2.0-beta.9

package/README.md

@@ -2,10 +2,34 @@
 
 Virtual Office MCP server — the open protocol surface that exposes VO's consensus and ratchet tool family to any MCP-capable LLM client (Claude Code, Claude Desktop, Cursor, Continue, Codex, etc.).
 
-**Status:** Phase 2. Stdio transport. **20 tools registered** (source of truth: `src/server.ts` `buildToolRegistry()`). The static-ratchet tools (`vo_check_assertion_strength`, `vo_check_ratchets`) run locally today; the consensus-routed tools fall back to `{ verdict: "unimplemented", ... }` until engine credentials are present; the heal-family, PR-admin, and session-state tools forward to the vo-control-plane admin proxy in cloud mode. `vo_review_merge` is a **read-only consensus pre-merge review** (the verify-before-act gate for the Command Center — never merges). The shape is stable; the institutional-knowledge content is loaded from closed packages.
+The live AlgoHQ whiteboard is available to every MCP client through
+`hq_whiteboard_post` and `hq_whiteboard_read`. Both use the scoped credential
+created by `vo-mcp login`; tenant/operator ownership is derived by the control
+plane and cannot be widened by tool input. The control plane admits scoped
+credentials only for operator IDs on its internal `HQ_WHITEBOARD_OPERATOR_IDS`
+allowlist; arbitrary self-serve tenants cannot read or write the shared fleet board.
+
+**Status:** Phase 2. Stdio transport. **26 tools registered** (source of truth: `src/server.ts` `buildToolRegistry()`). The static-ratchet tools (`vo_check_assertion_strength`, `vo_check_ratchets`) run locally today; the consensus-routed tools fall back to `{ verdict: "unimplemented", ... }` until engine credentials are present; the heal-family, PR-admin, session-state, and AlgoHQ whiteboard tools forward to the control plane in cloud mode. `vo_review_merge` is a **read-only consensus pre-merge review** (the verify-before-act gate for the Command Center — never merges). The shape is stable; the institutional-knowledge content is loaded from closed packages.
 
 This package is intentionally **shell-only**. Per `docs/handoffs/vo-mcp-server-2026-05-21.md` §C-1: tool *definitions* (schemas, names, descriptions) ship openly. Tool *implementations* that encode institutional knowledge (specific ratchet thresholds, consensus prompt content, architectural-defaults knowledge base) live behind the cloud or in closed companion packages.
 
+## Install and refresh client configuration
+
+`vo-mcp install` safely registers the same required `algohq` MCP server in
+Claude Desktop, Claude Code, and Codex (`~/.codex/config.toml`), then offers
+pairing and runner auto-start. Existing client settings and comments are
+preserved, and every changed config is backed up first.
+
+To refresh client configuration on an already-paired runner without touching
+its keychain credential or auto-start service, use the noninteractive form:
+
+```sh
+vo-mcp install --config-only
+```
+
+Restart the MCP clients and runner after updating, then use
+[AlgoHQ](https://algosuite.ai/algohq) to dispatch work.
+
 ## Tools
 
 | Name | Phase 1 status | Description |
@@ -44,7 +68,7 @@ pnpm test            # vitest run
 
 The integration test (`test/integration/stdio-roundtrip.test.ts`) spawns the built CLI, exchanges JSON-RPC over stdio, and asserts:
 
-- `initialize` + `tools/list` returns the 20 expected tools.
+- `initialize` + `tools/list` returns the 26 expected tools.
 - `vo_check_assertion_strength` runs end-to-end and writes a JSONL event line.
 - A repeat call with identical input hits the cache (`cache.hit = true`).
 - `vo_consensus_judgment` returns `unimplemented` and still writes its event line.

package/bin/vo-mcp

@@ -5,10 +5,11 @@
  * Usage:
  *   vo-mcp                                  # MCP stdio server (default)
  *   vo-mcp install                          # one-command installer
+ *   vo-mcp install --config-only            # refresh Claude + Codex MCP config only
  *   vo-mcp update                           # update MCP + runner package
  *   vo-mcp login                            # credential login (browser loopback)
  *   vo-mcp pair                             # device-code pairing (enter a code in the web)
- *   vo-mcp runner                           # agent runner daemon
+ *   vo-mcp runner                           # supervised agent runner
  *   vo-mcp runner --install-autostart       # register runner to start at login
  *   vo-mcp runner --uninstall-autostart     # remove auto-start registration
  */
@@ -31,9 +32,11 @@ if (command === 'install') {
     import('../dist/autostart-cli.js').then((m) => m.installAutostartCli());
   } else if (subcommand === '--uninstall-autostart') {
     import('../dist/autostart-cli.js').then((m) => m.uninstallAutostartCli());
-  } else {
-    // Bring-your-own runner daemon (bundled by scripts/bundle.mjs into dist/).
+  } else if (process.argv.includes('--once') || process.argv.includes('--status') || process.argv.includes('--version') || process.argv.includes('-v')) {
+    // Direct diagnostic/one-shot mode; remote maintenance uses the supervisor.
     import('../dist/runner-cli.js');
+  } else {
+    import('../dist/runner-supervisor.js');
   }
 } else {
   // Default: MCP stdio server

package/dist/cli.js

@@ -5592,6 +5592,149 @@ async function handlePrivateKnowledgeContext(_deps, rawInput, _signal, fetchFn =
   return jsonContent({ tool: CONTEXT_TOOL_NAME, schema_version: 1, payload });
 }
 
+// src/tools/hq/whiteboard.ts
+init_auth_token_source();
+init_credential_store();
+init_common();
+var POST_TOOL_NAME = "hq_whiteboard_post";
+var READ_TOOL_NAME = "hq_whiteboard_read";
+var postDescription = "Post an append-only coordination note to the live AlgoHQ whiteboard. Uses the scoped credential from vo-mcp login; operator and tenant ownership are derived by the server.";
+var readDescription = "Read recent coordination notes from the caller's live AlgoHQ whiteboard. Uses the scoped credential from vo-mcp login and cannot widen tenant scope.";
+var postInputSchema = {
+  type: "object",
+  properties: {
+    from: { type: "string", minLength: 1, maxLength: 100, description: "Agent/session display name." },
+    type: { type: "string", minLength: 1, maxLength: 64, description: "Message kind, such as intent, worklog, blocker, or completion." },
+    content: { type: "string", minLength: 1, maxLength: 500, description: "Short coordination note." },
+    targetAgent: { type: "string", maxLength: 100 },
+    tester: { type: "string", maxLength: 100 },
+    tier: { type: "string", maxLength: 32 }
+  },
+  required: ["from", "type", "content"],
+  additionalProperties: false
+};
+var readInputSchema = {
+  type: "object",
+  properties: {
+    limit: { type: "integer", minimum: 1, maximum: 100, default: 25 },
+    since: { type: "string", description: "Optional ISO-8601 lower bound." },
+    type: { type: "string", minLength: 1, maxLength: 64 }
+  },
+  additionalProperties: false
+};
+function resolveTimeoutMs() {
+  const parsed = Number(process.env["HQ_WHITEBOARD_TIMEOUT_MS"]);
+  return Number.isFinite(parsed) && parsed >= 10 && parsed <= 12e4 ? parsed : 1e4;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function onlyKeys(value, allowed) {
+  return Object.keys(value).every((key) => allowed.includes(key));
+}
+function isBoundedString(value, min, max) {
+  return typeof value === "string" && value.trim().length >= min && value.trim().length <= max;
+}
+function parsePostInput(value) {
+  if (!isRecord(value) || !onlyKeys(value, ["from", "type", "content", "targetAgent", "tester", "tier"])) return null;
+  if (!isBoundedString(value["from"], 1, 100)) return null;
+  if (!isBoundedString(value["type"], 1, 64) || !/^[a-zA-Z0-9_-]+$/.test(value["type"].trim())) return null;
+  if (!isBoundedString(value["content"], 1, 500)) return null;
+  for (const [key, max] of [["targetAgent", 100], ["tester", 100], ["tier", 32]]) {
+    if (value[key] !== void 0 && !isBoundedString(value[key], 0, max)) return null;
+  }
+  return {
+    from: value["from"].trim(),
+    type: value["type"].trim(),
+    content: value["content"].trim(),
+    ...typeof value["targetAgent"] === "string" ? { targetAgent: value["targetAgent"].trim() } : {},
+    ...typeof value["tester"] === "string" ? { tester: value["tester"].trim() } : {},
+    ...typeof value["tier"] === "string" ? { tier: value["tier"].trim() } : {}
+  };
+}
+function parseReadInput(value) {
+  if (!isRecord(value) || !onlyKeys(value, ["limit", "since", "type"])) return null;
+  if (value["limit"] !== void 0 && (!Number.isInteger(value["limit"]) || Number(value["limit"]) < 1 || Number(value["limit"]) > 100)) return null;
+  if (value["since"] !== void 0 && (typeof value["since"] !== "string" || Number.isNaN(Date.parse(value["since"])))) return null;
+  if (value["type"] !== void 0 && !isBoundedString(value["type"], 1, 64)) return null;
+  return {
+    ...typeof value["limit"] === "number" ? { limit: value["limit"] } : {},
+    ...typeof value["since"] === "string" ? { since: value["since"] } : {},
+    ...typeof value["type"] === "string" ? { type: value["type"].trim() } : {}
+  };
+}
+async function resolveCloud(fetchFn) {
+  const url = process.env["VO_CONTROL_PLANE_URL"]?.trim().replace(/\/$/, "");
+  if (!url) return null;
+  try {
+    const source = createAuthTokenSourceFromEnv(process.env, fetchFn, () => readStoredCredential(process.env));
+    const token = await source?.getToken();
+    return token ? { url, token } : null;
+  } catch {
+    return null;
+  }
+}
+async function callWhiteboard(method, bodyOrQuery, signal, fetchFn = fetch) {
+  const cloud = await resolveCloud(fetchFn);
+  if (!cloud) {
+    return {
+      ok: false,
+      error: "hq_whiteboard_not_configured",
+      message: "Set VO_CONTROL_PLANE_URL and run vo-mcp login to install a scoped HQ credential."
+    };
+  }
+  const timeoutSignal = AbortSignal.timeout(resolveTimeoutMs());
+  const requestSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+  const query = new URLSearchParams();
+  if (method === "GET") {
+    const input = bodyOrQuery;
+    query.set("limit", String(input.limit ?? 25));
+    if (input.since) query.set("since", input.since);
+    if (input.type) query.set("type", input.type);
+  }
+  try {
+    const response = await fetchFn(
+      `${cloud.url}/api/v1/hq/whiteboard/messages${query.size ? `?${query}` : ""}`,
+      {
+        method,
+        headers: {
+          Authorization: `Bearer ${cloud.token}`,
+          ...method === "POST" ? { "Content-Type": "application/json" } : {}
+        },
+        ...method === "POST" ? { body: JSON.stringify(bodyOrQuery) } : {},
+        signal: requestSignal
+      }
+    );
+    const text = await response.text();
+    let payload;
+    try {
+      payload = JSON.parse(text);
+    } catch {
+      payload = { ok: false, error: "invalid_response", message: text.slice(0, 200) };
+    }
+    if (!response.ok) {
+      return { ok: false, error: "hq_whiteboard_http_error", status: response.status, response: payload };
+    }
+    return payload;
+  } catch (error) {
+    return {
+      ok: false,
+      error: signal?.aborted ? "cancelled" : timeoutSignal.aborted ? "hq_whiteboard_timeout" : "hq_whiteboard_unreachable",
+      message: error instanceof Error ? error.message.slice(0, 200) : String(error).slice(0, 200)
+    };
+  }
+}
+async function handleHqWhiteboardPost(_deps, rawInput, signal) {
+  const input = parsePostInput(rawInput);
+  if (!input) throw invalidParams(POST_TOOL_NAME, "requires from, type, and 1-500 character content; unknown fields are rejected");
+  return jsonContent(await callWhiteboard("POST", input, signal));
+}
+async function handleHqWhiteboardRead(_deps, rawInput, signal) {
+  const input = parseReadInput(rawInput);
+  if (!input) throw invalidParams(READ_TOOL_NAME, "limit must be 1-100, since must be ISO-8601, and unknown fields are rejected");
+  return jsonContent(await callWhiteboard("GET", input, signal));
+}
+
 // src/server.ts
 function buildToolRegistry() {
   return {
@@ -5786,6 +5929,22 @@ function buildToolRegistry() {
         inputSchema: contextInputSchema
       },
       handler: handlePrivateKnowledgeContext
+    },
+    [POST_TOOL_NAME]: {
+      definition: {
+        name: POST_TOOL_NAME,
+        description: postDescription,
+        inputSchema: postInputSchema
+      },
+      handler: handleHqWhiteboardPost
+    },
+    [READ_TOOL_NAME]: {
+      definition: {
+        name: READ_TOOL_NAME,
+        description: readDescription,
+        inputSchema: readInputSchema
+      },
+      handler: handleHqWhiteboardRead
     }
   };
 }
@@ -6280,6 +6439,9 @@ function createClaimClassifier(model, options = {}) {
   };
 }
 
+// src/constants/consensus-models.ts
+var XAI_CONSENSUS_MODEL = "grok-4.5";
+
 // src/consensus/engine-client.ts
 function raceAbort(signal) {
   return new Promise((_, reject) => {
@@ -6430,6 +6592,7 @@ var DEFAULT_MODELS = {
   // Flash is also ~10x cheaper. 2026-06-02.
   google: "gemini-2.5-flash",
   deepseek: "deepseek-chat",
+  xai: XAI_CONSENSUS_MODEL,
   meta: META_CONSENSUS_MODEL
 };
 function probeProviders(env = process.env) {
@@ -6438,6 +6601,7 @@ function probeProviders(env = process.env) {
   if ((env["OPENAI_API_KEY"] ?? "").trim().length > 0) out.push("openai");
   if ((env["GOOGLE_API_KEY"] ?? "").trim().length > 0) out.push("google");
   if ((env["DEEPSEEK_API_KEY"] ?? "").trim().length > 0) out.push("deepseek");
+  if ((env["XAI_API_KEY"] ?? "").trim().length > 0) out.push("xai");
   if ((env[META_MODEL_API_KEY_ENV] ?? "").trim().length > 0 || (env[META_MODEL_API_KEY_ALIAS] ?? "").trim().length > 0) out.push("meta");
   return out;
 }
@@ -6461,7 +6625,7 @@ async function loadFactoryAndCallers(injectedEngine, injectedShared) {
       return { ok: false, reason: ENGINE_UNAVAILABLE_REASONS.FUNCTIONS_SHARED_NOT_INSTALLED };
     }
   }
-  if (sharedMod === null || typeof sharedMod !== "object" || typeof sharedMod.callAnthropicWithMetrics !== "function" || typeof sharedMod.callOpenAIWithMetrics !== "function" || typeof sharedMod.callGeminiWithMetrics !== "function") {
+  if (sharedMod === null || typeof sharedMod !== "object" || typeof sharedMod.callAnthropicWithMetrics !== "function" || typeof sharedMod.callOpenAIWithMetrics !== "function" || typeof sharedMod.callGeminiWithMetrics !== "function" || typeof sharedMod.callXAIWithMetrics !== "function") {
     return { ok: false, reason: ENGINE_UNAVAILABLE_REASONS.FUNCTIONS_SHARED_NOT_INSTALLED };
   }
   return {
@@ -6485,6 +6649,7 @@ async function tryCreateEngineConsensusClientFromEnvAsync(options = {}) {
     openai: loaded.shared.callOpenAIWithMetrics,
     google: loaded.shared.callGeminiWithMetrics,
     deepseek: loaded.shared.callDeepSeekWithMetrics,
+    xai: loaded.shared.callXAIWithMetrics,
     meta: options.metaCaller ?? callMetaWithMetrics
   };
   const modelByProvider = {
@@ -6492,6 +6657,7 @@ async function tryCreateEngineConsensusClientFromEnvAsync(options = {}) {
     openai: options.models?.openai ?? DEFAULT_MODELS.openai,
     google: options.models?.google ?? DEFAULT_MODELS.google,
     deepseek: options.models?.deepseek ?? DEFAULT_MODELS.deepseek,
+    xai: options.models?.xai ?? DEFAULT_MODELS.xai,
     meta: options.models?.meta ?? DEFAULT_MODELS.meta
   };
   const adapterEnv = !(env[META_MODEL_API_KEY_ENV] ?? "").trim() && (env[META_MODEL_API_KEY_ALIAS] ?? "").trim() ? { ...env, [META_MODEL_API_KEY_ENV]: env[META_MODEL_API_KEY_ALIAS] } : env;
@@ -6658,6 +6824,69 @@ function tryCreateMoatConsensusClientFromEnv(env = process.env, fetchFn) {
   });
 }
 
+// src/consensus/fallback-client.ts
+var MIN_VALID_LOCAL_VERDICTS = 2;
+var INSUFFICIENT_LOCAL_VERDICTS_REASON = "local-panel-insufficient-valid-verdicts";
+function createConsensusFallbackClient(primary, fallback, options = {}) {
+  return {
+    async run(request) {
+      const primaryResult = await primary.run(request);
+      if (request.signal?.aborted || !primaryResult.ok && primaryResult.reason === CANCELLED_REASON) {
+        return primaryResult;
+      }
+      if (primaryResult.ok) {
+        const validVerdicts = primaryResult.per_model_verdicts.filter(
+          (verdict) => verdict.verdict !== "error"
+        );
+        if (validVerdicts.length >= MIN_VALID_LOCAL_VERDICTS) return primaryResult;
+        options.onFallback?.(INSUFFICIENT_LOCAL_VERDICTS_REASON);
+        return fallback.run(request);
+      }
+      options.onFallback?.(primaryResult.reason);
+      return fallback.run(request);
+    }
+  };
+}
+
+// src/consensus/local-credential-env.ts
+import { createRequire as createRequire2 } from "node:module";
+var require2 = createRequire2(import.meta.url);
+var KEY_SERVICE = "algosuite-vo";
+var KEYCHAIN_TARGETS = [
+  { account: "anthropic-api-key", envVar: "ANTHROPIC_API_KEY" },
+  { account: "openai-api-key", envVar: "OPENAI_API_KEY" },
+  { account: "xai-api-key", envVar: "XAI_API_KEY" },
+  { account: "meta-api-key", envVar: "MODEL_API_KEY" }
+];
+function loadEntryCtor() {
+  try {
+    return require2("@napi-rs/keyring").Entry ?? null;
+  } catch {
+    return null;
+  }
+}
+function readKey(EntryCtor, account) {
+  try {
+    return new EntryCtor(KEY_SERVICE, account).getPassword()?.trim() || null;
+  } catch {
+    return null;
+  }
+}
+function withLocalConsensusCredentials(baseEnv = process.env, options = {}) {
+  const env = { ...baseEnv };
+  if (!env.OPENAI_API_KEY?.trim() && env.CODEX_API_KEY?.trim()) {
+    env.OPENAI_API_KEY = env.CODEX_API_KEY;
+  }
+  const EntryCtor = options.EntryCtor === void 0 ? loadEntryCtor() : options.EntryCtor;
+  if (!EntryCtor) return env;
+  for (const target of KEYCHAIN_TARGETS) {
+    if (env[target.envVar]?.trim()) continue;
+    const key = readKey(EntryCtor, target.account);
+    if (key) env[target.envVar] = key;
+  }
+  return env;
+}
+
 // src/cloud/login.ts
 init_credential_store();
 import { createServer as createServer2 } from "node:http";
@@ -6921,11 +7150,23 @@ async function main() {
   const ratchets = createStubRatchetClient();
   const testModule = process.env["VO_MCP_TEST_ENGINE_MODULE"];
   const testClient = testModule !== void 0 && testModule.length > 0 ? await loadTestEngineClient(testModule) : null;
+  const localEnv = withLocalConsensusCredentials();
+  const localProviders = probeProviders(localEnv);
+  for (const key of ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GOOGLE_API_KEY", "DEEPSEEK_API_KEY", "XAI_API_KEY", "MODEL_API_KEY"]) {
+    if (!process.env[key] && localEnv[key]) process.env[key] = localEnv[key];
+  }
+  const localConsensus = tryCreateEngineConsensusClientFromEnv({ envSource: localEnv });
   const cloudConsensus = testClient ? null : tryCreateMoatConsensusClientFromEnv();
-  if (cloudConsensus) {
-    console.error("[vo-mcp] cloud consensus active \u2014 verdicts via vo-moat-plane (no local model keys)");
+  let consensus = testClient ?? localConsensus;
+  if (!testClient && cloudConsensus && localProviders.length >= 2) {
+    console.error(`[vo-mcp] local-first consensus active (${localProviders.join(", ")}); cloud moat is fallback-only`);
+    consensus = createConsensusFallbackClient(localConsensus, cloudConsensus, {
+      onFallback: (reason) => console.error(`[vo-mcp] local consensus unavailable (${reason}); using cloud moat fallback`)
+    });
+  } else if (!testClient && cloudConsensus) {
+    console.error("[vo-mcp] fewer than 2 linked local providers; cloud moat consensus active");
+    consensus = cloudConsensus;
   }
-  const consensus = testClient ?? cloudConsensus ?? tryCreateEngineConsensusClientFromEnv();
   let adminCallables = null;
   try {
     adminCallables = buildAdminCallableClientFromEnv();