pi-creel 0.2.1 → 0.2.3

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.1",
+  "version": "0.2.3",
   "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

@@ -28,8 +28,20 @@ test("tokenToText maps every outcome and never echoes a value", () => {
   assert.match(tokenToText("added", "OPENAI_API_KEY", ".env"), /Added OPENAI_API_KEY to \.env/);
   assert.match(tokenToText("updated", "OPENAI_API_KEY", ".env"), /Updated OPENAI_API_KEY in \.env/);
   assert.match(tokenToText("cancelled", "K", ".env"), /cancelled/i);
-  assert.match(tokenToText("error:dest-outside-cwd", "K", ".env"), /Could not store K: dest-outside-cwd/);
+  assert.match(tokenToText("error:dest-outside-cwd", "K", ".env", "/p"), /Could not store K: dest must be inside the working directory \(\/p\)/);
   assert.match(tokenToText(undefined, "K", ".env"), /Timed out/);
   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

@@ -1,3 +1,4 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
 // Pure pieces of the request_secret tool: parameter schema, env-var name
 // validation, the popup command string, and the status-token -> reply mapping.
 // None of these ever see the captured value — creel writes it straight to the
@@ -14,7 +15,7 @@ export const REQUEST_SECRET_PARAMS = {
     dest: {
       type: "string",
       description:
-        "Path to the .env file to write, relative to the working directory. Defaults to .env.",
+        "Path to the .env file to write. Must be inside the working directory (relative, e.g. .env or .worktrees/<name>/.env); creel refuses anything outside it. Defaults to .env.",
     },
   },
   required: ["name"],
@@ -38,22 +39,49 @@ export function creelCommand(name: string, dest: string, statusFile: string): st
 
 // tokenToText maps creel's status token to the reply the model sees. It never
 // includes the secret — only the outcome.
+// destInsideCwd mirrors creel's own rule (ResolveDest): an agent-chosen dest
+// resolves against the working directory and may not leave it. Checked here
+// too, so a refused path never opens a popup the user then sees fail.
+export function destInsideCwd(cwd: string, dest: string): boolean {
+  const rel = relative(cwd, resolve(cwd, dest));
+  return rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+
+// outsideCwdText is the reply for a dest outside the working directory: the
+// rule, and a path that works.
+export function outsideCwdText(name: string, cwd: string): string {
+  return (
+    `Could not store ${name}: dest must be inside the working directory (${cwd}), ` +
+    "so a secret only lands where this project keeps its own files. Use a path under it, " +
+    "e.g. .env, or .worktrees/<name>/.env for scratch work; nothing was written."
+  );
+}
+
 export function tokenToText(
   token: string | undefined,
   name: string,
   dest: string,
+  cwd: string = process.cwd(),
 ): string {
   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:
+      if (token === "error:dest-outside-cwd") return outsideCwdText(name, cwd);
       if (token.startsWith("error:")) {
         return `Could not store ${name}: ${token.slice("error:".length)}.`;
       }

package/src/index.test.ts

@@ -89,6 +89,56 @@ test("reports a timeout when no token arrives", async () => {
 
 test("surfaces a creel error token", async () => {
   const reg = harness(okDeps({ waitForToken: async () => "error:dest-outside-cwd" }));
-  const text = await run(reg, { name: "K", dest: "../x.env" });
-  assert.match(text, /Could not store K: dest-outside-cwd/);
+  const text = await run(reg, { name: "K", dest: "sub/.env" });
+  assert.match(text, /Could not store K: dest must be inside the working directory/);
+});
+
+// The popup exits non-zero when creel refuses (tmux then throws), but creel has
+// already written its reason to the status file: the agent must get that
+// reason, not a bare "Command failed".
+test("a popup that exits non-zero still reports creel's reason", async () => {
+  const reg = harness(okDeps({
+    spawnPopup: () => { throw new Error("Command failed: tmux display-popup ..."); },
+    readStatus: () => "error:dest-outside-cwd",
+  }));
+  const text = await run(reg, { name: "K", dest: "sub/.env" });
+  assert.match(text, /Could not store K/);
+  assert.match(text, /inside the working directory/);
+  assert.doesNotMatch(text, /Command failed/);
+});
+
+test("a popup that fails with no status keeps the tmux error", async () => {
+  const reg = harness(okDeps({
+    spawnPopup: () => { throw new Error("no server running"); },
+    readStatus: () => undefined,
+  }));
+  assert.match(await run(reg, { name: "K" }), /Failed to run the creel popup: .*no server running/);
+});
+
+// A dest outside the working directory is refused before any popup opens, with
+// the rule and a path that works.
+test("a dest outside the working directory is refused without opening the popup", async () => {
+  for (const dest of ["../../tmp/x/.env", "/tmp/x/.env"]) {
+    let spawned = false;
+    const reg = harness(okDeps({ spawnPopup: () => { spawned = true; } }));
+    const text = await run(reg, { name: "K", dest });
+    assert.equal(spawned, false, `popup opened for ${dest}`);
+    assert.match(text, /inside the working directory/);
+    assert.match(text, /\.worktrees\//);
+  }
+});
+
+test("a dest inside the working directory, absolute or relative, opens the popup", async () => {
+  for (const dest of [".worktrees/check/.env", `${process.cwd()}/sub/.env`]) {
+    let spawned = false;
+    const reg = harness(okDeps({ spawnPopup: () => { spawned = true; } }));
+    await run(reg, { name: "K", dest });
+    assert.equal(spawned, true, `popup not opened for ${dest}`);
+  }
+});
+
+test("the tool description states the dest rule", () => {
+  let def: any;
+  createCreel({ registerTool(d: any) { def = d; } }, okDeps());
+  assert.match(def.parameters.properties.dest.description, /inside the working directory/);
 });

package/src/index.ts

@@ -24,6 +24,8 @@ import {
   REQUEST_SECRET_PARAMS,
   creelCommand,
   tokenToText,
+  destInsideCwd,
+  outsideCwdText,
   validName,
 } from "./capture.ts";
 import { parseEvent, savedMessage } from "./notify.ts";
@@ -41,6 +43,7 @@ export type Deps = {
   spawnPopup?: (tmux: TmuxContext, command: string) => void;
   waitForToken?: (statusPath: string, timeoutMs: number) => Promise<string | undefined>;
   tmpStatusPath?: () => string;
+  readStatus?: (statusPath: string) => string | undefined;
   resolveSessionId?: (tmux: TmuxContext) => string | undefined;
   homedir?: () => string;
   watch?: (dir: string, cb: (event: string, filename: string | null) => void) => WatchHandle;
@@ -49,6 +52,14 @@ export type Deps = {
   mkdir?: (dir: string) => void;
 };
 
+function defaultReadStatus(statusPath: string): string | undefined {
+  try {
+    return existsSync(statusPath) ? readFileSync(statusPath, "utf-8").trim() || undefined : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 function defaultCreelOnPath(): boolean {
   try {
     execFileSync("creel", ["version"], { stdio: "ignore" });
@@ -114,6 +125,7 @@ export function createCreel(pi: any, deps: Deps = {}): void {
   const spawn = deps.spawnPopup ?? defaultSpawnPopup;
   const wait = deps.waitForToken ?? defaultWaitForToken;
   const tmpPath = deps.tmpStatusPath ?? defaultTmpStatusPath;
+  const readStatus = deps.readStatus ?? defaultReadStatus;
 
   pi.registerTool({
     name: "request_secret",
@@ -143,12 +155,20 @@ export function createCreel(pi: any, deps: Deps = {}): void {
         );
       }
 
+      if (!destInsideCwd(process.cwd(), dest)) {
+        return reply(outsideCwdText(name, process.cwd()));
+      }
+
       const statusPath = tmpPath();
       try {
         spawn(tmux, creelCommand(name, dest, statusPath));
         const token = await wait(statusPath, TOKEN_TIMEOUT_MS);
         return reply(tokenToText(token, name, dest));
       } catch (error) {
+        // creel exits non-zero when it refuses, and tmux then reports a bare
+        // "Command failed"; creel's reason is already in the status file.
+        const token = readStatus(statusPath);
+        if (token) return reply(tokenToText(token, name, dest));
         return reply(`Failed to run the creel popup: ${String(error)}`);
       } finally {
         try {