@andares/pi-toolkits 0.9.6 → 0.9.7

package/src/features/ask/scratch.ts

@@ -0,0 +1,324 @@
+/**
+ * ask feature — scratch directory for planning notes.
+ *
+ * Ask mode used to confiscate every write tool, including writes to a temp
+ * file. That is stricter than the promise it makes ("do not change the
+ * project"): a model that wants to hold an outline, a checklist or a draft
+ * analysis had to either dump it into the reply or work around the sandbox. So
+ * the mode now hands out exactly one place to write — a per-session directory
+ * under the OS temp dir, outside the project:
+ *
+ *  - the root is `<os.tmpdir()>/pi-ask/<session>`, so nothing here can touch the
+ *    repository and no path arrives from the model (names are relative);
+ *  - names are validated against a narrow allowlist (letters, digits, dot,
+ *    dash, underscore; at most two levels; no `..`, no absolute path, no
+ *    backslash), and the joined path is re-checked for containment as defence
+ *    in depth;
+ *  - existing symlinked components are refused, so a pre-existing link in the
+ *    temp dir cannot turn a note into a write somewhere else;
+ *  - files are capped at {@link SCRATCH_MAX_BYTES}: "notes" are not a dump of
+ *    the repository, and the cap also keeps a tool result from flooding the
+ *    context when the model reads its own note back;
+ *  - `createScratchStore` throws when the temp dir cannot be created or written.
+ *    The caller then degrades to the old fully read-only mode instead of
+ *    running half-open.
+ *
+ * Nothing written here is ever executed: ask mode's bash sandbox stays
+ * read-only, so a script dropped into the scratch directory is just text.
+ */
+import { createHash } from "node:crypto";
+// Creation and sweeping are synchronous on purpose: ask mode can be entered from
+// `session_start` (the autostart path), and the first run starts before an async
+// directory creation would resolve. Those are a handful of syscalls; the actual
+// note operations stay async because they run inside tool calls.
+import {
+	mkdirSync,
+	realpathSync,
+	readdirSync,
+	rmSync,
+	statSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import {
+	appendFile,
+	lstat,
+	mkdir,
+	readFile,
+	readdir,
+	stat,
+	unlink,
+	writeFile,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, resolve, sep } from "node:path";
+
+/** Directory under the OS temp dir that holds every session's scratch space. */
+export const SCRATCH_DIR_NAME = "pi-ask";
+/** Largest single note. Notes are planning aids, not a copy of the repository. */
+export const SCRATCH_MAX_BYTES = 256 * 1024;
+/** Scratch directories older than this are removed when a session enters ask mode. */
+export const SCRATCH_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** A note name segment: no leading dot, no separators, no shell metacharacters. */
+const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** A session id that is safe as a directory name (pi uses UUIDs; be defensive). */
+const SESSION = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** Deepest allowed note name, e.g. `notes/api.md`. */
+const MAX_SEGMENTS = 2;
+
+/** One note as reported by `list`. */
+export interface ScratchFile {
+	readonly name: string;
+	readonly bytes: number;
+}
+
+/** Result of writing or appending one note. */
+export interface ScratchWrite {
+	readonly name: string;
+	readonly path: string;
+	readonly bytes: number;
+	readonly lines: number;
+}
+
+/** The scratch space of one session. Every operation takes a relative note name. */
+export interface ScratchStore {
+	readonly root: string;
+	write(name: string, content: string): Promise<ScratchWrite>;
+	append(name: string, content: string): Promise<ScratchWrite>;
+	read(name: string): Promise<string>;
+	list(): Promise<ScratchFile[]>;
+	remove(name: string): Promise<void>;
+}
+
+/** Why `name` is not a valid note name, or undefined when it is. */
+export function nameError(name: string): string | undefined {
+	const trimmed = name.trim();
+	if (trimmed === "") {
+		return 'The note name is empty. Use a relative name such as "plan.md".';
+	}
+	if (isAbsolute(name) || /^[A-Za-z]:/.test(name) || name.includes("\\")) {
+		return `"${name}" is not a relative name. Scratch names are relative to the scratch directory (for example "plan.md"); absolute paths and backslashes are rejected.`;
+	}
+	const segments = name.split("/");
+	if (segments.length > MAX_SEGMENTS) {
+		return `"${name}" is nested too deeply. At most ${MAX_SEGMENTS} levels are allowed ("notes/api.md").`;
+	}
+	const invalid = segments.find((segment) => !SEGMENT.test(segment));
+	if (invalid !== undefined) {
+		return `"${name}" has an invalid segment "${invalid}". A segment is 1-64 characters of letters, digits, dot, dash or underscore and may not start with a dot.`;
+	}
+	return undefined;
+}
+
+/** Case-folded containment check (Windows paths are case-insensitive). */
+function inside(root: string, target: string): boolean {
+	const fold = (value: string): string =>
+		process.platform === "win32" ? value.toLowerCase() : value;
+	const base = fold(root);
+	const candidate = fold(target);
+	return (
+		candidate === base ||
+		candidate.startsWith(base.endsWith(sep) ? base : `${base}${sep}`)
+	);
+}
+
+/** Absolute path of a validated note name, re-checked for containment. */
+function targetFor(root: string, name: string): string {
+	const problem = nameError(name);
+	if (problem !== undefined) throw new Error(problem);
+	const target = resolve(root, name);
+	if (!inside(root, target)) {
+		throw new Error(`"${name}" resolves outside the scratch directory.`);
+	}
+	return target;
+}
+
+/**
+ * Refuse a target whose existing components go through a symlink.
+ *
+ * The store never creates links itself, so this only matters when something
+ * else (the operator, another process) put one in the temp directory first.
+ * Missing components are fine: they are about to be created inside the root.
+ */
+async function assertNoSymlink(root: string, target: string): Promise<void> {
+	const parts = target.slice(root.length).split(sep).filter(Boolean);
+	let current = root;
+	for (const part of parts) {
+		current = join(current, part);
+		try {
+			const info = await lstat(current);
+			if (info.isSymbolicLink()) {
+				throw new Error(
+					`${part} in the scratch directory is a symbolic link; scratch notes must be regular files.`,
+				);
+			}
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+			throw error;
+		}
+	}
+}
+
+function tooBig(bytes: number): string {
+	const kib = Math.ceil(SCRATCH_MAX_BYTES / 1024);
+	return `Scratch notes are capped at ${kib} KiB; this note would be ${Math.ceil(bytes / 1024)} KiB. Keep it to the planning essentials — the reply, not the note, is the deliverable.`;
+}
+
+function lineCount(text: string): number {
+	if (text === "") return 0;
+	const breaks = text.split("\n").length;
+	return text.endsWith("\n") ? breaks - 1 : breaks;
+}
+
+async function sizeOf(path: string): Promise<number | undefined> {
+	try {
+		const info = await stat(path);
+		return info.size;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Create a {@link ScratchStore} rooted in `options.baseDir` (default: OS temp). */
+export function createScratchStore(options: {
+	readonly sessionId: string;
+	readonly baseDir?: string;
+	readonly now?: number;
+}): ScratchStore {
+	const base = join(resolve(options.baseDir ?? tmpdir()), SCRATCH_DIR_NAME);
+	const leaf = SESSION.test(options.sessionId)
+		? options.sessionId
+		: createHash("sha256").update(options.sessionId).digest("hex").slice(0, 16);
+	const created = join(base, leaf);
+	mkdirSync(created, { recursive: true });
+	// macOS resolves /var (and therefore the default tmpdir) through a symlink.
+	const root = realpathSync(created);
+	// Prove the directory is writable: on a read-only TMPDIR `mkdir -p` on an
+	// existing directory succeeds without proving anything. Ask mode degrades
+	// when this throws.
+	const probe = join(root, `.probe-${process.pid}-${Date.now()}`);
+	writeFileSync(probe, "");
+	unlinkSync(probe);
+	sweepScratchDirs(base, SCRATCH_MAX_AGE_MS, options.now);
+
+	const store: ScratchStore = {
+		root,
+
+		async write(name, content) {
+			const target = targetFor(root, name);
+			const bytes = Buffer.byteLength(content, "utf8");
+			if (bytes > SCRATCH_MAX_BYTES) throw new Error(tooBig(bytes));
+			await assertNoSymlink(root, target);
+			await mkdir(resolve(target, ".."), { recursive: true });
+			await writeFile(target, content, "utf8");
+			return { name, path: target, bytes, lines: lineCount(content) };
+		},
+
+		async append(name, content) {
+			const target = targetFor(root, name);
+			const existing = (await sizeOf(target)) ?? 0;
+			const bytes = Buffer.byteLength(content, "utf8");
+			if (existing + bytes > SCRATCH_MAX_BYTES) {
+				throw new Error(tooBig(existing + bytes));
+			}
+			await assertNoSymlink(root, target);
+			await mkdir(resolve(target, ".."), { recursive: true });
+			await appendFile(target, content, "utf8");
+			const total = existing + bytes;
+			return {
+				name,
+				path: target,
+				bytes: total,
+				// The appended text is what the caller just wrote; the file's own
+				// line count is not needed by the model.
+				lines: lineCount(content),
+			};
+		},
+
+		async read(name) {
+			const target = targetFor(root, name);
+			await assertNoSymlink(root, target);
+			let data: Buffer;
+			try {
+				data = await readFile(target);
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+					throw new Error(
+						`There is no scratch note named "${name}". Use op "list" to see the notes that exist.`,
+					);
+				}
+				throw error;
+			}
+			if (data.length > SCRATCH_MAX_BYTES) {
+				return `${data.subarray(0, SCRATCH_MAX_BYTES).toString("utf8")}\n…(truncated at ${Math.floor(SCRATCH_MAX_BYTES / 1024)} KiB)`;
+			}
+			return data.toString("utf8");
+		},
+
+		async list() {
+			const files: ScratchFile[] = [];
+			const walk = async (dir: string, prefix: string): Promise<void> => {
+				const entries = await readdir(dir, { withFileTypes: true });
+				for (const entry of entries) {
+					if (entry.name.startsWith(".")) continue;
+					const name = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+					if (entry.isDirectory()) {
+						// One level only: names cannot nest deeper than MAX_SEGMENTS.
+						if (prefix === "") await walk(join(dir, entry.name), name);
+						continue;
+					}
+					// Symlinks and other non-files are deliberately not listed.
+					if (!entry.isFile()) continue;
+					const size = await sizeOf(join(dir, entry.name));
+					files.push({ name, bytes: size ?? 0 });
+				}
+			};
+			await walk(root, "");
+			return files.sort((a, b) => a.name.localeCompare(b.name));
+		},
+
+		async remove(name) {
+			const target = targetFor(root, name);
+			try {
+				await unlink(target);
+			} catch (error) {
+				// Deleting a note that is already gone is not an error: the model
+				// asked for the note to be gone and it is.
+				if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+			}
+		},
+	};
+	return store;
+}
+
+/**
+ * Remove scratch directories older than `maxAgeMs`. Never throws: cleanup is
+ * housekeeping, and a stale directory must not keep ask mode from starting.
+ */
+export function sweepScratchDirs(
+	base: string,
+	maxAgeMs: number,
+	now = Date.now(),
+): string[] {
+	const removed: string[] = [];
+	let entries;
+	try {
+		entries = readdirSync(base, { withFileTypes: true });
+	} catch {
+		return removed;
+	}
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		const dir = join(base, entry.name);
+		try {
+			const info = statSync(dir);
+			if (now - info.mtimeMs <= maxAgeMs) continue;
+			rmSync(dir, { recursive: true, force: true });
+			removed.push(entry.name);
+		} catch {
+			// Best effort; a directory in use elsewhere stays.
+		}
+	}
+	return removed;
+}

package/src/features/permission/index.test.ts

@@ -8,13 +8,18 @@
 import { mkdtempSync, realpathSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { describe, expect, it } from "vitest";
+import { beforeEach, describe, expect, it } from "vitest";
 import type {
 	ExtensionAPI,
 	ExtensionContext,
 	ToolCallEvent,
 } from "@earendil-works/pi-coding-agent";
 import type { AskDecision, GateHub, ToolGate } from "../../lib/gates.js";
+import {
+	clearJailedTool,
+	markJailedTool,
+	resetJailedTools,
+} from "../../lib/tools.js";
 import { markStartupCommand } from "../../lib/startup.js";
 import { registerPermission } from "./index.js";
 
@@ -391,8 +396,7 @@ describe("model-facing banner", () => {
 	});
 });
 
