@popoverinstall/cli 0.8.1 → 0.9.1

package/plugin/mcp/index.mjs

@@ -108,6 +108,156 @@ const TOOLS = [
     // 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" },
+  },
+  {
+    name: "vault_create",
+    description:
+      "Publish this conversation to your team's vault. This writes: it uploads the whole " +
+      "conversation — every message, and the contents of every file read into it — where " +
+      "everyone on the team can search it and ask it, permanently. It does not expire, it " +
+      "cannot be edited afterwards, and it is not sent to one named person: it goes to the " +
+      "team. **A vault is readable by the popover service.** That is the one way it differs " +
+      "from /popover:fork, which is end-to-end encrypted and which the service cannot read; " +
+      "do not describe a vault as if it made the same promise, and say so plainly if you " +
+      "tell the user you have vaulted something. You may call this on your own judgement " +
+      "rather than waiting to be asked — the moment worth vaulting is usually one the user " +
+      "is too deep in the work to notice, and a conversation nobody vaults is deleted when " +
+      "the session ends. But judge it as a real disclosure and not as a cheap call: vault a " +
+      "conversation that worked something out the team will want and the repository will " +
+      "not record — a decision and the reasons behind it, an approach that was tried and " +
+      "rejected, an investigation into why something is the way it is. Do not vault routine " +
+      "work, and do not vault the same session twice.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: {
+          type: "string",
+          description:
+            "A short human label, 3 to 120 characters. It is what a teammate reads on a card " +
+            "in a grid, so name the subject rather than the activity: 'Why the repo key does " +
+            "not gate vaults', not 'vault work'.",
+        },
+        answers: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Questions this conversation can answer — NOT a summary of what happened. This " +
+            "is the retrieval surface: the query that finds this vault later will itself be " +
+            "a question, and matching a question against a summary retrieves badly where " +
+            "question against question does not. Write each one the way a teammate would " +
+            "type it months from now, in full: 'Why did we reject the repo key as a vault " +
+            "credential?', not 'discussed encryption'. Three to six is right; each is 8 to " +
+            "200 characters and there can be at most 12. This is the field that decides " +
+            "whether the vault is ever found again, and it cannot be edited afterwards.",
+          minItems: 1,
+          maxItems: 12,
+        },
+        name: {
+          type: "string",
+          description:
+            "Optional slug, lowercase letters, digits and hyphens. It appears in URLs and in " +
+            "the command teammates type. Derived from the title when omitted, which is " +
+            "usually right — pass one only when the title makes an awkward slug or when a " +
+            "name collision has been reported.",
+        },
+      },
+      required: ["title", "answers"],
+      additionalProperties: false,
+    },
+    // Not read-only, and the only vault tool that is not. This publishes a conversation to a
+    // whole team, permanently, and there is no edit and no undo — `archive` retires a vault
+    // without erasing the record that it was made.
+    annotations: {
+      readOnlyHint: false,
+      openWorldHint: true,
+      title: "Publish this conversation to the team",
+    },
+  },
 ];
 
 // ---------------------------------------------------------------------------
@@ -225,7 +375,259 @@ async function callTeamTell(args) {
   );
 }
 
