pi-robot-hand 0.1.0 → 0.2.0

package/lib/apply.ts

@@ -0,0 +1,148 @@
+/**
+ * Apply a staged secret to its destination. The user runs this through a pi `!` command, so its
+ * output reaches the model: it reports what changed and a length check, never the value.
+ * Compiled to dist/apply.js, which the prefilled command runs with node.
+ */
+
+import { spawn } from "node:child_process";
+import { open, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { parseArgs } from "node:util";
+import { checkValue, describePlacement, ENV_QUOTES, type EnvQuote, type Placement, validatePlacement } from "./placement.ts";
+import { shellQuote } from "./shell.ts";
+import { parseFileMode, readExisting, writeSecret } from "./write.ts";
+
+interface Options {
+	quote?: string;
+	flags?: string;
+	mode?: string;
+	overwrite?: boolean;
+}
+
+const USAGE = `usage:
+  apply.js env <destination> <KEY> --from <staged> [--quote auto|none|single|double] [--mode 600]
+  apply.js regex <destination> <regex> --from <staged> [--flags g] [--mode 600]
+  apply.js file <destination> --from <staged> [--overwrite] [--mode 600]
+  apply.js exec <command using {secret}> --from <staged>`;
+
+/**
+ * Overwrite then delete the staged file.
+ */
+async function wipe(path: string): Promise<void> {
+	try {
+		const { size } = await stat(path);
+		const handle = await open(path, "r+");
+		try {
+			await handle.write(Buffer.alloc(size), 0, size, 0);
+		} finally {
+			await handle.close();
+		}
+	} catch {
+		// Missing or unwritable: removal below still runs.
+	}
+	await rm(path, { force: true });
+}
+
+function redact(value: string, text: string): string {
+	return value.length > 0 ? text.split(value).join("[REDACTED]") : text;
+}
+
+function chars(value: string): number {
+	return [...value].length;
+}
+
+/**
+ * Run a shell command with {secret} replaced by the staged file path. Stdout is discarded.
+ */
+async function runCommand(command: string, staged: string, value: string): Promise<string> {
+	if (!command.includes("{secret}")) throw new Error("exec command must reference {secret}.");
+	const script = command.split("{secret}").join(shellQuote(staged));
+	const child = spawn("sh", ["-c", script], { stdio: ["ignore", "pipe", "pipe"] });
+	let stdoutBytes = 0;
+	let stderr = "";
+	child.stdout.on("data", (chunk: Buffer) => {
+		stdoutBytes += chunk.length;
+	});
+	child.stderr.on("data", (chunk: Buffer) => {
+		stderr += chunk.toString("utf8");
+	});
+	const code = await new Promise<number | null>((resolve, reject) => {
+		child.on("error", reject);
+		child.on("close", resolve);
+	});
+	if (code !== 0) {
+		const tail = redact(value, stderr).trim().split("\n").slice(-15).join("\n");
+		throw new Error(`command exited ${code}${tail ? `:\n${tail}` : ""}`);
+	}
+	const suppressed = stdoutBytes > 0 ? `; ${stdoutBytes} bytes of stdout suppressed` : "";
+	return `command exited 0 — secret delivered via {secret} (${chars(value)} chars)${suppressed}`;
+}
+
+async function apply(format: string | undefined, args: string[], options: Options, staged: string, value: string): Promise<string> {
+	if (format === "exec") {
+		if (args.length !== 1 || !args[0]) throw new Error(USAGE);
+		return runCommand(args[0], staged, value);
+	}
+
+	let placement: Placement;
+	const destination = args[0];
+	if (format === "env" && args.length === 2 && destination && args[1]) {
+		const quote = options.quote ?? "auto";
+		if (!(ENV_QUOTES as readonly string[]).includes(quote)) throw new Error(`Invalid quote "${quote}".`);
+		placement = { mode: "env", key: args[1], quote: quote as EnvQuote };
+	} else if (format === "regex" && args.length === 2 && destination && args[1]) {
+		placement = { mode: "regex", pattern: args[1], flags: options.flags ?? "" };
+	} else if (format === "file" && args.length === 1 && destination) {
+		placement = { mode: "file" };
+	} else {
+		throw new Error(USAGE);
+	}
+
+	const fileMode = parseFileMode(options.mode);
+	const problem = checkValue(placement, value);
+	if (problem) throw new Error(problem);
+	validatePlacement(placement, await readExisting(destination), options.overwrite === true);
+	const outcome = await writeSecret(destination, placement, value, fileMode);
+	const where = `${destination} (${describePlacement(placement)}, mode ${outcome.mode.toString(8)})`;
+	return `${outcome.summary} in ${where} — length check passed (${chars(value)} chars)`;
+}
+
+async function main() {
+	const { values, positionals } = parseArgs({
+		allowPositionals: true,
+		options: {
+			from: { type: "string" },
+			quote: { type: "string" },
+			flags: { type: "string" },
+			mode: { type: "string" },
+			overwrite: { type: "boolean" },
+		},
+	});
+	const staged = values.from;
+	if (!staged) {
+		console.error(USAGE);
+		process.exitCode = 2;
+		return;
+	}
+	const [format, ...args] = positionals;
+	const resultFile = `${staged}.result`;
+	let value = "";
+	try {
+		try {
+			value = await readFile(staged, "utf8");
+		} catch {
+			throw new Error("staged secret not found; it was already applied or discarded. Call secret_drop again.");
+		}
+		const message = await apply(format, args, values, staged, value);
+		await writeFile(resultFile, JSON.stringify({ ok: true, message }), { mode: 0o600 });
+		console.log(`✓ secret-drop: ${message}`);
+	} catch (error) {
+		const message = redact(value, (error as Error).message);
+		await writeFile(resultFile, JSON.stringify({ ok: false, message }), { mode: 0o600 }).catch(() => undefined);
+		console.error(`✗ secret-drop: ${message}`);
+		process.exitCode = 1;
+	} finally {
+		await wipe(staged);
+	}
+}
+
+await main();

package/lib/placement.ts

@@ -0,0 +1,227 @@
+/**
+ * Pure placement logic: where a secret goes inside a file, and how to find it again.
+ */
+
+export type EnvQuote = "auto" | "none" | "single" | "double";
+
+export type Placement =
+	| { mode: "file" }
+	| { mode: "env"; key: string; quote: EnvQuote }
+	| { mode: "regex"; pattern: string; flags: string };
+
+export interface PlacementResult {
+	content: string;
+	summary: string;
+}
+
+export const ENV_QUOTES: readonly EnvQuote[] = ["auto", "none", "single", "double"];
+
+const ENV_KEY = /^[A-Za-z_][A-Za-z0-9_.]*$/;
+const SAFE_UNQUOTED = /^[A-Za-z0-9_\-.,/:@%+=]*$/;
+
+function escapeRegExp(text: string): string {
+	return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function envLinePattern(key: string): RegExp {
+	return new RegExp(`^([ \\t]*(?:export[ \\t]+)?${escapeRegExp(key)}[ \\t]*=)(.*)$`, "gm");
+}
+
+/**
+ * Compile the placement regex with match indices so the first capture group can be replaced.
+ */
+function compileRegex(pattern: string, flags: string): RegExp {
+	const cleaned = [...new Set(flags.replace(/d/g, ""))].join("");
+	return new RegExp(pattern, `${cleaned}d`);
+}
+
+/**
+ * Throw when the env key or regex is malformed. Needs no file.
+ */
+export function validateSyntax(placement: Placement): void {
+	if (placement.mode === "env" && !ENV_KEY.test(placement.key)) {
+		throw new Error(`Invalid env key "${placement.key}". Use letters, digits, "_" or ".", not starting with a digit.`);
+	}
+	if (placement.mode === "regex") {
+		try {
+			compileRegex(placement.pattern, placement.flags);
+		} catch (error) {
+			throw new Error(`Invalid regex: ${(error as Error).message}`);
+		}
+	}
+}
+
+/**
+ * Return a message when a file placement would replace an existing file without `overwrite`.
+ */
+export function checkOverwrite(placement: Placement, exists: boolean, overwrite: boolean): string | undefined {
+	if (placement.mode !== "file" || !exists || overwrite) return undefined;
+	return "The destination exists and file placement would replace all of it. Use env or regex to change one value; pass overwrite only for single-value files such as keys or password files.";
+}
+
+/**
+ * Throw when the placement cannot be applied to `existing` (undefined for a missing file).
+ */
+export function validatePlacement(placement: Placement, existing: string | undefined, overwrite = false): void {
+	validateSyntax(placement);
+	const refused = checkOverwrite(placement, existing !== undefined, overwrite);
+	if (refused) throw new Error(refused);
+	if (placement.mode !== "regex") return;
+	if (existing === undefined) throw new Error("regex placement needs an existing file to locate the insertion point.");
+	if (!compileRegex(placement.pattern, placement.flags).test(existing)) {
+		throw new Error(`Pattern /${placement.pattern}/${placement.flags} does not match the destination file.`);
+	}
+}
+
+function resolveQuote(quote: EnvQuote, value: string): Exclude<EnvQuote, "auto"> {
+	if (quote !== "auto") return quote;
+	if (SAFE_UNQUOTED.test(value)) return "none";
+	return value.includes("'") ? "double" : "single";
+}
+
+/**
+ * Return a message when the placement cannot represent `value`, otherwise undefined.
+ */
+export function checkValue(placement: Placement, value: string): string | undefined {
+	if (value.length === 0) return "Value is empty.";
+	if (placement.mode !== "file" && /[\r\n]/.test(value)) return `${placement.mode} placement needs a single-line value.`;
+	if (placement.mode === "env") {
+		const q = resolveQuote(placement.quote, value);
+		if (q === "none" && !SAFE_UNQUOTED.test(value)) return "Value needs quoting; use quote auto, single, or double.";
+		if (q === "single" && value.includes("'")) return "Value contains a single quote; use quote auto or double.";
+	}
+	return undefined;
+}
+
+export function encodeEnvValue(value: string, quote: EnvQuote): string {
+	switch (resolveQuote(quote, value)) {
+		case "none":
+			return value;
+		case "single":
+			return `'${value}'`;
+		case "double":
+			return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\$/g, "\\$").replace(/`/g, "\\`")}"`;
+	}
+}
+
+/**
+ * Split the text after `KEY=` into the value and a trailing ` # comment` outside quotes.
+ * The comment keeps its leading whitespace; an unterminated quote yields no comment.
+ */
+export function splitEnvComment(raw: string): { value: string; comment: string } {
+	const start = raw.length - raw.trimStart().length;
+	const quote = raw[start];
+	if (quote === "'" || quote === '"') {
+		let end = start + 1;
+		while (end < raw.length && raw[end] !== quote) end += quote === '"' && raw[end] === "\\" ? 2 : 1;
+		const rest = raw.slice(end + 1);
+		if (end < raw.length && /^\s*#/.test(rest)) return { value: raw.slice(0, end + 1), comment: rest };
+		return { value: raw, comment: "" };
+	}
+	const hash = raw.search(/\s#/);
+	return hash === -1 ? { value: raw, comment: "" } : { value: raw.slice(0, hash), comment: raw.slice(hash) };
+}
+
+export function decodeEnvValue(raw: string): string {
+	const trimmed = splitEnvComment(raw).value.trim();
+	if (trimmed.length >= 2 && trimmed.startsWith("'") && trimmed.endsWith("'")) return trimmed.slice(1, -1);
+	if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
+		return trimmed.slice(1, -1).replace(/\\([\\"$`])/g, "$1");
+	}
+	return trimmed;
+}
+
+/**
+ * Produce the new file content with the secret placed. `existing` is undefined for a new file.
+ */
+export function applyPlacement(existing: string | undefined, placement: Placement, value: string): PlacementResult {
+	switch (placement.mode) {
+		case "file":
+			return { content: value, summary: existing === undefined ? "created file" : "replaced file content" };
+		case "env": {
+			const encoded = encodeEnvValue(value, placement.quote);
+			const base = existing ?? "";
+			const re = envLinePattern(placement.key);
+			if (re.test(base)) {
+				re.lastIndex = 0;
+				let count = 0;
+				const content = base.replace(re, (_match, prefix: string, old: string) => {
+					count += 1;
+					const { comment } = splitEnvComment(old.replace(/\r$/, ""));
+					return `${prefix}${encoded}${comment}${old.endsWith("\r") ? "\r" : ""}`;
+				});
+				return { content, summary: `updated ${placement.key} (${count} line${count === 1 ? "" : "s"})` };
+			}
+			const separator = base.length === 0 || base.endsWith("\n") ? "" : "\n";
+			return { content: `${base}${separator}${placement.key}=${encoded}\n`, summary: `appended ${placement.key}` };
+		}
+		case "regex": {
+			if (existing === undefined) throw new Error("regex placement needs an existing file.");
+			const re = compileRegex(placement.pattern, placement.flags);
+			let content = "";
+			let cursor = 0;
+			let count = 0;
+			re.lastIndex = 0;
+			let match: RegExpExecArray | null;
+			while ((match = re.exec(existing)) !== null) {
+				const span = match.indices?.[1] ?? match.indices?.[0];
+				if (!span) break;
+				content += existing.slice(cursor, span[0]) + value;
+				cursor = span[1];
+				count += 1;
+				if (!re.global) break;
+				if (match[0].length === 0) re.lastIndex += 1;
+			}
+			if (count === 0) throw new Error(`Pattern /${placement.pattern}/${placement.flags} does not match the destination file.`);
+			content += existing.slice(cursor);
+			return { content, summary: `replaced ${count} regex match${count === 1 ? "" : "es"}` };
+		}
+	}
+}
+
+/**
+ * Check that `content` holds `value` at the placement. Used after a write.
+ */
+export function verifyPlaced(content: string, placement: Placement, value: string): boolean {
+	if (placement.mode === "file") return content === value;
+	if (placement.mode === "env") return extractSecret(content, placement) === value;
+	return content.includes(value);
+}
+
+/**
+ * Recover the stored secret from file content, for redaction after a restart.
+ */
+export function extractSecret(content: string, placement: Placement): string | undefined {
+	switch (placement.mode) {
+		case "file":
+			return content.length > 0 ? content : undefined;
+		case "env": {
+			let last: string | undefined;
+			for (const match of content.matchAll(envLinePattern(placement.key))) last = decodeEnvValue(match[2] ?? "");
+			return last ? last : undefined;
+		}
+		case "regex": {
+			let re: RegExp;
+			try {
+				re = compileRegex(placement.pattern, placement.flags);
+			} catch {
+				return undefined;
+			}
+			const match = re.exec(content);
+			if (!match) return undefined;
+			const value = match[1] ?? match[0];
+			return value.length > 0 ? value : undefined;
+		}
+	}
+}
+
+export function describePlacement(placement: Placement): string {
+	switch (placement.mode) {
+		case "file":
+			return "whole file";
+		case "env":
+			return `env ${placement.key}`;
+		case "regex":
+			return `regex /${placement.pattern}/${placement.flags}`;
+	}
+}

package/lib/shell.ts

@@ -0,0 +1,9 @@
+/**
+ * POSIX shell quoting for the commands shown to and run by the user.
+ */
+
+const SAFE = /^[A-Za-z0-9_\-.,/:@%+=]+$/;
+
+export function shellQuote(word: string): string {
+	return SAFE.test(word) ? word : `'${word.replace(/'/g, `'\\''`)}'`;
+}

package/lib/write.ts

@@ -0,0 +1,79 @@
+/**
+ * Atomic file write for a placed secret.
+ */
+
+import { randomBytes } from "node:crypto";
+import { chmod, mkdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { applyPlacement, type Placement, verifyPlaced } from "./placement.ts";
+
+export interface WriteOutcome {
+	bytes: number;
+	created: boolean;
+	mode: number;
+	summary: string;
+}
+
+export const DEFAULT_NEW_FILE_MODE = 0o600;
+
+export async function readExisting(path: string): Promise<string | undefined> {
+	try {
+		return await readFile(path, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+/**
+ * Replace `path` with `content` through a temp file and rename, so readers never see a partial file.
+ */
+async function atomicWrite(path: string, content: string, mode: number): Promise<void> {
+	const tmp = join(dirname(path), `.${basename(path)}.${randomBytes(6).toString("hex")}.tmp`);
+	try {
+		await writeFile(tmp, content, { mode: 0o600, flag: "wx" });
+		await chmod(tmp, mode);
+		await rename(tmp, path);
+	} catch (error) {
+		await unlink(tmp).catch(() => undefined);
+		throw error;
+	}
+}
+
+/**
+ * Place `value` into `path`, write it atomically, and re-read it with `verify`.
+ * When the check fails, the original content and mode are restored from memory (a new file is
+ * removed) and the call throws; no backup file is ever written.
+ * New files get `fileMode ?? 0600`; existing files keep their mode unless `fileMode` is given.
+ */
+export async function writeSecret(
+	path: string,
+	placement: Placement,
+	value: string,
+	fileMode: number | undefined,
+	verify: (content: string, placement: Placement, value: string) => boolean = verifyPlaced,
+): Promise<WriteOutcome> {
+	const existing = await readExisting(path);
+	const { content, summary } = applyPlacement(existing, placement, value);
+	const created = existing === undefined;
+	const originalMode = created ? undefined : (await stat(path)).mode & 0o777;
+	const mode = fileMode ?? originalMode ?? DEFAULT_NEW_FILE_MODE;
+
+	await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+	await atomicWrite(path, content, mode);
+	if (!verify(await readFile(path, "utf8"), placement, value)) {
+		if (existing === undefined || originalMode === undefined) await unlink(path);
+		else await atomicWrite(path, existing, originalMode);
+		throw new Error(`verification failed after writing; ${created ? "removed the new file" : "restored the original content"}.`);
+	}
+	return { bytes: Buffer.byteLength(content), created, mode, summary };
+}
+
+/**
+ * Parse an octal permission string such as "600".
+ */
+export function parseFileMode(raw: string | undefined): number | undefined {
+	if (raw === undefined) return undefined;
+	if (!/^0?[0-7]{3}$/.test(raw)) throw new Error(`Invalid file mode "${raw}". Use octal like "600".`);
+	return Number.parseInt(raw, 8);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-robot-hand",
-  "version": "0.1.0",
-  "description": "Pi extension: the agent hands the user a command, and after the user agrees it lands in the pi prompt or the clipboard, never run by the agent",
+  "version": "0.2.0",
+  "description": "The lazy kit for pi: no IDE, no copy-paste, safety net still on. The agent hands you commands (prompt, clipboard, or a Herdr pane that reports back), answers your ! commands, and takes secrets through a masked dialog it never sees",
   "type": "module",
   "license": "MIT",
   "author": "wayne930242",
@@ -17,21 +17,34 @@
     "extension",
     "clipboard",
     "command",
-    "approval"
+    "approval",
+    "herdr",
+    "secret",
+    "dotenv"
   ],
   "files": [
     "src",
+    "lib",
+    "dist",
+    "skills",
     "README.md",
     "LICENSE"
   ],
   "pi": {
     "extensions": [
-      "./src/index.ts"
+      "./src/index.ts",
+      "./src/follow-up.ts",
+      "./src/secret-drop/index.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "scripts": {
+    "build": "tsc -p tsconfig.build.json",
     "check": "tsc --noEmit",
-    "test": "node --test tests/*.test.ts"
+    "test": "npm run build && node --test tests/*.test.ts",
+    "prepack": "npm run build"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",

package/skills/secret-drop/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: secret-drop
+description: Use when a password, token, API key, certificate, or other credential must be written to a file or fed to a command, or when working with a file that holds one.
+---
+
+# Secret Drop
+
+Secrets reach files and commands through the `secret_drop` tool, so the value never enters the conversation. The user follows the steps you give, types it into a masked dialog or asks you a question instead; it is staged outside the project; pi pre-fills a `!` apply command in the user's prompt; the user runs it. The tool waits for that run and returns the apply script's report: what changed and a length check. Files that hold secrets are opaque to the agent: programs consume them, the agent never reads them.
+
+## Writing a secret
+
+1. Pick the destination the consuming program expects. For a `regex` placement in a file that is not yet protected, read its structure first.
+2. Call `secret_drop` with a `label` naming exactly what to enter (service, account, environment), `instructions` the user can follow without asking (the exact page or menu path, every field to fill in such as name, scope, permissions, and expiration, and what to copy), the page as `url` when there is one, both in the user's language, and one format:
+   - `key` + `destination` (format `env`): sets `KEY=value`, replacing existing `KEY` / `export KEY` lines or appending one. Other lines and trailing comments stay. For a file read by `docker --env-file`, pass `quote: "none"`, since Docker keeps quotes as part of the value.
+   - `format: "regex"` + `destination` + `regex`: replaces capture group 1, or the whole match, in an existing file. Make the group cover only the value, e.g. `password: "([^"]*)"`.
+   - `format: "file"` + `destination`: the whole file is the secret, for key files and single-value files. An existing destination is refused unless `overwrite: true` is passed; pass it only to rotate a single-value file, never for a multi-value file such as `.env`.
+   - `command` (format `command`): a shell command that reads the staged file `{secret}`. Redirect results into files; stdout is discarded. Examples:
+     - `ansible-vault encrypt_string --vault-password-file .vault-pass --stdin-name db_password < {secret} >> group_vars/prod/vault.yml`
+     - `gh secret set DEPLOY_TOKEN < {secret}`
+     - `kubectl create secret generic app-tls --from-file=tls.key={secret}`
+3. Call it once per secret and wait for the result:
+   - **Applied**: the report states the change and `length check passed (N chars)`. That report is the verification; the value is in place.
+   - **Question**: the user pressed Tab and asked instead; nothing was staged. Answer it, then call `secret_drop` again.
+   - **Cancelled or aborted**: nothing was applied. Ask the user how to proceed.
+   - **Apply failed**: the staged value was discarded. Fix the parameters from the error (a regex that does not match, a failing command) and call again.
+
+When the user offers to paste a secret into chat, call `secret_drop` instead.
+
+## Using a file that holds a secret
+
+Let the program that needs the secret read the file itself: a script that loads `.env` internally, a `--env-file` or `--vault-password-file` flag, or a config path. Once `secret_drop` applies a secret, `read`, `edit`, `write`, `grep`, and bash commands that print or copy the destination are blocked, and tool output containing the value shows `[REDACTED]`. Other safety extensions block secret files such as `.env` too. When a consuming command is blocked, ask the user to run it with `!`, and continue from its output.
+
+To change a value, call `secret_drop` again with the same destination and placement. When non-secret lines in a protected file need edits, ask the user to make them.

package/src/follow-up.ts

@@ -0,0 +1,54 @@
+/**
+ * `!` follow-up: pi records a `!` command's output but starts no turn. This extension leaves
+ * execution to pi (keeping live output and every other user_bash handler), watches the session
+ * until the command's bashExecution entry lands, then starts one turn. `!!` commands, cancelled
+ * commands, and commands typed while the agent is busy keep pi's behavior.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export const POLL_MS = 200;
+export const FOLLOW_UP_TYPE = "robot-hand-follow-up";
+export const FOLLOW_UP_PROMPT = "The user just ran the shell command above with `!`. Read its output and respond to it.";
+
+interface Recorded {
+	cancelled?: boolean;
+}
+
+function recorded(ctx: ExtensionContext, since: string | null, command: string): Recorded | undefined {
+	let id = ctx.sessionManager.getLeafId();
+	while (id && id !== since) {
+		const entry = ctx.sessionManager.getEntry(id);
+		if (!entry) return undefined;
+		if (entry.type === "message" && entry.message.role === "bashExecution" && entry.message.command === command) {
+			return entry.message;
+		}
+		id = entry.parentId;
+	}
+	return undefined;
+}
+
+export default function followUp(pi: ExtensionAPI): void {
+	let timer: ReturnType<typeof setInterval> | undefined;
+
+	const stop = (): void => {
+		if (timer) clearInterval(timer);
+		timer = undefined;
+	};
+
+	pi.on("user_bash", (event, ctx) => {
+		stop();
+		if (event.excludeFromContext || !ctx.isIdle()) return;
+		const since = ctx.sessionManager.getLeafId();
+		timer = setInterval(() => {
+			const message = recorded(ctx, since, event.command);
+			if (!message) return;
+			stop();
+			if (message.cancelled || !ctx.isIdle() || ctx.hasPendingMessages()) return;
+			pi.sendMessage({ customType: FOLLOW_UP_TYPE, content: FOLLOW_UP_PROMPT, display: false }, { triggerTurn: true });
+		}, POLL_MS);
+	});
+	pi.on("agent_start", () => stop());
+	pi.on("session_start", () => stop());
+	pi.on("session_shutdown", () => stop());
+}