@popoverinstall/cli 0.8.1 → 0.9.0

package/plugin/mcp/index.mjs

@@ -1,355 +1,585 @@
-#!/usr/bin/env node
-// Popover MCP server — lets an agent see and ask its teammates' agents.
-//
-// Implemented directly against the JSON-RPC stdio protocol rather than the MCP SDK. The
-// plugin is distributed through a marketplace and installed into a cache directory where
-// dependency installation is conditional and can fail; a server with zero dependencies
-// simply cannot fail that way. The protocol surface we need is small — initialize,
-// tools/list, tools/call — so the SDK buys us little here.
-//
-// All real work happens in the daemon. This process is a thin bridge to it.
-
-import { readFileSync } from "node:fs";
-import { callerSessionId, request } from "../scripts/_ipc.mjs";
-
-const PROTOCOL_VERSION = "2025-06-18";
-
-// Read from the plugin manifest, which Claude Code copies into its cache alongside this
-// file — so the relative path survives the severing copy that breaks everything else.
-const SERVER_INFO = {
-  name: "popover",
-  version: JSON.parse(
-    readFileSync(new URL("../.claude-plugin/plugin.json", import.meta.url), "utf8"),
-  ).version,
-};
-
-
-const TOOLS = [
-  {
-    name: "team_list",
-    description:
-      "List your teammates' currently-active Claude Code agents in THIS repo: who owns " +
-      "each one, what it is doing right now, and its short handle (e.g. B1). Only agents " +
-      "working in the same repository as you are visible — agents your teammates are " +
-      "running in other repos are not listed and cannot be asked. Use this before " +
-      "team_ask to find out which agent to ask. Read-only.",
-    inputSchema: { type: "object", properties: {}, additionalProperties: false },
-    annotations: { readOnlyHint: true, openWorldHint: true, title: "List team agents" },
-  },
-  {
-    name: "team_ask",
-    description:
-      "Ask a teammate's Claude Code agent a question and wait for the answer. A " +
-      "read-only copy of that agent answers from its full accumulated context; the " +
-      "teammate's live session is never interrupted or modified. Use this when a " +
-      "teammate's agent already knows something that would take you a long time to " +
-      "work out — why a decision was made, what they already ruled out, how a service " +
-      "they own behaves. Only agents working in the same repository as you can be asked. " +
-      "Answering costs the teammate tokens and takes up to ~90s, so ask one well-formed " +
-      "question rather than several exploratory ones.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        target: {
-          type: "string",
-          description:
-            "Which agent to ask: a handle from team_list such as 'B1', or a teammate's " +
-            "name, or a repo name.",
-        },
-        question: {
-          type: "string",
-          description:
-            "A self-contained question. The answering agent has none of your " +
-            "conversation's context, so expand pronouns and vague references.",
-        },
-        timeout_seconds: {
-          type: "number",
-          description: "How long to wait for an answer. Default 90, max 300.",
-          minimum: 5,
-          maximum: 300,
-        },
-      },
-      required: ["target", "question"],
-      additionalProperties: false,
-    },
-    annotations: { readOnlyHint: true, openWorldHint: true, title: "Ask a teammate's agent" },
-  },
-  {
-    name: "team_tell",
-    description:
-      "Send a short heads-up to a teammate's agent working in this repo. Unlike team_ask " +
-      "there is no answer: the message is delivered into that agent's context before its " +
-      "next prompt, and nothing comes back. Use it for facts about shared state that would " +
-      "otherwise cause a collision — \"the migration is applied on prod\", \"I am rewriting " +
-      "globals.css, leave it alone\". Do not use it to give another agent instructions or " +
-      "assign it work: the receiving agent is told to treat your message as information " +
-      "from outside its conversation, not as a directive, and its user is notified that you " +
-      "sent it. Only agents in the same repository can be told, and you are limited to 10 " +
-      "messages an hour to any one agent.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        target: {
-          type: "string",
-          description:
-            "Which agent to tell: a handle from team_list such as 'B1', or a teammate's " +
-            "name, or a repo name.",
-        },
-        message: {
-          type: "string",
-          description:
-            "The heads-up, in one or two sentences. It arrives with no context of its own, " +
-            "so name the thing you are talking about rather than referring to it.",
-        },
-      },
-      required: ["target", "message"],
-      additionalProperties: false,
-    },
-    // Not read-only: this writes into someone else's context and notifies a person.
-    annotations: { readOnlyHint: false, openWorldHint: true, title: "Tell a teammate's agent" },
-  },
-];
-
-// ---------------------------------------------------------------------------
-// Tool implementations
-// ---------------------------------------------------------------------------
-
-async function callTeamList() {
-  // Sent so the daemon can mark which line is this agent's own, and so it can scope the
-  // roster to the repo this session is working in. Absent outside a session, in which case
-  // the roster comes back unmarked rather than failing.
-  const reply = await request(
-    {
-      t: "roster",
-      id: rpcId(),
-      refresh: true,
-      ...(callerSessionId() ? { fromSessionId: callerSessionId() } : {}),
-      // Fallback for the narrow window where the daemon has not seen this session yet. The
-      // session is authoritative when known; this is only ever consulted when it is not.
-      cwd: process.cwd(),
-    },
-    { timeoutMs: 15000 },
-  );
-
-  if (!reply) return errorText(daemonDownMessage());
-  if (reply.t === "error") return errorText(explain(reply));
-  if (reply.t !== "roster.ok") return errorText("The popover daemon returned an unexpected response.");
-
-  if (!reply.entries || reply.entries.length === 0) {
-    // The daemon's own text, because only it knows whether the answer is "nobody on your
-    // team is working" or "nobody is working in this repo" — and those lead a model to say
-    // very different things.
-    return text(
-      reply.rendered ||
-        "No teammates currently have active Claude Code sessions. Nobody is available to ask right now.",
-    );
-  }
-  // Returned as text rather than structuredContent on purpose: setting
-  // structuredContent suppresses text blocks, and the rendered table is both easier for
-  // the model to read and directly presentable to the user.
-  return text(reply.rendered);
-}
-
-async function callTeamAsk(args) {
-  const target = typeof args?.target === "string" ? args.target.trim() : "";
-  const question = typeof args?.question === "string" ? args.question.trim() : "";
-
-  if (!target) return errorText("`target` is required — call team_list to see the options.");
-  if (!question) return errorText("`question` is required.");
-
-  const timeoutSeconds = clamp(Number(args?.timeout_seconds) || 90, 5, 300);
-
-  const reply = await request(
-    {
-      t: "ask",
-      id: rpcId(),
-      req: {
-        target,
-        question,
-        timeoutSeconds,
-        // Lets the audit log show that an agent asked, not a human, and scopes the target
-        // to this session's repo.
-        ...(callerSessionId() ? { fromSessionId: callerSessionId() } : {}),
-      },
-      cwd: process.cwd(),
-    },
-    // Outlast the daemon's own wait so its specific error wins over a generic timeout.
-    { timeoutMs: timeoutSeconds * 1000 + 15000 },
-  );
-
-  if (!reply) return errorText(daemonDownMessage());
-  if (reply.t === "error") return errorText(explain(reply));
-  if (reply.t !== "ask.ok") return errorText("The popover daemon returned an unexpected response.");
-
-  const { answer } = reply;
-  const by = answer.answeredBy;
-  const attribution = by ? `${by.handle} (${by.ownerName}, ${by.repo})` : "a teammate's agent";
-  const cost =
-    answer.costUsd != null && answer.durationMs != null
-      ? `\n\n_(answered in ${(answer.durationMs / 1000).toFixed(1)}s, cost $${answer.costUsd.toFixed(3)} on their account)_`
-      : "";
-
-  return text(`Answer from ${attribution}:\n\n${answer.answer}${cost}`);
-}
-
-async function callTeamTell(args) {
-  const target = typeof args?.target === "string" ? args.target.trim() : "";
-  const message = typeof args?.message === "string" ? args.message.trim() : "";
-
-  if (!target) return errorText("`target` is required — call team_list to see the options.");
-  if (!message) return errorText("`message` is required.");
-
-  const reply = await request(
-    {
-      t: "tell",
-      id: rpcId(),
-      req: {
-        target,
-        message,
-        ...(callerSessionId() ? { fromSessionId: callerSessionId() } : {}),
-      },
-      cwd: process.cwd(),
-    },
-    { timeoutMs: 15000 },
-  );
-
-  if (!reply) return errorText(daemonDownMessage());
-  if (reply.t === "error") return errorText(explain(reply));
-  if (reply.t !== "tell.ok") return errorText("The popover daemon returned an unexpected response.");
-
-  // Says delivered-to, never read-by: a sender is deliberately told nothing about what
-  // happened to their message afterwards.
-  return text(
-    `Sent to ${reply.handle} (${reply.ownerName}). It will reach that agent before its next ` +
-      `prompt; there is no reply.`,
-  );
-}
-
-function explain(errorReply) {
-  switch (errorReply.code) {
-    // The daemon knows whether credentials are missing or merely unusable; relaying its
-    // message avoids telling an already signed-in user to sign in again.
-    case "not_authenticated":
-    case "target_offline":
-    case "unknown_target":
-    case "timeout":
-    case "fork_failed":
-    case "bad_request":
-      return errorReply.message;
-    case "cloud_unreachable":
-      return `Could not reach the popover backend: ${errorReply.message}`;
-    default:
-      return errorReply.message || "The request failed.";
-  }
-}
-
-function daemonDownMessage() {
-  return (
-    "The popover daemon is not running on this machine, so teammate agents are not " +
-    "reachable. Start it with `popover daemon start`, or run `popover doctor` to diagnose."
-  );
-}
-
-// ---------------------------------------------------------------------------
-// JSON-RPC plumbing
-// ---------------------------------------------------------------------------
-
-function text(value) {
-  return { content: [{ type: "text", text: value }] };
-}
-
-function errorText(message) {
-  // isError tells the model the call failed while still handing it a readable reason,
-  // which is far more useful than a transport-level error.
-  return { content: [{ type: "text", text: message }], isError: true };
-}
-
-function clamp(n, lo, hi) {
-  return Number.isFinite(n) ? Math.min(hi, Math.max(lo, n)) : lo;
-}
-
-let counter = 0;
-function rpcId() {
-  counter += 1;
-  return `mcp-${process.pid}-${counter}`;
-}
-
-function send(message) {
-  process.stdout.write(`${JSON.stringify(message)}\n`);
-}
-
-function reply(id, result) {
-  send({ jsonrpc: "2.0", id, result });
-}
-
-function replyError(id, code, message) {
-  send({ jsonrpc: "2.0", id, error: { code, message } });
-}
-
-async function handle(message) {
-  const { id, method, params } = message;
-
-  // Notifications have no id and must never be answered.
-  const isNotification = id === undefined || id === null;
-
-  switch (method) {
-    case "initialize":
-      return reply(id, {
-        protocolVersion: PROTOCOL_VERSION,
-        capabilities: { tools: {} },
-        serverInfo: SERVER_INFO,
-      });
-
-    case "notifications/initialized":
-    case "notifications/cancelled":
-      return;
-
-    case "ping":
-      return reply(id, {});
-
-    case "tools/list":
-      return reply(id, { tools: TOOLS });
-
-    case "tools/call": {
-      const name = params?.name;
-      try {
-        if (name === "team_list") return reply(id, await callTeamList());
-        if (name === "team_ask") return reply(id, await callTeamAsk(params?.arguments ?? {}));
-        if (name === "team_tell") return reply(id, await callTeamTell(params?.arguments ?? {}));
-        return replyError(id, -32602, `Unknown tool: ${name}`);
-      } catch (err) {
-        // A thrown handler must not kill the server; report it as a failed tool call.
-        return reply(id, errorText(`popover failed: ${err?.message ?? String(err)}`));
-      }
-    }
-
-    default:
-      if (!isNotification) replyError(id, -32601, `Method not found: ${method}`);
-      return;
-  }
-}
-
-let buffer = "";
-process.stdin.setEncoding("utf8");
-process.stdin.on("data", (chunk) => {
-  buffer += chunk;
-  let idx = buffer.indexOf("\n");
-  while (idx !== -1) {
-    const line = buffer.slice(0, idx).trim();
-    buffer = buffer.slice(idx + 1);
-    if (line) {
-      let message;
-      try {
-        message = JSON.parse(line);
-      } catch {
-        idx = buffer.indexOf("\n");
-        continue;
-      }
-      void handle(message);
-    }
-    idx = buffer.indexOf("\n");
-  }
-});
-
-process.stdin.on("end", () => process.exit(0));
-process.on("uncaughtException", () => {});
+#!/usr/bin/env node
+// Popover MCP server — lets an agent see and ask its teammates' agents.
+//
+// Implemented directly against the JSON-RPC stdio protocol rather than the MCP SDK. The
+// plugin is distributed through a marketplace and installed into a cache directory where
+// dependency installation is conditional and can fail; a server with zero dependencies
+// simply cannot fail that way. The protocol surface we need is small — initialize,
+// tools/list, tools/call — so the SDK buys us little here.
+//
+// All real work happens in the daemon. This process is a thin bridge to it.
+
+import { readFileSync } from "node:fs";
+import { callerSessionId, request } from "../scripts/_ipc.mjs";
+
+const PROTOCOL_VERSION = "2025-06-18";
+
+// Read from the plugin manifest, which Claude Code copies into its cache alongside this
+// file — so the relative path survives the severing copy that breaks everything else.
+const SERVER_INFO = {
+  name: "popover",
+  version: JSON.parse(
+    readFileSync(new URL("../.claude-plugin/plugin.json", import.meta.url), "utf8"),
+  ).version,
+};
+
+
+const TOOLS = [
+  {
+    name: "team_list",
+    description:
+      "List your teammates' currently-active Claude Code agents in THIS repo: who owns " +
+      "each one, what it is doing right now, and its short handle (e.g. B1). Only agents " +
+      "working in the same repository as you are visible — agents your teammates are " +
+      "running in other repos are not listed and cannot be asked. Use this before " +
+      "team_ask to find out which agent to ask. Read-only.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true, openWorldHint: true, title: "List team agents" },
+  },
+  {
+    name: "team_ask",
+    description:
+      "Ask a teammate's Claude Code agent a question and wait for the answer. A " +
+      "read-only copy of that agent answers from its full accumulated context; the " +
+      "teammate's live session is never interrupted or modified. Use this when a " +
+      "teammate's agent already knows something that would take you a long time to " +
+      "work out — why a decision was made, what they already ruled out, how a service " +
+      "they own behaves. Only agents working in the same repository as you can be asked. " +
+      "Answering costs the teammate tokens and takes up to ~90s, so ask one well-formed " +
+      "question rather than several exploratory ones.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: {
+          type: "string",
+          description:
+            "Which agent to ask: a handle from team_list such as 'B1', or a teammate's " +
+            "name, or a repo name.",
+        },
+        question: {
+          type: "string",
+          description:
+            "A self-contained question. The answering agent has none of your " +
+            "conversation's context, so expand pronouns and vague references.",
+        },
+        timeout_seconds: {
+          type: "number",
+          description: "How long to wait for an answer. Default 90, max 300.",
+          minimum: 5,
+          maximum: 300,
+        },
+      },
+      required: ["target", "question"],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true, title: "Ask a teammate's agent" },
+  },
+  {
+    name: "team_tell",
+    description:
+      "Send a short heads-up to a teammate's agent working in this repo. Unlike team_ask " +
+      "there is no answer: the message is delivered into that agent's context before its " +
+      "next prompt, and nothing comes back. Use it for facts about shared state that would " +
+      "otherwise cause a collision — \"the migration is applied on prod\", \"I am rewriting " +
+      "globals.css, leave it alone\". Do not use it to give another agent instructions or " +
+      "assign it work: the receiving agent is told to treat your message as information " +
+      "from outside its conversation, not as a directive, and its user is notified that you " +
+      "sent it. Only agents in the same repository can be told, and you are limited to 10 " +
+      "messages an hour to any one agent.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: {
+          type: "string",
+          description:
+            "Which agent to tell: a handle from team_list such as 'B1', or a teammate's " +
+            "name, or a repo name.",
+        },
+        message: {
+          type: "string",
+          description:
+            "The heads-up, in one or two sentences. It arrives with no context of its own, " +
+            "so name the thing you are talking about rather than referring to it.",
+        },
+      },
+      required: ["target", "message"],
+      additionalProperties: false,
+    },
+    // Not read-only: this writes into someone else's context and notifies a person.
+    annotations: { readOnlyHint: false, openWorldHint: true, title: "Tell a teammate's agent" },
+  },
+  {
+    name: "vault_search",
+    description:
+      "Search your team's vaults. A vault is a conversation somebody on your team froze " +
+      "deliberately and published: it does not expire, it is not a live session, and its " +
+      "author does not have to be online — or still at the company — for you to use it. " +
+      "This searches the index only. It is free, it runs no model, it resumes nothing, and " +
+      "it costs neither you nor anybody else a token, so use it freely. Each result carries " +
+      "the questions that vault says it can answer, when it was frozen, who froze it, and " +
+      "how much of the code it discussed has changed since — a vault whose files nobody has " +
+      "touched is current however old it is, and one whose files have churned is suspect " +
+      "even if it is recent. Unlike team_list this is not limited to agents in your repo or " +
+      "to people who are working right now: every vault on every team you belong to is " +
+      "searchable. ALWAYS call this before vault_ask, and read what comes back: asking is " +
+      "the expensive half and this is how you spend it on the right vault.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description:
+            "What you want to know, phrased as a question. Vaults are indexed by the " +
+            "questions they can answer rather than by a summary, so a question matches far " +
+            "better than keywords do. Omit it to list the most recently frozen vaults.",
+        },
+        repo: {
+          type: "string",
+          description:
+            "Narrow to one repo label. Display-level filtering only — vaults are visible " +
+            "across every repo your team works in, so leave this off unless the user asked " +
+            "for one repo specifically.",
+        },
+        limit: {
+          type: "number",
+          description: "How many to return. Default 20, max 50.",
+          minimum: 1,
+          maximum: 50,
+        },
+      },
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true, title: "Search team vaults" },
+  },
+  {
+    name: "vault_ask",
+    description:
+      "Ask one vault one question and wait for the answer. **This costs a full context " +
+      "load and real money** — the frozen conversation is resumed in its entirety on THIS " +
+      "machine, on your user's account, at roughly $0.50 and up to 90 seconds per call. " +
+      "Call vault_search first and ask the one vault that fits; never fan out across " +
+      "several to see which answers best, and never call this on a vault you have not seen " +
+      "in a search result. The vault answers from its frozen context and has no tools at " +
+      "all: it cannot read a file, run a command, or look at the repository as it stands " +
+      "today, which is deliberate — it is authoritative about what was decided and why, and " +
+      "explicitly unreliable about what the code currently looks like. Report what comes " +
+      "back as the vault's claim, attributed and dated, never as a bare fact merged into " +
+      "your own reasoning: a vault can hold a hypothesis the team later disproved. Nothing " +
+      "you do here reaches the vault's author, changes the vault, or costs them anything.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        vault_id: {
+          type: "string",
+          description: "The `id` of a vault from a vault_search result. Never guess one.",
+        },
+        question: {
+          type: "string",
+          description:
+            "A self-contained question. The vault has none of your conversation and has " +
+            "been frozen for weeks or months, so expand every pronoun, name files by path, " +
+            "and ask about decisions and reasoning rather than about the current code.",
+        },
+        timeout_seconds: {
+          type: "number",
+          description: "How long to wait for an answer. Default 90, max 300.",
+          minimum: 5,
+          maximum: 300,
+        },
+      },
+      required: ["vault_id", "question"],
+      additionalProperties: false,
+    },
+    // Read-only: it resumes a copy and writes nothing back. It is not free, which the
+    // description says at length, because an annotation cannot say "and it costs money".
+    annotations: { readOnlyHint: true, openWorldHint: true, title: "Ask a team vault" },
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Tool implementations
+// ---------------------------------------------------------------------------
+
+async function callTeamList() {
+  // Sent so the daemon can mark which line is this agent's own, and so it can scope the
+  // roster to the repo this session is working in. Absent outside a session, in which case
+  // the roster comes back unmarked rather than failing.
+  const reply = await request(
+    {
+      t: "roster",
+      id: rpcId(),
+      refresh: true,
+      ...(callerSessionId() ? { fromSessionId: callerSessionId() } : {}),
+      // Fallback for the narrow window where the daemon has not seen this session yet. The
+      // session is authoritative when known; this is only ever consulted when it is not.
+      cwd: process.cwd(),
+    },
+    { timeoutMs: 15000 },
+  );
+
+  if (!reply) return errorText(daemonDownMessage());
+  if (reply.t === "error") return errorText(explain(reply));
+  if (reply.t !== "roster.ok") return errorText("The popover daemon returned an unexpected response.");
+
+  if (!reply.entries || reply.entries.length === 0) {
+    // The daemon's own text, because only it knows whether the answer is "nobody on your
+    // team is working" or "nobody is working in this repo" — and those lead a model to say
+    // very different things.
+    return text(
+      reply.rendered ||
+        "No teammates currently have active Claude Code sessions. Nobody is available to ask right now.",
+    );
+  }
+  // Returned as text rather than structuredContent on purpose: setting
+  // structuredContent suppresses text blocks, and the rendered table is both easier for
+  // the model to read and directly presentable to the user.
+  return text(reply.rendered);
+}
+
+async function callTeamAsk(args) {
+  const target = typeof args?.target === "string" ? args.target.trim() : "";
+  const question = typeof args?.question === "string" ? args.question.trim() : "";
+
+  if (!target) return errorText("`target` is required — call team_list to see the options.");
+  if (!question) return errorText("`question` is required.");
+
+  const timeoutSeconds = clamp(Number(args?.timeout_seconds) || 90, 5, 300);
+
+  const reply = await request(
+    {
+      t: "ask",
+      id: rpcId(),
+      req: {
+        target,
+        question,
+        timeoutSeconds,
+        // Lets the audit log show that an agent asked, not a human, and scopes the target
+        // to this session's repo.
+        ...(callerSessionId() ? { fromSessionId: callerSessionId() } : {}),
+      },
+      cwd: process.cwd(),
+    },
+    // Outlast the daemon's own wait so its specific error wins over a generic timeout.
+    { timeoutMs: timeoutSeconds * 1000 + 15000 },
+  );
+
+  if (!reply) return errorText(daemonDownMessage());
+  if (reply.t === "error") return errorText(explain(reply));
+  if (reply.t !== "ask.ok") return errorText("The popover daemon returned an unexpected response.");
+
+  const { answer } = reply;
+  const by = answer.answeredBy;
+  const attribution = by ? `${by.handle} (${by.ownerName}, ${by.repo})` : "a teammate's agent";
+  const cost =
+    answer.costUsd != null && answer.durationMs != null
+      ? `\n\n_(answered in ${(answer.durationMs / 1000).toFixed(1)}s, cost $${answer.costUsd.toFixed(3)} on their account)_`
+      : "";
+
+  return text(`Answer from ${attribution}:\n\n${answer.answer}${cost}`);
+}
+
+async function callTeamTell(args) {
+  const target = typeof args?.target === "string" ? args.target.trim() : "";
+  const message = typeof args?.message === "string" ? args.message.trim() : "";
+
+  if (!target) return errorText("`target` is required — call team_list to see the options.");
+  if (!message) return errorText("`message` is required.");
+
+  const reply = await request(
+    {
+      t: "tell",
+      id: rpcId(),
+      req: {
+        target,
+        message,
+        ...(callerSessionId() ? { fromSessionId: callerSessionId() } : {}),
+      },
+      cwd: process.cwd(),
+    },
+    { timeoutMs: 15000 },
+  );
+
+  if (!reply) return errorText(daemonDownMessage());
+  if (reply.t === "error") return errorText(explain(reply));
+  if (reply.t !== "tell.ok") return errorText("The popover daemon returned an unexpected response.");
+
+  // Says delivered-to, never read-by: a sender is deliberately told nothing about what
+  // happened to their message afterwards.
+  return text(
+    `Sent to ${reply.handle} (${reply.ownerName}). It will reach that agent before its next ` +
+      `prompt; there is no reply.`,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Vaults — the cheap half and the costly half, deliberately two tools
+// ---------------------------------------------------------------------------
+
+async function callVaultSearch(args) {
+  const query = typeof args?.query === "string" ? args.query.trim() : "";
+  const repo = typeof args?.repo === "string" ? args.repo.trim() : "";
+  const limit = clamp(Number(args?.limit) || 20, 1, 50);
+
+  const reply = await request(
+    {
+      t: "vaults",
+      id: rpcId(),
+      req: {
+        limit,
+        ...(query ? { query } : {}),
+        ...(repo ? { repo } : {}),
+      },
+      // Not a filter. The daemon uses it to diff each vault's files against the tree in front
+      // of you, which is what the staleness figure in each result is.
+      cwd: process.cwd(),
+    },
+    { timeoutMs: 20000 },
+  );
+
+  if (!reply) return errorText(daemonDownMessage());
+  if (reply.t === "error") return errorText(explain(reply));
+  if (reply.t !== "vaults.ok") return errorText("The popover daemon returned an unexpected response.");
+
+  const vaults = reply.vaults ?? [];
+  if (vaults.length === 0) {
+    return text(
+      query
+        ? `No vault on your teams answers anything like "${query}". Nothing was spent looking. ` +
+            "Do not call vault_ask — there is no vault to ask."
+        : "Your teams have not published any vaults yet.",
+    );
+  }
+
+  const lines = vaults.map((vault, index) => {
+    const facts = [
+      vault.authorLabel,
+      `frozen ${friendlyDate(vault.frozenAt)}`,
+      vault.repoLabel ? `repo ${vault.repoLabel}` : null,
+      vault.noteCount > 0 ? `${vault.noteCount} note${vault.noteCount === 1 ? "" : "s"}` : null,
+      describeStaleness(vault.staleness),
+    ].filter(Boolean);
+
+    const answers = (vault.answers ?? []).map((a) => `     - ${a}`).join("\n");
+    return (
+      `${index + 1}. ${vault.title}  (${vault.name})\n` +
+      `   id: ${vault.id}\n` +
+      `   ${facts.join(" · ")}\n` +
+      (answers ? `   Says it can answer:\n${answers}\n` : "")
+    );
+  });
+
+  return text(
+    `${vaults.length} vault${vaults.length === 1 ? "" : "s"} on your teams:\n\n` +
+      lines.join("\n") +
+      "\nThis search cost nothing. Asking one of these costs a full context load and real " +
+      "money on your user's account, so pick the single best fit — or none, if none of them " +
+      "claims to answer the question.",
+  );
+}
+
+async function callVaultAsk(args) {
+  const vaultId = typeof args?.vault_id === "string" ? args.vault_id.trim() : "";
+  const question = typeof args?.question === "string" ? args.question.trim() : "";
+
+  if (!vaultId) return errorText("`vault_id` is required — call vault_search to find one.");
+  if (!question) return errorText("`question` is required.");
+
+  const timeoutSeconds = clamp(Number(args?.timeout_seconds) || 90, 5, 300);
+
+  const reply = await request(
+    {
+      t: "vaultAsk",
+      id: rpcId(),
+      req: {
+        vaultId,
+        question,
+        timeoutSeconds,
+        // Carries the per-session budget. Without it the daemon cannot tell one agent asking
+        // six vaults from six agents asking one each.
+        ...(callerSessionId() ? { fromSessionId: callerSessionId() } : {}),
+      },
+      cwd: process.cwd(),
+    },
+    // Outlast the daemon's own wait so its specific error wins over a generic timeout.
+    { timeoutMs: timeoutSeconds * 1000 + 15000 },
+  );
+
+  if (!reply) return errorText(daemonDownMessage());
+  if (reply.t === "error") return errorText(explain(reply));
+  if (reply.t !== "vaultAsk.ok") return errorText("The popover daemon returned an unexpected response.");
+
+  const { answer } = reply;
+  // Attribution first, and not optional. A human reading a vault's answer supplies the
+  // skepticism unprompted; a model will not unless the format forces it, and a vault can hold
+  // a hypothesis the team later disproved.
+  const at = answer.gitSha ? ` at commit ${answer.gitSha}` : "";
+  const cost =
+    answer.costUsd != null && answer.durationMs != null
+      ? ` Answered in ${(answer.durationMs / 1000).toFixed(1)}s, cost $${answer.costUsd.toFixed(3)} on your own account.`
+      : "";
+
+  return text(
+    `The "${answer.title}" vault, frozen ${friendlyDate(answer.frozenAt)}${at}, says:\n\n` +
+      `${answer.answer}\n\n` +
+      `_(That is a frozen conversation, not the current code. Treat it as authoritative ` +
+      `about what was decided and why, and check anything it says about how the repository ` +
+      `looks today. Attribute it to the vault when you pass it on.${cost})_`,
+  );
+}
+
+/** ISO timestamp to something a person reads, without pulling in a formatter. */
+function friendlyDate(iso) {
+  const at = new Date(iso);
+  if (Number.isNaN(at.getTime())) return iso;
+  const months = "Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec".split(" ");
+  return `${at.getUTCDate()} ${months[at.getUTCMonth()]} ${at.getUTCFullYear()}`;
+}
+
+/**
+ * The staleness figure in words.
+ *
+ * Absent when the daemon had no working tree to diff against, or the vault recorded no paths.
+ * Silence is correct there: "0% changed" and "we could not check" are different claims, and
+ * only one of them is evidence that the vault is still current.
+ */
+function describeStaleness(staleness) {
+  if (typeof staleness !== "number") return null;
+  if (staleness === 0) return "none of its files have changed since";
+  return `${Math.round(staleness * 100)}% of its files have changed since`;
+}
+
+function explain(errorReply) {
+  switch (errorReply.code) {
+    // The daemon knows whether credentials are missing or merely unusable; relaying its
+    // message avoids telling an already signed-in user to sign in again.
+    case "not_authenticated":
+    case "target_offline":
+    case "unknown_target":
+    case "timeout":
+    case "fork_failed":
+    case "bad_request":
+      return errorReply.message;
+    // A vault that is gone is gone: they are never edited and never expire, so this means the
+    // id was wrong or it has been archived. Retrying it, or trying a neighbouring id, cannot
+    // help — searching again can.
+    case "vault_not_found":
+      return `${errorReply.message} Call vault_search again rather than trying another id.`;
+    case "cloud_unreachable":
+      return `Could not reach the popover backend: ${errorReply.message}`;
+    default:
+      return errorReply.message || "The request failed.";
+  }
+}
+
+function daemonDownMessage() {
+  return (
+    "The popover daemon is not running on this machine, so teammate agents are not " +
+    "reachable. Start it with `popover daemon start`, or run `popover doctor` to diagnose."
+  );
+}
+
+// ---------------------------------------------------------------------------
+// JSON-RPC plumbing
+// ---------------------------------------------------------------------------
+
+function text(value) {
+  return { content: [{ type: "text", text: value }] };
+}
+
+function errorText(message) {
+  // isError tells the model the call failed while still handing it a readable reason,
+  // which is far more useful than a transport-level error.
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+
+function clamp(n, lo, hi) {
+  return Number.isFinite(n) ? Math.min(hi, Math.max(lo, n)) : lo;
+}
+
+let counter = 0;
+function rpcId() {
+  counter += 1;
+  return `mcp-${process.pid}-${counter}`;
+}
+
+function send(message) {
+  process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+
+function reply(id, result) {
+  send({ jsonrpc: "2.0", id, result });
+}
+
+function replyError(id, code, message) {
+  send({ jsonrpc: "2.0", id, error: { code, message } });
+}
+
+async function handle(message) {
+  const { id, method, params } = message;
+
+  // Notifications have no id and must never be answered.
+  const isNotification = id === undefined || id === null;
+
+  switch (method) {
+    case "initialize":
+      return reply(id, {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: { tools: {} },
+        serverInfo: SERVER_INFO,
+      });
+
+    case "notifications/initialized":
+    case "notifications/cancelled":
+      return;
+
+    case "ping":
+      return reply(id, {});
+
+    case "tools/list":
+      return reply(id, { tools: TOOLS });
+
+    case "tools/call": {
+      const name = params?.name;
+      try {
+        if (name === "team_list") return reply(id, await callTeamList());
+        if (name === "team_ask") return reply(id, await callTeamAsk(params?.arguments ?? {}));
+        if (name === "team_tell") return reply(id, await callTeamTell(params?.arguments ?? {}));
+        if (name === "vault_search") return reply(id, await callVaultSearch(params?.arguments ?? {}));
+        if (name === "vault_ask") return reply(id, await callVaultAsk(params?.arguments ?? {}));
+        return replyError(id, -32602, `Unknown tool: ${name}`);
+      } catch (err) {
+        // A thrown handler must not kill the server; report it as a failed tool call.
+        return reply(id, errorText(`popover failed: ${err?.message ?? String(err)}`));
+      }
+    }
+
+    default:
+      if (!isNotification) replyError(id, -32601, `Method not found: ${method}`);
+      return;
+  }
+}
+
+let buffer = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  buffer += chunk;
+  let idx = buffer.indexOf("\n");
+  while (idx !== -1) {
+    const line = buffer.slice(0, idx).trim();
+    buffer = buffer.slice(idx + 1);
+    if (line) {
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch {
+        idx = buffer.indexOf("\n");
+        continue;
+      }
+      void handle(message);
+    }
+    idx = buffer.indexOf("\n");
+  }
+});
+
+process.stdin.on("end", () => process.exit(0));
+process.on("uncaughtException", () => {});