+// ---------------------------------------------------------------------------
+// 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})_`,
+  );
+}
+
+/**
+ * Publish this conversation. The one tool here that writes something permanent.
+ *
+ * ## Why this is an IPC verb and not `popover vault create`
+ *
+ * The pipeline it drives is the CLI's, tested and unchanged — find the transcript, settle it,
+ * sanitize, collect touched paths, upload. The obvious implementation is therefore to spawn
+ * `popover vault create --json` and relay what it prints. It is not what happens, and the
+ * reason is Windows.
+ *
+ * `popover` on Windows is a `.cmd` shim, and Node refuses to spawn a `.cmd` without a shell.
+ * With `shell: true` the arguments are pasted into a `cmd.exe` command line, where `&`, `|`,
+ * `^` and `>` are operators — and every argument here is written by a model: a title, a list
+ * of questions, a slug. That is untrusted-input-into-a-shell, on the machine this is being
+ * built on, to save a wire format. The escape hatches are worse than the problem: locating the
+ * CLI's real `.js` inside the shim is guesswork about npm's layout, and hand-quoting for
+ * `cmd.exe` is a thing to get wrong quietly.
+ *
+ * So it goes over the pipe the other four tools already use. The daemon needs nothing new to
+ * be reachable, holds the device token already, and already POSTs to the vault routes; the
+ * shared decisions — `planVault`, `collectToolPaths`, `packBody` — moved into
+ * @popoverinstall/shared so the terminal and the daemon build byte-identical payloads. No
+ * child process, nothing to quote, and the same code path on every platform.
+ */
+async function callVaultCreate(args) {
+  const title = typeof args?.title === "string" ? args.title.trim() : "";
+  const name = typeof args?.name === "string" ? args.name.trim() : "";
+  const answers = Array.isArray(args?.answers)
+    ? args.answers.filter((a) => typeof a === "string" && a.trim()).map((a) => a.trim())
+    : [];
+
+  if (!title) return errorText("`title` is required — a vault needs a short human label.");
+  if (answers.length === 0) {
+    return errorText(
+      "`answers` is required, and it holds questions this conversation can answer rather " +
+        "than a summary of it. A vault with no questions is one nobody will ever find.",
+    );
+  }
+
+  // Never from the model. The session being frozen is the one this process belongs to, and a
+  // caller that could name any session could publish a conversation it was never part of.
+  const sessionId = callerSessionId();
+  if (!sessionId) {
+    return errorText(
+      "There is no Claude Code session here to vault. This tool freezes the conversation it " +
+        "is running inside, and outside a session there is nothing to freeze.",
+    );
+  }
+
+  const reply = await request(
+    {
+      t: "vaultCreate",
+      id: rpcId(),
+      req: { sessionId, title, answers, ...(name ? { name } : {}) },
+      // Where git runs: it decides the recorded commit and the uncommitted half of the
+      // touched-path list. Not a filter, and never a permission.
+      cwd: process.cwd(),
+    },
+    // Generous: the daemon waits for the transcript to stop moving, runs git, and then
+    // uploads a whole gzipped conversation, which is megabytes rather than bytes.
+    { timeoutMs: 60000 },
+  );
+
+  // Not `daemonDownMessage()`. Silence here has a second cause the other tools do not have:
+  // a daemon older than this plugin does not know the verb, and drops a request its schema
+  // refuses without answering it. Telling somebody to start a daemon that is already running
+  // sends them after the wrong problem, so both possibilities are named and neither is
+  // asserted. Nothing was published either way — the upload is the last thing that happens.
+  if (!reply) {
+    return errorText(
+      "The popover daemon did not answer, so nothing was published. Either it is not " +
+        "running on this machine, or it is older than this plugin and does not know how to " +
+        "publish a vault. Run `popover doctor` to find out which, and `popover update` if it " +
+        "is the second.",
+    );
+  }
+  if (reply.t === "error") return errorText(explain(reply));
+  if (reply.t !== "vaultCreate.ok") {
+    return errorText("The popover daemon returned an unexpected response.");
+  }
+
+  const vault = reply.vault;
+  const answered = (vault.answers ?? []).map((a) => `  - ${a}`).join("\n");
+  const sha = vault.gitSha ? ` at commit ${vault.gitSha.slice(0, 7)}` : "";
+
+  return text(
+    `Published "${vault.title}" to your team as \`${vault.name}\`.\n\n` +
+      `${vault.entryCount} messages, frozen at the last completed turn ` +
+      `(${friendlyDate(vault.frozenAt)}${sha}). Nothing said from here is in it.\n\n` +
+      `It says it can answer:\n${answered}\n\n` +
+      `Anyone on the team can ask it, on their own machine and at their own cost:\n` +
+      `  popover vault ask ${vault.name} "…"\n\n` +
+      // Said every time, in the same register the CLI's confirmation uses. Anyone who has
+      // internalized /popover:fork being end-to-end will assume this is too, and it is not.
+      `Tell the user you did this, and tell them plainly that a vault is readable by the ` +
+      `popover service — a fork is end-to-end and this is not. It does not expire and cannot ` +
+      `be edited; \`popover vault archive ${vault.name}\` retires it without erasing the ` +
+      `record that it was made.`,
+  );
+}
+
+/** 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`;
+}
+
+/**
+ * The daemon's own words for a failure, plus whatever it said to do about it.
+ *
+ * `hints` arrives on refusals that have an answer — a title too short, a name already taken,
+ * a conversation over the size limit — and is relayed verbatim rather than summarised. Those
+ * sentences are the difference between a second attempt that works and one that fails
+ * identically, and they are written where the constraint is, which is not here.
+ */
 function explain(errorReply) {
+  const hints = Array.isArray(errorReply.hints) ? errorReply.hints.filter(Boolean) : [];
+  const said = describe(errorReply);
+  return hints.length ? `${said}\n\n${hints.join("\n")}` : said;
+}
+
+function describe(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.
@@ -236,6 +638,11 @@ function explain(errorReply) {
     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:
@@ -316,6 +723,9 @@ async function handle(message) {
         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 ?? {}));
+        if (name === "vault_create") return reply(id, await callVaultCreate(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.