pi-creel 0.2.0 → 0.2.2

package/README.md

@@ -17,6 +17,23 @@ user pastes once, and the value goes straight from the popup into the target
 - `name` — the environment-variable name, e.g. `OPENAI_API_KEY`.
 - `dest` — path to the `.env` (relative to cwd), default `.env`.
 
+## Consuming the secret
+
+The value is written to `.env` mid-session, but the pi process env is frozen at
+launch, so the model can't just read `process.env.NAME`. Two supported paths,
+both of which keep the value out of the chat/context:
+
+- **`creel exec NAME[,NAME2,...] -- <command>`** runs `<command>` with each
+  value in its environment **only** — never printed, never in argv, never in an
+  error (a missing key is a hard error naming just the key). This is the
+  language-agnostic way to hand a mid-session key to a child process
+  (`creel exec OPENAI_API_KEY -- node run.mjs`).
+- **`process.env.NAME` after a relaunch**, once the new process inherits the
+  updated `.env`.
+
+The model should **not** read the `.env` itself. The `added` / `updated` reply
+from `request_secret` states this consumption path directly.
+
 ## Requirements
 
 - A tmux session (`$TMUX`). Without one the tool fails fast and asks the user to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-creel",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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/capture.test.ts

@@ -33,3 +33,15 @@ test("tokenToText maps every outcome and never echoes a value", () => {
   assert.match(tokenToText("", "K", ".env"), /Timed out/);
   assert.match(tokenToText("weird", "K", ".env"), /unexpected status \(weird\)/);
 });
+
+test("a successful capture tells the model how to consume the secret", () => {
+  for (const token of ["added", "updated"]) {
+    const text = tokenToText(token, "TYPESAFE_API_KEY", ".env");
+    // Points at the containment path (creel exec) with the real var name...
+    assert.match(text, /creel exec TYPESAFE_API_KEY -- /);
+    // ...and the relaunch fallback...
+    assert.match(text, /process\.env\.TYPESAFE_API_KEY/);
+    // ...and steers the model away from reading the .env itself.
+    assert.match(text, /do not read|don't read/i);
+  }
+});

package/src/capture.ts

@@ -46,11 +46,18 @@ export function tokenToText(
   if (token === undefined || token === "") {
     return `Timed out waiting for the creel popup; nothing was recorded for ${name}.`;
   }
+  // howToUse tells the model the two supported ways to consume a mid-session
+  // secret without ever handling the value itself. It must never suggest
+  // reading the .env directly (the value must not enter the harness/context).
+  const howToUse =
+    ` The value was not shown here. To use it, run \`creel exec ${name} -- <command>\`` +
+    ` (that puts ${name} in the command's environment only), or read \`process.env.${name}\`` +
+    ` after a relaunch. Do not read ${dest} yourself.`;
   switch (token) {
     case "added":
-      return `Added ${name} to ${dest} (chmod 600). The value was not shown here.`;
+      return `Added ${name} to ${dest} (chmod 600).` + howToUse;
     case "updated":
-      return `Updated ${name} in ${dest}. The value was not shown here.`;
+      return `Updated ${name} in ${dest}.` + howToUse;
     case "cancelled":
       return `Capture cancelled; nothing was written for ${name}.`;
     default:

package/src/index.ts

@@ -182,11 +182,15 @@ function defaultResolveSessionId(tmux: TmuxContext): string | 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.
+// --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;
@@ -201,7 +205,9 @@ export function startCreelWatch(pi: any, deps: Deps = {}): void {
   const sid = resolveSid(tmux);
   if (!sid) return;
 
-  const dir = join(home, EVENTS_SUBDIR);
+  // 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 {
@@ -218,7 +224,16 @@ export function startCreelWatch(pi: any, deps: Deps = {}): void {
   // 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;

package/src/watch.test.ts

@@ -23,29 +23,79 @@ function fakePi() {
 // 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> = {}) {
+// 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: () => {},
-    watch: (_dir, c) => {
+    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: () => 1000,
+    eventMtimeMs: () => {
+      if (!present) throw new Error("ENOENT");
+      return mt;
+    },
     ...overrides,
   };
   return {
     deps,
-    fire: (file: string | null = "$3.json") => cb?.("change", file),
+    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();
@@ -69,13 +119,12 @@ test("an idle session steers a fresh turn", () => {
 
 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 });
+  const { deps, fire, setMtime } = watchDeps();
   startCreelWatch(pi, deps);
   fire();
   fire(); // double-fire of one write -> same mtime -> skipped
   assert.equal(sent.length, 1);
-  mt = 2000; // a genuinely new save
+  setMtime(2000); // a genuinely new save
   fire();
   assert.equal(sent.length, 2);
 });