pi-creel 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-creel",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "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 {
@@ -52,12 +61,18 @@ function defaultCreelOnPath(): boolean {
 function defaultSpawnPopup(tmux: TmuxContext, command: string): void {
   // display-popup returns immediately (the popup runs detached on the server),
   // so completion is observed out-of-band via the status file.
+  //
+  // -d anchors the popup's working directory to this process's cwd — the folder
+  // pi was launched in, i.e. the project being worked on. creel resolves a
+  // relative --dest (".env") against that cwd, so the key lands in the project's
+  // .env. Without -d, tmux opens the popup in $HOME and the .env goes there.
   execFileSync(
     "tmux",
     [
       "-L", tmux.socket,
       "display-popup",
       "-t", tmux.pane,
+      "-d", process.cwd(),
       "-E",
       "-w", POPUP_WIDTH,
       "-h", POPUP_HEIGHT,
@@ -104,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 : "";
@@ -146,6 +161,112 @@ 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 <dir>/<session>.json). It resolves the session id so a save in
+// one session never notifies another (routing by tmux session), watches the
+// events dir, 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;
+
+  const dir = join(home, EVENTS_SUBDIR);
+  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.
+  let lastMtimeMs = -1;
+  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,115 @@
+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.
+function watchDeps(overrides: Partial<Deps> = {}) {
+  let cb: ((e: string, f: string | null) => void) | undefined;
+  let closed = false;
+  const deps: Deps = {
+    resolveTmux: () => ({ socket: "s", pane: "%1" }),
+    resolveSessionId: () => "$3",
+    homedir: () => "/home/u",
+    mkdir: () => {},
+    watch: (_dir, c) => {
+      cb = c;
+      return { close() { closed = true; } } as WatchHandle;
+    },
+    readEventFile: () => '{"name":"STRIPE_KEY","dest":".env","action":"added"}',
+    eventMtimeMs: () => 1000,
+    ...overrides,
+  };
+  return {
+    deps,
+    fire: (file: string | null = "$3.json") => cb?.("change", file),
+    isClosed: () => closed,
+  };
+}
+
+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();
+  let mt = 1000;
+  const { deps, fire } = watchDeps({ eventMtimeMs: () => mt });
+  startCreelWatch(pi, deps);
+  fire();
+  fire(); // double-fire of one write -> same mtime -> skipped
+  assert.equal(sent.length, 1);
+  mt = 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);
+});