@popoverinstall/cli 0.9.0 → 0.10.0

package/plugin/scripts/_ipc.mjs

@@ -11,12 +11,60 @@
 import net from "node:net";
 import os from "node:os";
 import path from "node:path";
-import { appendFileSync, mkdirSync } from "node:fs";
+import { appendFileSync, mkdirSync, statSync } from "node:fs";
 
 export function popoverHome() {
   return process.env.POPOVER_HOME ?? path.join(os.homedir(), ".popover");
 }
 
+/**
+ * Path of the daemon's "something is waiting for this session" flag.
+ *
+ * **Canonical definition: `inboxFlagPath` in `packages/shared/src/paths.ts`. This is a copy.**
+ * Hook scripts stay dependency-free — there is no node_modules beside a marketplace-installed
+ * plugin — so the path is duplicated here and the two must change together, the same
+ * arrangement `daemonEntryPointerPath` already documents for ensure-daemon.mjs. Read that one
+ * for why the file exists; this one only has to agree with it.
+ *
+ * Two properties of that contract are load-bearing here and are easy to break by accident:
+ *
+ *   - **Nothing reads the bytes.** The file exists or it does not. `pending` is what hands over
+ *     rendered text, on this machine, from the columns the database filled in — a flag holding
+ *     the message would be a second copy a hook could print without the framing (docs/messages.md
+ *     §5). So this stats; it never opens.
+ *   - **The session id is reduced before it becomes a filename**, identically to paths.ts. Two
+ *     sessions folding onto one flag costs an unnecessary IPC call; a `..` surviving into the
+ *     path costs a file somewhere else on disk.
+ *
+ * Existence is also the capability handshake, without needing a version byte: a daemon old
+ * enough to render only tell-shaped framing is a daemon that never writes this file.
+ */
+export function inboxFlagPath(sessionId) {
+  const safe = String(sessionId).replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 128) || "unknown";
+  return path.join(popoverHome(), "inbox", `${safe}.flag`);
+}
+
+/**
+ * When the flag was last written, or null when there is nothing waiting.
+ *
+ * The mtime comes free in the same `stat` that answers the existence question, and it is the
+ * only clock available once the contract says the contents are not a payload. inject-message.mjs
+ * uses it to bound how long it will hold a message back during a run of edits.
+ *
+ * What it measures is "when the daemon last touched this flag", which is the arrival of the
+ * *most recent* waiting item rather than the oldest. Close enough for a patience deadline
+ * measured in tens of seconds, and worth knowing before anyone builds something finer on it.
+ */
+export function inboxWaitingSince(sessionId) {
+  if (!sessionId) return null;
+  try {
+    return statSync(inboxFlagPath(sessionId)).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+
 export function daemonAddress() {
   if (process.env.POPOVER_DAEMON_ADDR) return process.env.POPOVER_DAEMON_ADDR;
   if (process.platform === "win32") {

package/plugin/scripts/announce-roster.mjs

@@ -7,10 +7,11 @@
 // hook is the cheap one: it is about to edit a file a teammate's agent is already in, and
 // the roster line is what makes the overlap visible before the edit rather than at merge.
 //
-// Registered synchronously on UserPromptSubmit, because that is the one event whose stdout
-// is injected into the model's context. That makes this the second hook here allowed to
-// print — see the header of deliver-messages.mjs — and it inherits every constraint that
-// one documents: it runs before every prompt, so it must be fast and must fail open.
+// Registered synchronously on UserPromptSubmit, because that is the event this line wants:
+// its stdout is injected into the model's context ahead of the prompt it is about to answer.
+// That makes this the second hook here allowed to print — see the header of
+// deliver-messages.mjs — and it inherits every constraint that one documents: it runs before
+// every prompt, so it must be fast and must fail open.
 //
 // It announces on change rather than on every prompt. A line repeated ahead of all fifty
 // prompts in a session stops being information and becomes wallpaper: the model habituates,

package/plugin/scripts/deliver-messages.mjs

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 // Delivers tells into a live session.
 //
-// One of the two hooks in the plugin that write to stdout on purpose — announce-roster.mjs
-// is the other. Every one of the rest is registered `async: true` and forbidden from
-// printing, because for UserPromptSubmit stdout is injected into the model's context — see
-// the header of emit-event.mjs. That is precisely the channel a tell needs, so this hook is
-// synchronous and its output is the message.
+// One of the two hooks in the plugin that write to plain stdout on purpose —
+// announce-roster.mjs is the other, and nudge-vault.mjs reaches the model a third way, with
+// JSON `additionalContext` on Stop. Every one of the rest is registered `async: true` and
+// forbidden from printing, because for UserPromptSubmit stdout is injected into the model's
+// context — see the header of emit-event.mjs for which events that holds for. That is
+// precisely the channel a tell needs, so this hook is synchronous and its output is the
+// message.
 //
 // Which makes it the riskiest script here, and it is written accordingly:
 //

package/plugin/scripts/emit-event.mjs

@@ -6,8 +6,17 @@
 // 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 write to stdout. Plain stdout from a hook is injected into the model's context on
+//     UserPromptSubmit, UserPromptExpansion, SessionStart and PostModelSwitch — that is the
+//     verified full list for *plain stdout*, and this script is registered on one of them,
+//     UserPromptSubmit.
+//     What that list is not is the set of events that can reach the model at all: JSON
+//     `hookSpecificOutput.additionalContext` is delivered on many more, including PreToolUse,
+//     PostToolUse, PostToolBatch and Stop. The comment here used to name only the first two
+//     events, which read as "nothing can reach the model mid-turn" and shaped this plugin's
+//     design around waiting for the next prompt. It is wrong, and nudge-vault.mjs is built on
+//     the correction: it answers Stop with `additionalContext` and reaches the model at the
+//     end of the turn that earned it.
 //   - 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)
 

package/plugin/scripts/inject-message.mjs

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+// Hands a waiting message to a session that is in the middle of working.
+//
+// docs/messages.md §5. The routing table in §1 sends a message to the live session when the
+// target is `working`, and this is the only thing that can carry it there: hooks react, they
+// do not initiate, so the message rides on a tool batch the agent was already running. The
+// agent answers, briefly, and goes back to what it was doing.
+//
+// Registered synchronously on `PostToolBatch`, which fires once after a whole batch of
+// parallel tool calls resolves and before the next model request. `PostToolUse` would work and
+// would pay this hook's cost once per *tool* to deliver the same message once. Async would
+// deliver a model call late — measured, and a message that arrives a call late arrives after
+// the decision it was meant to inform.
+//
+// ## This is the second deliberate exception to popover's trust model, and it says so
+//
+// README.md rests popover's safety on one property: content enters an agent's context only as
+// the return value of a tool that agent chose to call. A tell is named there as the single
+// deliberate exception. This is the same exception, not a softer third category — a teammate's
+// words entering a running, fully-tooled session that did not ask for them — and §5 requires
+// it be described that way rather than discovered.
+//
+// So it carries the defences a tell carries, and **it does not build any of them here**:
+//
+//   - The text is rendered by the daemon, on this machine, from a template. A sender cannot
+//     strip framing they never touched. This script prints what it is handed, exactly as
+//     deliver-messages.mjs does — read that file's header for why that constraint is the
+//     riskiest one in the plugin to break.
+//   - Fencing and `sanitizeField`-grade sanitisation of the quoted body — control characters
+//     and newlines stripped, so a body cannot emit a line at all, cannot close the fence and
+//     cannot forge a `[popover]` header — live in `packages/shared/src/envelope.ts` beside
+//     `renderReceiptRecord`, which already does exactly this for ask receipts.
+//   - Which means this hook must never print text a daemon that predates live injection
+//     rendered. The flag file's existence is that handshake — a daemon that renders only
+//     tell-shaped framing never writes one. See `inboxFlagPath` in _ipc.mjs.
+//
+// ## Cost, which is the whole reason for the flag file
+//
+// This runs inside the agentic loop, after every batch, on every session. An IPC round trip
+// per batch is not affordable and §5 rules it out. So the daemon drops a file when something
+// is waiting and this stats for it: on the overwhelmingly common path the file is absent, the
+// stat fails, and the process exits having done nothing else — no stdin, no socket, and not
+// even an import of _ipc.mjs, which is loaded dynamically below so that node:net stays
+// unloaded on the path that does not need it.
+//
+// The floor is therefore a bare Node start, which nothing here can improve on and which is
+// most of the measured cost.
+//
+// Fail open, always. No daemon, no flag, a malformed payload, a wedged socket: exit 0 in
+// silence. A message arriving one batch later is a small loss; a wedged hook between an
+// agent's tool call and its next thought is not.
+
+import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// A fork answering a teammate's question must not be handed a third party's message: its
+// output goes back to whoever asked. The daemon's own `handlePending` documents the backstop
+// behind this guard — a fork's session id is never published, so it addresses no inbox — but
+// the guard is what makes it free rather than merely harmless.
+if (process.env.CLAUDE_CODE_ENTRYPOINT === "popover-fork") process.exit(0);
+
+/**
+ * How long a colleague may be left waiting while the agent is mid-edit.
+ *
+ * The discipline in §5 is to inject after read-only tools and never inside a multi-edit
+ * sequence — interrupting between a read and the write that depends on it is worse than
+ * interrupting after the read. Held batches cost nothing, because the flag stays on disk and
+ * the next batch tries again.
+ *
+ * But patience without a deadline is a dropped message: a long edit run is minutes of
+ * mutating batches, and the sender is waiting on a reply the whole time. After this, the
+ * message goes in on the next batch whatever it contains. Twenty seconds is long enough to
+ * clear a normal edit-then-verify sequence and short enough that nobody watching a colleague's
+ * agent work would call it lost.
+ */
+const PATIENCE_MS = 20_000;
+
+/**
+ * Tools whose batch is a bad moment to interrupt.
+ *
+ * File mutations only. `Bash` is deliberately absent, and that is the one judgement call in
+ * here: it is the most common *read-only* tool in practice — git status, a test run, a grep —
+ * so treating it as mutating would collapse "prefer read-only moments" into "never inject",
+ * which is the failure mode §5 is not asking for.
+ */
+const MUTATING = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
+
+/** One item per batch. The drain below says why this is not deliver-messages.mjs's three. */
+const LIMIT = 1;
+
+const sessionId = process.env.CLAUDE_CODE_SESSION_ID || process.env.CLAUDE_SESSION_ID || "";
+
+try {
+  // The env var rather than the payload, and this is the whole trick: the session id has to be
+  // known *before* deciding whether this batch is worth reading stdin for. announce-roster.mjs
+  // makes the same trade for the same reason and records it — a hook that spends 150ms on a
+  // payload it will discard has already lost. The cost is that a session where Claude Code
+  // does not export the id never injects, which is the safe direction to fail in.
+  const waitingSince = inboxWaitingSince(sessionId);
+  if (waitingSince === null) process.exit(0);
+
+  // A flag whose drain already came back empty. The daemon deletes the file when the inbox
+  // empties, so reaching here means either a daemon that did not, or a race with another
+  // drain — deliver-messages.mjs runs on every prompt and takes from the same queue. Either
+  // way, one wasted round trip per flag is the budget, not one per batch.
+  if (!drainedEmpty(waitingSince)) {
+    const payload = await readPayload();
+
+    if (goodMoment(payload, waitingSince)) {
+      // Loaded here and not at the top of the file: this pulls in node:net, and the path that
+      // does not need it is the path that runs thousands of times a session.
+      const { request } = await import("./_ipc.mjs");
+
+      const reply = await request(
+        {
+          t: "pending",
+          id: "hook",
+          fromSessionId: sessionId,
+          limit: LIMIT,
+          // Which surface is draining, so the daemon can render for it. A tell delivered at a
+          // prompt boundary and a message injected mid-turn need different framing — §5 wants
+          // the fence and the newline-stripped body for the second — and the daemon cannot
+          // tell the two callers apart otherwise. Unknown fields are dropped by the zod arm in
+          // packages/shared/src/ipc.ts today, so this is inert until that arm accepts it, and
+          // inert is correct: a daemon not knowing the field is also one whose flag file
+          // never appears.
+          surface: "injection",
+        },
+        // Local socket, answered from memory by design — `handlePending` is documented as
+        // never touching the network. 400ms is a ceiling on a degraded daemon, not a target.
+        { timeoutMs: 400 },
+      );
+
+      if (reply?.t === "pending.ok" && reply.rendered) emit(reply.rendered);
+      // An empty drain is not an error: something else got there first. Remember it so the
+      // next batch does not ask again.
+      else rememberEmpty(waitingSince);
+    }
+  }
+} catch {
+  // Fail open, always.
+}
+
+process.exit(0);
+
+/**
+ * The one line of stdout this script may write.
+ *
+ * `hookEventName` must name the event being answered. The 10,000-character cap on
+ * `additionalContext` is bounded by the daemon's render and by LIMIT above, and is not
+ * enforced here on purpose: by the time this text exists the inbox has been drained and
+ * marked delivered, so refusing to print it would lose the message outright. Over the cap,
+ * Claude Code writes a file and passes a path — a documented degradation, and strictly
+ * better than a silent drop. If this ever fires the render is at fault, and that is where
+ * to fix it.
+ */
+function emit(additionalContext) {
+  process.stdout.write(
+    `${JSON.stringify({
+      hookSpecificOutput: { hookEventName: "PostToolBatch", additionalContext },
+    })}\n`,
+  );
+}
+
+/**
+ * Is this batch a decent moment to interrupt?
+ *
+ * Honest about its own limits. The `PostToolBatch` payload's representation of the tools in
+ * the batch is **not documented** — `session_id`, `cwd`, `transcript_path` and
+ * `hook_event_name` are, the batch is not — so `toolNames` guesses at spellings, and a batch
+ * it cannot read is delivered into rather than held. That direction is deliberate: the
+ * alternative is a message that is never delivered live at all on a payload shape nobody here
+ * has seen, which would quietly defeat §1's routing while looking implemented.
+ *
+ * The consequence to be honest about: until the payload shape is confirmed, the multi-edit
+ * exclusion may be doing nothing. It is real code against a guessed key, not a verified rule.
+ */
+function goodMoment(payload, waitingSince) {
+  if (Date.now() - waitingSince > PATIENCE_MS) return true;
+  const names = toolNames(payload);
+  if (names.length === 0) return true;
+  return !names.some((name) => MUTATING.has(name));
+}
+
+/**
+ * Every tool name this payload might be carrying.
+ *
+ * One array of candidate keys, in one place, so that confirming the real shape is a one-line
+ * edit rather than an archaeology exercise. `tool_name` is the documented single-tool spelling
+ * from PostToolUse and is read first because a batch of one may well look like one.
+ */
+function toolNames(payload) {
+  const names = [];
+  const add = (value) => {
+    if (typeof value === "string" && value) names.push(value);
+  };
+
+  add(payload?.tool_name);
+  for (const key of ["tool_uses", "tools", "tool_calls", "tool_results", "batch"]) {
+    const items = payload?.[key];
+    if (!Array.isArray(items)) continue;
+    for (const item of items) {
+      if (typeof item === "string") add(item);
+      else if (item && typeof item === "object") {
+        add(item.tool_name);
+        add(item.name);
+        add(item.tool);
+      }
+    }
+  }
+  return names;
+}
+
+/**
+ * Read the hook payload, but never wait long for it.
+ *
+ * Duplicated from deliver-messages.mjs rather than imported, because importing it would mean
+ * loading _ipc.mjs on a path that has already decided not to talk to the daemon. That file's
+ * own header says fifteen duplicated lines beat an import a hook can trip over, and this is
+ * the same trade one level down. 200ms because the payload is already written by the time the
+ * process starts; if it is not there, the batch is unclassifiable and goodMoment says so.
+ */
+function readPayload() {
+  return new Promise((resolve) => {
+    let data = "";
+    const done = () => {
+      try {
+        resolve(JSON.parse(data));
+      } catch {
+        resolve({});
+      }
+    };
+    const timer = setTimeout(done, 200);
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on("end", () => {
+      clearTimeout(timer);
+      done();
+    });
+    process.stdin.on("error", () => {
+      clearTimeout(timer);
+      done();
+    });
+  });
+}
+
+/*
+ * The flag file, and the marker beside it.
+ *
+ * `inboxFlagPath` is duplicated from _ipc.mjs — which is itself a copy of the canonical one in
+ * `packages/shared/src/paths.ts` — for the single reason this file exists to serve: importing
+ * _ipc.mjs is what the fast path is avoiding. Three copies is one too many, so the ranking is
+ * written down rather than guessed at: paths.ts is right, _ipc.mjs agrees with it, and this
+ * agrees with _ipc.mjs.
+ *
+ * The contract's own rule is what keeps the duplication cheap — nothing reads the bytes, so
+ * there is no format here to drift, only a path and a `stat`.
+ */
+function popoverHome() {
+  return process.env.POPOVER_HOME ?? path.join(os.homedir(), ".popover");
+}
+
+function inboxWaitingSince(id) {
+  if (!id) return null;
+  try {
+    const safe = String(id).replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 128) || "unknown";
+    return statSync(path.join(popoverHome(), "inbox", `${safe}.flag`)).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+/** Where this hook remembers a flag it already drained to nothing. */
+function markerPath() {
+  return path.join(popoverHome(), "announced", `${sessionId}.inject.json`);
+}
+
+function drainedEmpty(waitingSince) {
+  try {
+    return JSON.parse(readFileSync(markerPath(), "utf8"))?.emptyAt === waitingSince;
+  } catch {
+    return false;
+  }
+}
+
+function rememberEmpty(waitingSince) {
+  try {
+    mkdirSync(path.join(popoverHome(), "announced"), { recursive: true });
+    writeFileSync(markerPath(), JSON.stringify({ v: 1, emptyAt: waitingSince }), "utf8");
+  } catch {
+    // Unwritable means one wasted round trip per batch while a stale flag sits there. It is a
+    // cost, not a break, and it stops the moment the daemon removes the file.
+  }
+}