@popoverinstall/cli 0.4.0

package/plugin/mcp/index.mjs

@@ -0,0 +1,286 @@
+#!/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" },
+  },
+];
+
+// ---------------------------------------------------------------------------
+// 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}`);
+}
+
+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 ?? {}));
+        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", () => {});

package/plugin/scripts/_ipc.mjs

@@ -0,0 +1,146 @@
+// Zero-dependency IPC helpers for the plugin's hook scripts.
+//
+// These deliberately duplicate a small amount of logic from @popoverinstall/shared. The plugin is
+// installed standalone from a marketplace, where there is no node_modules to import
+// from, and a hook that fails to resolve an import would break every tool call in the
+// session. Fifteen duplicated lines is the cheaper trade.
+//
+// Keep this file dependency-free and fast: a cold node spawn already costs ~50ms, and
+// PreToolUse runs on every tool call.
+
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { appendFileSync, mkdirSync } from "node:fs";
+
+export function popoverHome() {
+  return process.env.POPOVER_HOME ?? path.join(os.homedir(), ".popover");
+}
+
+export function daemonAddress() {
+  if (process.env.POPOVER_DAEMON_ADDR) return process.env.POPOVER_DAEMON_ADDR;
+  if (process.platform === "win32") {
+    const user = process.env.USERNAME || process.env.USER || "default";
+    return `\\\\.\\pipe\\popover-${user.replace(/[^A-Za-z0-9_-]/g, "_")}`;
+  }
+  return path.join(popoverHome(), "daemon.sock");
+}
+
+/**
+ * Send one message and do not wait for a reply.
+ *
+ * Used by the status hooks. Any failure falls back to the spool file, which the daemon
+ * drains the next time it starts — so events survive the daemon being down.
+ */
+export function sendFireAndForget(message, { timeoutMs = 400 } = {}) {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (ok) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      try {
+        socket.destroy();
+      } catch {}
+      if (!ok) spool(message);
+      resolve(ok);
+    };
+
+    const socket = net.createConnection(daemonAddress());
+    const timer = setTimeout(() => finish(false), timeoutMs);
+
+    socket.on("connect", () => {
+      socket.write(`${JSON.stringify(message)}\n`, () => finish(true));
+    });
+    socket.on("error", () => finish(false));
+  });
+}
+
+/** Send a request and wait for the matching reply. */
+export function request(message, { timeoutMs = 5000 } = {}) {
+  return new Promise((resolve) => {
+    let buffer = "";
+    let done = false;
+    const finish = (value) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      try {
+        socket.destroy();
+      } catch {}
+      resolve(value);
+    };
+
+    const socket = net.createConnection(daemonAddress());
+    const timer = setTimeout(() => finish(null), timeoutMs);
+
+    socket.on("connect", () => socket.write(`${JSON.stringify(message)}\n`));
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString();
+      let idx = buffer.indexOf("\n");
+      while (idx !== -1) {
+        const line = buffer.slice(0, idx).trim();
+        buffer = buffer.slice(idx + 1);
+        if (line) {
+          try {
+            return finish(JSON.parse(line));
+          } catch {
+            /* keep reading */
+          }
+        }
+        idx = buffer.indexOf("\n");
+      }
+    });
+    socket.on("error", () => finish(null));
+  });
+}
+
+function spool(message) {
+  try {
+    mkdirSync(popoverHome(), { recursive: true });
+    // Only status payloads are worth replaying; a stale roster request is meaningless.
+    if (message?.t !== "status") return;
+    appendFileSync(
+      path.join(popoverHome(), "spool.jsonl"),
+      `${JSON.stringify(message.payload)}\n`,
+      "utf8",
+    );
+  } catch {
+    /* never let a hook fail because of logging */
+  }
+}
+
+/** Read this hook's JSON payload from stdin. */
+export async function readStdin(timeoutMs = 2000) {
+  return new Promise((resolve) => {
+    let data = "";
+    const timer = setTimeout(() => resolve(data), timeoutMs);
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on("end", () => {
+      clearTimeout(timer);
+      resolve(data);
+    });
+    process.stdin.on("error", () => {
+      clearTimeout(timer);
+      resolve(data);
+    });
+  });
+}
+
+/**
+ * The Claude session this process belongs to, or undefined outside one.
+ *
+ * Claude Code exports `CLAUDE_CODE_SESSION_ID`. This was previously read as
+ * `CLAUDE_SESSION_ID`, which does not exist — so every ask recorded a null
+ * `from_session_id` and the dashboard could never say which agent had asked. Verified
+ * against a live session: the value is the same id the daemon publishes as
+ * `cc_session_id`, so it joins directly to a roster entry.
+ *
+ * The older name is still consulted second, in case a future or older Claude Code uses it.
+ */
+export function callerSessionId() {
+  return process.env.CLAUDE_CODE_SESSION_ID || process.env.CLAUDE_SESSION_ID || undefined;
+}

package/plugin/scripts/emit-event.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// Status hook handler.
+//
+// Reads the hook payload from stdin, forwards it to the daemon, exits. That is the whole
+// job — all interpretation happens in the daemon, so this stays fast enough to sit on
+// PreToolUse, which fires on every single tool call.
+//
+// Rules this script must never break:
+//   - never write to stdout (for UserPromptSubmit and SessionStart, stdout is injected
+//     into the model's context)
+//   - never exit non-zero (exit 2 would BLOCK the tool call it is reporting on)
+//   - never hang (hooks run async, but a wedged process still costs a handle)
+
+import { readStdin, sendFireAndForget } from "./_ipc.mjs";
+
+try {
+  const raw = await readStdin();
+  const payload = JSON.parse(raw);
+
+  if (payload?.session_id && payload?.hook_event_name) {
+    await sendFireAndForget({ t: "status", payload });
+  }
+} catch {
+  // A malformed payload or an absent daemon is not worth interrupting anyone's work.
+}
+
+process.exit(0);

