pi-creel 0.1.1 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-creel",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "request_secret for the pi coding agent: capture an API key into a local .env via a tmux popup (the creel tool) so it never enters the chat/context.",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -13,8 +13,8 @@
 // pi-wakeup and guardrails use.
 
 import { execFileSync } from "node:child_process";
-import { existsSync, readFileSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, watch } from "node:fs";
+import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 import { setTimeout as sleep } from "node:timers/promises";
@@ -26,18 +26,27 @@ import {
   tokenToText,
   validName,
 } from "./capture.ts";
+import { parseEvent, savedMessage } from "./notify.ts";
 
 const POPUP_WIDTH = "64";
 const POPUP_HEIGHT = "14";
 const TOKEN_TIMEOUT_MS = 120_000;
 const POLL_INTERVAL_MS = 150;
 
+export type WatchHandle = { close: () => void };
+
 export type Deps = {
   resolveTmux?: (env: NodeJS.ProcessEnv) => TmuxContext | undefined;
   creelOnPath?: () => boolean;
   spawnPopup?: (tmux: TmuxContext, command: string) => void;
   waitForToken?: (statusPath: string, timeoutMs: number) => Promise<string | undefined>;
   tmpStatusPath?: () => string;
+  resolveSessionId?: (tmux: TmuxContext) => string | undefined;
+  homedir?: () => string;
+  watch?: (dir: string, cb: (event: string, filename: string | null) => void) => WatchHandle;
+  readEventFile?: (path: string) => string;
+  eventMtimeMs?: (path: string) => number;
+  mkdir?: (dir: string) => void;
 };
 
 function defaultCreelOnPath(): boolean {
@@ -110,9 +119,9 @@ export function createCreel(pi: any, deps: Deps = {}): void {
     name: "request_secret",
     label: "Request Secret",
     description:
-      "Capture an API key or secret from the user without it entering the chat. Opens a masked tmux popup (the creel tool); the user pastes once and the value is written straight into a local .env. Call this whenever you would otherwise ask the user to paste a key — you receive only a confirmation (added/updated), never the value. Requires a tmux session and the 'creel' binary on PATH.",
+      "Capture an API key, token, password, or any secret from the user WITHOUT it entering the chat or your context. Opens a masked tmux popup (the creel tool); the user pastes once and the value is written straight into a local .env (chmod 600). ALWAYS use this instead of asking the user to paste a secret into chat: any time you need a credential, or are about to say 'paste your ... key/token', call request_secret first. You receive only a confirmation (added/updated/cancelled), never the value. Requires a tmux session and the 'creel' binary on PATH.",
     promptSnippet:
-      "request_secret(name, dest?) — need an API key/secret? Capture it into a .env via a popup instead of asking the user to paste it into chat.",
+      "request_secret(name, dest?) - need ANY secret, API key, token, or password? ALWAYS capture it via this popup instead of asking the user to paste it into chat.",
     parameters: REQUEST_SECRET_PARAMS,
     async execute(_id: string, params: { name?: string; dest?: string }) {
       const name = typeof params?.name === "string" ? params.name : "";
@@ -152,6 +161,127 @@ export function createCreel(pi: any, deps: Deps = {}): void {
   });
 }
 
+const EVENTS_SUBDIR = ".pi/agent/creel-events";
+
+// defaultResolveSessionId asks tmux for the id of the session this pi runs in,
+// so the watcher reacts only to saves made in THIS session (routing by tmux
+// session). Returns undefined outside tmux or on any tmux error.
+function defaultResolveSessionId(tmux: TmuxContext): string | undefined {
+  try {
+    const out = execFileSync(
+      "tmux",
+      ["-L", tmux.socket, "display-message", "-p", "-t", tmux.pane, "#{session_id}"],
+      { stdio: ["ignore", "pipe", "ignore"] },
+    ).toString("utf-8");
+    const id = out.trim();
+    return id || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// startCreelWatch notifies THIS pi session when the user saves a secret via
+// creel outside a request_secret call (the tmux keybind runs creel with
+// --event-file <root>/<socket>/<session>.json). Routing must be GLOBALLY
+// unique: a tmux session id (`$0`, `$1`...) is only unique within one tmux
+// server, and we run one socket per project against a shared events root, so
+// the key is scoped by socket name first, session id second. Without this a
+// save on one socket wakes a same-numbered session on every other socket. It
+// watches this socket's subdir, and on a NEW event delivers a value-free note -
+// steering a fresh turn when idle, queuing after the current turn when busy
+// (mirroring pi-wakeup). It is a no-op outside tmux, where there is no keybind
+// to hear.
+export function startCreelWatch(pi: any, deps: Deps = {}): void {
+  const resolveT = deps.resolveTmux ?? resolveTmux;
+  const resolveSid = deps.resolveSessionId ?? defaultResolveSessionId;
+  const home = (deps.homedir ?? homedir)();
+  const startWatch = deps.watch ?? watch;
+  const readEvent = deps.readEventFile ?? ((p: string) => readFileSync(p, "utf-8"));
+  const mtimeMs = deps.eventMtimeMs ?? ((p: string) => statSync(p).mtimeMs);
+  const ensureDir = deps.mkdir ?? ((d: string) => mkdirSync(d, { recursive: true }));
+
+  const tmux = resolveT(process.env);
+  if (!tmux) return;
+  const sid = resolveSid(tmux);
+  if (!sid) return;
+
+  // Scope by socket so `$0` on proj-foo and `$0` on proj-bar never collide in
+  // the shared events root.
+  const dir = join(home, EVENTS_SUBDIR, tmux.socket);
+  try {
+    ensureDir(dir);
+  } catch {
+    return; // nothing to watch if the dir cannot be made
+  }
+  const fileName = `${sid}.json`;
+  const target = join(dir, fileName);
+
+  let ctx: any;
+  pi.on?.("session_start", (_e: unknown, sessionCtx: any) => {
+    ctx = sessionCtx;
+  });
+
+  // Dedupe by mtime: one write can fire the watcher twice (rename+change), and
+  // two saves with identical name/dest/action have identical CONTENT, so mtime
+  // - which advances on every write - is the reliable "is this a new save" key.
+  // Seed from any file left by a PRIOR session at this same sid so a stray dir
+  // event (macOS can deliver a null filename, bypassing the name filter) can
+  // never re-deliver that stale note - only a fresh write, with a new mtime,
+  // fires.
+  let lastMtimeMs = -1;
+  try {
+    lastMtimeMs = mtimeMs(target);
+  } catch {
+    // no pre-existing file - the first real save is a genuine new event
+  }
+  const handle = startWatch(dir, (_event: string, changed: string | null) => {
+    if (changed !== null && changed !== fileName) return;
+    let m: number;
+    try {
+      m = mtimeMs(target);
+    } catch {
+      return; // file gone or unreadable
+    }
+    if (m === lastMtimeMs) return;
+    lastMtimeMs = m;
+    let raw: string;
+    try {
+      raw = readEvent(target);
+    } catch {
+      return;
+    }
+    const evt = parseEvent(raw);
+    if (!evt) return;
+    let idle = false;
+    try {
+      idle = ctx && typeof ctx.isIdle === "function" ? Boolean(ctx.isIdle()) : false;
+    } catch {
+      idle = false;
+    }
+    try {
+      pi.sendMessage(
+        { content: savedMessage(evt), customType: "creel_saved", display: true },
+        { triggerTurn: true, deliverAs: idle ? "steer" : "followUp" },
+      );
+    } catch (error) {
+      try {
+        pi.appendEntry?.("creel_notify_failed", { error: String(error) });
+      } catch {
+        // best-effort
+      }
+    }
+  });
+
+  pi.on?.("session_shutdown", () => {
+    try {
+      handle?.close?.();
+    } catch {
+      // best-effort
+    }
+  });
+}
+
 export default function (pi: any) {
   createCreel(pi);
+  startCreelWatch(pi);
 }

package/src/notify.test.ts

@@ -0,0 +1,41 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { parseEvent, savedMessage } from "./notify.ts";
+
+test("parseEvent accepts a well-formed added/updated event", () => {
+  assert.deepEqual(parseEvent('{"name":"STRIPE_KEY","dest":".env","action":"added"}'), {
+    name: "STRIPE_KEY",
+    dest: ".env",
+    action: "added",
+  });
+  assert.deepEqual(parseEvent('{"name":"K","dest":"config/.env","action":"updated"}'), {
+    name: "K",
+    dest: "config/.env",
+    action: "updated",
+  });
+});
+
+test("parseEvent rejects bad json, missing fields, bad name, bad action", () => {
+  assert.equal(parseEvent("not json"), undefined);
+  assert.equal(parseEvent("{}"), undefined);
+  assert.equal(parseEvent('{"name":"K","dest":".env"}'), undefined); // no action
+  assert.equal(parseEvent('{"name":"BAD-NAME","dest":".env","action":"added"}'), undefined);
+  assert.equal(parseEvent('{"name":"K","dest":".env","action":"deleted"}'), undefined);
+  assert.equal(parseEvent('{"name":"K","dest":"","action":"added"}'), undefined);
+});
+
+test("parseEvent refuses any payload carrying a value field", () => {
+  assert.equal(
+    parseEvent('{"name":"K","dest":".env","action":"added","value":"sk-secret"}'),
+    undefined,
+  );
+});
+
+test("savedMessage names the key and dest, points at process.env, and omits the value", () => {
+  const m = savedMessage({ name: "STRIPE_KEY", dest: ".env", action: "added" });
+  assert.match(m, /STRIPE_KEY/);
+  assert.match(m, /\.env/);
+  assert.match(m, /process\.env\.STRIPE_KEY/);
+  assert.ok(!/sk-/.test(m));
+});

package/src/notify.ts

@@ -0,0 +1,44 @@
+// Pure pieces of the creel-save notifier: the value-free event shape, its
+// parser, and the note the agent receives. None of these ever see the secret
+// value; creel writes only {name, dest, action} to its --event-file, and this
+// code refuses anything carrying a value field.
+
+export type CreelEvent = { name: string; dest: string; action: "added" | "updated" };
+
+// A legal environment-variable name, mirroring creel's own ValidName.
+const NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+// parseEvent reads a creel --event-file payload and returns a CreelEvent only
+// when it is well-formed: a valid env-var name, a non-empty dest, an
+// added/updated action, and crucially NO value field. Anything else (bad JSON,
+// missing fields, or a stray value) returns undefined and is ignored, so a
+// malformed or tampered file can never push a secret into the agent.
+export function parseEvent(raw: string): CreelEvent | undefined {
+  let obj: unknown;
+  try {
+    obj = JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+  if (typeof obj !== "object" || obj === null) return undefined;
+  const rec = obj as Record<string, unknown>;
+  if ("value" in rec) return undefined; // creel never writes one; refuse if present
+  const name = typeof rec.name === "string" ? rec.name : "";
+  const dest = typeof rec.dest === "string" ? rec.dest : "";
+  const action = rec.action === "added" || rec.action === "updated" ? rec.action : "";
+  if (!NAME_RE.test(name) || dest === "" || action === "") return undefined;
+  return { name, dest, action };
+}
+
+// savedMessage is the note the agent receives when the user saves a secret via
+// creel OUTSIDE a request_secret call (the tmux keybind). It names what was
+// captured and where, tells the agent how to reference it, and never carries
+// the value.
+export function savedMessage(e: CreelEvent): string {
+  return (
+    `The user just ${e.action} the secret \`${e.name}\` in \`${e.dest}\` using creel. ` +
+    `The value went straight into that file and is not shown here: reference it as ` +
+    `\`process.env.${e.name}\` (or have your program read \`${e.dest}\` at runtime), and do not ` +
+    `try to read the .env yourself. No action is needed unless you were waiting on this key.`
+  );
+}

package/src/watch.test.ts

@@ -0,0 +1,164 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { startCreelWatch, type Deps, type WatchHandle } from "./index.ts";
+
+type Sent = { content: any; opts: any };
+
+function fakePi() {
+  const sent: Sent[] = [];
+  const handlers: Record<string, (...a: any[]) => void> = {};
+  const pi = {
+    on(evt: string, cb: (...a: any[]) => void) {
+      handlers[evt] = cb;
+    },
+    sendMessage(content: any, opts: any) {
+      sent.push({ content, opts });
+    },
+    appendEntry() {},
+  };
+  return { pi, sent, handlers };
+}
+
+// watchDeps wires a fully-injected Deps: no real fs, no real tmux. `fire`
+// invokes the captured watch callback for this session's file; `closeFake`
+// reports whether the handle was closed.
+// watchDeps models a file that is ABSENT until a save creates it: eventMtimeMs
+// throws while `present` is false (statSync's real behavior on a missing file),
+// so the startup mtime-seed only kicks in when the file already exists. `fire`
+// marks the file present (a save wrote it) before invoking the watch callback,
+// mirroring reality. Pass presentAtStartup:true to simulate a stale file left
+// by a prior session.
+function watchDeps(
+  overrides: Partial<Deps> = {},
+  opts: { presentAtStartup?: boolean; mtime?: number } = {},
+) {
+  let cb: ((e: string, f: string | null) => void) | undefined;
+  let closed = false;
+  let watchedDir: string | undefined;
+  const mkdirCalls: string[] = [];
+  let present = opts.presentAtStartup ?? false;
+  let mt = opts.mtime ?? 1000;
+  const deps: Deps = {
+    resolveTmux: () => ({ socket: "s", pane: "%1" }),
+    resolveSessionId: () => "$3",
+    homedir: () => "/home/u",
+    mkdir: (d) => {
+      mkdirCalls.push(d);
+    },
+    watch: (dir, c) => {
+      watchedDir = dir;
+      cb = c;
+      return { close() { closed = true; } } as WatchHandle;
+    },
+    readEventFile: () => '{"name":"STRIPE_KEY","dest":".env","action":"added"}',
+    eventMtimeMs: () => {
+      if (!present) throw new Error("ENOENT");
+      return mt;
+    },
+    ...overrides,
+  };
+  return {
+    deps,
+    fire: (file: string | null = "$3.json") => {
+      present = true;
+      cb?.("change", file);
+    },
+    setMtime: (v: number) => {
+      mt = v;
+    },
+    isClosed: () => closed,
+    watchedDir: () => watchedDir,
+    mkdirCalls: () => mkdirCalls,
+  };
+}
+
+test("watches (and creates) a socket-scoped events dir, not the shared root", () => {
+  // session ids (`$0`, `$1`...) are unique only within one tmux server, so the
+  // routing key must include the socket name or a save on one socket wakes a
+  // same-id session on another. The watcher scopes to <root>/<socket>.
+  const { pi } = fakePi();
+  const { deps, watchedDir, mkdirCalls } = watchDeps();
+  startCreelWatch(pi, deps);
+  assert.equal(watchedDir(), "/home/u/.pi/agent/creel-events/s");
+  assert.ok(mkdirCalls().includes("/home/u/.pi/agent/creel-events/s"));
+});
+
+test("a pre-existing stale event file does not fire on the first spurious event", () => {
+  // If this session's file already exists at startup (a prior save at the same
+  // sid), a stray dir event (macOS can deliver a null filename) must not
+  // re-deliver the old note. Seeding lastMtimeMs from the file at startup guards
+  // this: an unchanged mtime is skipped.
+  const { pi, sent } = fakePi();
+  const { deps, fire } = watchDeps({}, { presentAtStartup: true, mtime: 1000 });
+  startCreelWatch(pi, deps);
+  fire(null); // null filename falls through the name filter; mtime is unchanged
+  assert.equal(sent.length, 0);
+});
+
+test("delivers a value-free note on a new event, queued after the turn", () => {
+  const { pi, sent } = fakePi();
+  const { deps, fire } = watchDeps();
+  startCreelWatch(pi, deps);
+  fire();
+  assert.equal(sent.length, 1);
+  assert.match(sent[0].content.content, /STRIPE_KEY/);
+  assert.equal(sent[0].content.customType, "creel_saved");
+  assert.equal(sent[0].opts.triggerTurn, true);
+  assert.equal(sent[0].opts.deliverAs, "followUp"); // no ctx captured -> not idle
+});
+
+test("an idle session steers a fresh turn", () => {
+  const { pi, sent, handlers } = fakePi();
+  const { deps, fire } = watchDeps();
+  startCreelWatch(pi, deps);
+  handlers.session_start?.(null, { isIdle: () => true });
+  fire();
+  assert.equal(sent[0].opts.deliverAs, "steer");
+});
+
+test("the same mtime does not re-notify; a new mtime does", () => {
+  const { pi, sent } = fakePi();
+  const { deps, fire, setMtime } = watchDeps();
+  startCreelWatch(pi, deps);
+  fire();
+  fire(); // double-fire of one write -> same mtime -> skipped
+  assert.equal(sent.length, 1);
+  setMtime(2000); // a genuinely new save
+  fire();
+  assert.equal(sent.length, 2);
+});
+
+test("ignores a change to another session's file", () => {
+  const { pi, sent } = fakePi();
+  const { deps, fire } = watchDeps();
+  startCreelWatch(pi, deps);
+  fire("$9.json");
+  assert.equal(sent.length, 0);
+});
+
+test("is a no-op outside tmux and when the session id cannot resolve", () => {
+  const a = fakePi();
+  startCreelWatch(a.pi, watchDeps({ resolveTmux: () => undefined }).deps);
+  assert.equal(a.sent.length, 0);
+  const b = fakePi();
+  startCreelWatch(b.pi, watchDeps({ resolveSessionId: () => undefined }).deps);
+  assert.equal(b.sent.length, 0);
+});
+
+test("ignores a malformed event file", () => {
+  const { pi, sent } = fakePi();
+  const { deps, fire } = watchDeps({ readEventFile: () => "garbage" });
+  startCreelWatch(pi, deps);
+  fire();
+  assert.equal(sent.length, 0);
+});
+
+test("closes the watcher on session shutdown", () => {
+  const { pi, handlers } = fakePi();
+  const { deps, isClosed } = watchDeps();
+  startCreelWatch(pi, deps);
+  assert.equal(isClosed(), false);
+  handlers.session_shutdown?.();
+  assert.equal(isClosed(), true);
+});