-describe("session grants cover repeat asks", () => {
-	it("stops asking for a destructive in-project command once allowed", async () => {
+describe("session grants cover repeat asks", () => {	it("stops asking for a destructive in-project command once allowed", async () => {
 		const h = makeHarness();
 		await h.command("allow allow allow ask");
 		const first = asAsk(await h.evaluate(bashEvent("rm -rf .")));
@@ -411,3 +415,23 @@ describe("session grants cover repeat asks", () => {
 		expect(await h.evaluate(bashEvent(command))).toBeUndefined();
 	});
 });
+
+describe("self-jailed tools", () => {
+	beforeEach(() => {
+		resetJailedTools();
+	});
+
+	it("skips the boundary check only while the owning feature marks the tool", async () => {
+		const h = makeHarness();
+		// Make the judgement observable: with in-project writes set to ask, an
+		// unmarked pathless tool would raise a dialog.
+		await h.command("ask ask ask ask");
+		expect(asAsk(await h.evaluate(customEvent("scratchpad"))).kind).toBe("ask");
+
+		markJailedTool("scratchpad");
+		expect(await h.evaluate(customEvent("scratchpad"))).toBeUndefined();
+
+		clearJailedTool("scratchpad");
+		expect(asAsk(await h.evaluate(customEvent("scratchpad"))).kind).toBe("ask");
+	});
+});

package/src/features/permission/index.ts

@@ -23,6 +23,7 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import type { AskRequest, GateHub } from "../../lib/gates.js";
+import { isJailedTool } from "../../lib/tools.js";
 import { consumeStartupCommand } from "../../lib/startup.js";
 import {
 	DEFAULT_MODES,
@@ -356,6 +357,11 @@ export function registerPermission(pi: ExtensionAPI, gates: GateHub): void {
 		order: 20,
 		evaluate(event, ctx) {
 			if (!enabled) return undefined;
+			// A self-jailed tool (ask's `scratchpad`) can only reach the temp directory
+			// it owns: there is no boundary to judge, and the operator sanctioned that
+			// space by entering the mode that activates the tool. The owning feature
+			// marks it only while active, so an inactive tool is judged normally.
+			if (isJailedTool(event.toolName)) return undefined;
 			const units = unitsFor(event, ctx.cwd);
 			if (units.length === 0) return undefined;
 			const decision = decideProgram(units, {

package/src/lib/tools.ts

@@ -1,5 +1,9 @@
 /**
  * Shared tool-set management helpers (feature-agnostic).
+ *
+ * Two concerns live here because both are about tool identity rather than any
+ * one feature: snapshotting/restoring the active set, and the registry of
+ * self-jailed tools that the boundary gate consults.
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
@@ -23,3 +27,47 @@ export function withoutTools(
 ): string[] {
 	return active.filter((name) => !removed.has(name));
 }
+
+/**
+ * Self-jailed tools — a registry the boundary gate consults.
+ *
+ * A tool can be *jailed*: its own implementation only reaches a place it
+ * created and owns, so there is no boundary for `permission` to judge and no
+ * dialog to raise. Example: ask mode's `scratchpad` writes into the session's
+ * temp directory through a relative, validated name; running it through the
+ * boundary analysis would ask "outside the project, write?" on every note even
+ * though the operator already sanctioned that space by entering ask mode.
+ *
+ * This is intentionally a registry rather than a bypass baked into
+ * `permission`: the owning feature marks the tool only while it is active, and
+ * `permission` does not need to know which feature that is. A tool that is not
+ * marked is judged normally, so forgetting to clear the mark would widen the
+ * boundary — hence the owning feature clears it on exit.
+ *
+ * Narrow on purpose: the registry covers tool *names*, not paths. A tool only
+ * belongs here when its caller cannot point it at a path.
+ */
+const jailed = new Set<string>();
+
+/** Mark a tool as self-jailed (call while it is active). */
+export function markJailedTool(name: string): void {
+	jailed.add(name);
+}
+
+/** Remove the mark (call when the tool is deactivated). */
+export function clearJailedTool(name: string): void {
+	jailed.delete(name);
+}
+
+/** Whether `name` is a self-jailed tool that is currently active. */
+export function isJailedTool(name: string): boolean {
+	return jailed.has(name);
+}
+
+/**
+ * Drop every mark. Tests call this between cases; production code clears one
+ * tool at a time when the owning feature exits.
+ */
+export function resetJailedTools(): void {
+	jailed.clear();
+}