package/plugin/scripts/ensure-daemon.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// SessionStart hook: make sure exactly one daemon is running, then register this session.
+//
+// This runs on every session start, so the common case — a daemon is already up — must
+// be a single cheap probe with no side effects.
+
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, openSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { daemonAddress, popoverHome, readStdin, request, sendFireAndForget } from "./_ipc.mjs";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+async function main() {
+  const raw = await readStdin().catch(() => "");
+  let payload = null;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    /* still worth ensuring the daemon is up */
+  }
+
+  const alive = await ping();
+  if (!alive) {
+    const entry = resolveDaemonEntry();
+    if (entry) {
+      launch(entry);
+      // Give it a moment to bind before we register, but do not block the session on it:
+      // the hook is async and the status event falls back to the spool file regardless.
+      await waitForDaemon(3000);
+    }
+  }
+
+  if (payload?.session_id) {
+    await sendFireAndForget({ t: "status", payload });
+  }
+  process.exit(0);
+}
+
+async function ping() {
+  const reply = await request({ t: "ping", id: "ensure" }, { timeoutMs: 1200 });
+  return reply?.t === "pong";
+}
+
+async function waitForDaemon(budgetMs) {
+  const deadline = Date.now() + budgetMs;
+  while (Date.now() < deadline) {
+    if (await ping()) return true;
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  return false;
+}
+
+/**
+ * Find the daemon entry point.
+ *
+ * Order matters: an explicit override wins, then the pointer file, then the monorepo
+ * layouts used during development.
+ *
+ * The pointer file is the one that matters in production, and it holds an absolute path on
+ * purpose. Installing a plugin *copies* it into
+ * `~/.claude/plugins/cache/<mkt>/<plugin>/<version>/`, severed from whatever tree it was
+ * built in — so every path relative to this file lands inside that cache directory, where
+ * no daemon has ever existed. Only a fixed location under `~/.popover` survives the copy,
+ * and `popover setup` is what writes it there.
+ *
+ * Keep in step with `daemonEntryPointerPath()` in @popoverinstall/shared. This file cannot import
+ * it: a hook that fails to resolve an import would break every tool call in the session.
+ */
+function resolveDaemonEntry() {
+  if (process.env.POPOVER_DAEMON_ENTRY && existsSync(process.env.POPOVER_DAEMON_ENTRY)) {
+    return process.env.POPOVER_DAEMON_ENTRY;
+  }
+
+  // Written by `popover setup`. Survives the plugin-cache copy; see above.
+  try {
+    const entry = readFileSync(path.join(popoverHome(), "daemon-entry"), "utf8").trim();
+    if (entry && existsSync(entry)) return entry;
+  } catch {
+    /* no pointer yet — `popover setup` has not run */
+  }
+
+  const candidates = [
+    // Vendored beside the plugin.
+    path.join(HERE, "..", "node_modules", "@popoverinstall", "daemon", "dist", "index.js"),
+    // Monorepo checkout.
+    path.join(HERE, "..", "..", "daemon", "dist", "index.js"),
+    path.join(HERE, "..", "..", "..", "packages", "daemon", "dist", "index.js"),
+  ];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+function launch(entry) {
+  try {
+    // Detached with stdio to a log file: the daemon must outlive this hook, this session,
+    // and the terminal window it was started from.
+    mkdirSync(popoverHome(), { recursive: true });
+    const out = openSync(path.join(popoverHome(), "daemon-stdout.log"), "a");
+    const child = spawn(process.execPath, [entry], {
+      detached: true,
+      stdio: ["ignore", out, out],
+      windowsHide: true,
+      env: { ...process.env, POPOVER_DAEMON_ADDR: daemonAddress() },
+    });
+    child.unref();
+  } catch {
+    // If the daemon cannot start, /team will say so plainly. Never fail the session.
+  }
+}
+
+main().catch(() => process.exit(0));

package/plugin/scripts/roster.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// Renders the /team menu.
+//
+// Invoked from the command's `!` injection, so its stdout becomes part of the prompt
+// Claude sees. Two consequences shape everything here:
+//   - always exit 0. A non-zero exit aborts the whole slash command.
+//   - always print something useful. If the daemon is down, say so in words the model
+//     can relay, rather than printing an empty section and letting it invent a reason.
+
+import { callerSessionId, request } from "./_ipc.mjs";
+
+// `fromSessionId` is what lets the daemon mark this agent's own line. It comes from the
+// session's environment, so a bare shell run of this script sends nothing and the roster
+// comes back unmarked.
+const reply = await request(
+  {
+    t: "roster",
+    id: "cli",
+    refresh: true,
+    ...(callerSessionId() ? { fromSessionId: callerSessionId() } : {}),
+  },
+  { timeoutMs: 8000 },
+);
+
+if (!reply) {
+  console.log(
+    "The popover daemon is not running on this machine, so teammate agents are not visible.\n" +
+      "Start it with `popover daemon start`, or check `popover doctor`.",
+  );
+} else if (reply.t === "error") {
+  // The daemon distinguishes "no credentials" from "signed in but cannot connect", so
+  // relay its message rather than assuming the user has not logged in.
+  console.log(
+    reply.code === "not_authenticated"
+      ? reply.message
+      : `Could not load the team roster: ${reply.message}`,
+  );
+} else if (reply.t === "roster.ok") {
+  console.log(reply.rendered);
+  if (reply.stale) {
+    console.log("\n(Showing cached data — the backend was unreachable.)");
+  }
+} else {
+  console.log("The popover daemon returned an unexpected response.");
+}
+
+process.exit(0);