@andares/pi-toolkits 0.8.0 → 0.9.1

package/src/features/permission/index.ts

@@ -0,0 +1,333 @@
+/**
+ * permission feature — `/ask-perm`: session-scoped boundary permission.
+ *
+ * Design notes:
+ *  - Off by default and never persisted. The mode, the modes, and every session
+ *    grant live in this closure; `session_start` resets them and
+ *    `session_shutdown` clears them. A forgotten toggle cannot follow the
+ *    operator into the next session.
+ *  - Toggling: no arguments flips on→off, off→panel. Arguments configure and
+ *    enable in one step (`/ask-perm allow allow allow ask`), which is also the
+ *    autostart path and never opens a dialog.
+ *  - Enforcement is a gate on the shared bus, so it composes with `/ask`
+ *    instead of replacing it: ask answers "does this mutate?", permission
+ *    answers "does this cross the project boundary?", and either can block.
+ *  - The boundary is the working directory plus directories added through
+ *    pi-add-dir (read from its session entry).
+ */
+import { isAbsolute, join } from "node:path";
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	ToolCallEvent,
+} from "@earendil-works/pi-coding-agent";
+import type { AskRequest, GateHub } from "../../lib/gates.js";
+import {
+	DEFAULT_MODES,
+	type PermissionModes,
+	PERMISSION_STATUS_KEY,
+	type Effect,
+} from "./constants.js";
+import {
+	formatModes,
+	parsePermissionArgs,
+	shortMode,
+} from "./modes.js";
+import { openPermissionPanel } from "./panel.js";
+import {
+	canonicalize,
+	expandHome,
+	readAddedDirectories,
+	sessionRoots,
+} from "./paths.js";
+import {
+	decideProgram,
+	decisionEffect,
+	decisionGrantRoot,
+	formatDenial,
+	type PolicyDecision,
+	programKey,
+} from "./policy.js";
+import { askPermission } from "./prompt.js";
+import { SessionRules } from "./session-rules.js";
+import { parseCommandUnits, type CommandUnit } from "./units.js";
+
+/** Tools that read one path. */
+const READ_PATH_TOOLS = new Set(["read", "grep", "find", "ls"]);
+/** Tools that write one path. */
+const WRITE_PATH_TOOLS = new Set(["write", "edit"]);
+
+function inputPath(input: unknown): string | undefined {
+	if (typeof input !== "object" || input === null) return undefined;
+	const value = (input as { path?: unknown }).path;
+	return typeof value === "string" ? value : undefined;
+}
+
+/** One synthetic unit for a non-bash tool call. */
+function toolUnit(
+	command: string,
+	effect: Effect,
+	pathValue: string | undefined,
+	cwd: string,
+): CommandUnit {
+	const base = canonicalize(cwd);
+	return {
+		raw: command,
+		headWord: command,
+		command,
+		args: [],
+		effect,
+		opaque: WRITE_PATH_TOOLS.has(command) && pathValue === undefined,
+		base,
+		targets:
+			pathValue === undefined
+				? []
+				: [
+						{
+							path: isAbsolute(expandHome(pathValue))
+								? expandHome(pathValue)
+								: join(base, pathValue),
+							effect,
+							source: "operand",
+						},
+					],
+		note: pathValue === undefined ? "the tool call names no path" : undefined,
+	};
+}
+
+export function registerPermission(pi: ExtensionAPI, gates: GateHub): void {
+	let enabled = false;
+	let modes: PermissionModes = { ...DEFAULT_MODES };
+	const rules = new SessionRules();
+	let rootsCache:
+		| { cwd: string; branchLength: number; roots: string[] }
+		| undefined;
+
+	function reset(): void {
+		enabled = false;
+		modes = { ...DEFAULT_MODES };
+		rules.clear();
+		rootsCache = undefined;
+	}
+
+	function syncStatus(ctx: ExtensionContext): void {
+		if (!enabled) {
+			ctx.ui.setStatus(PERMISSION_STATUS_KEY, undefined);
+			return;
+		}
+		const color = (mode: string, label: string): string => {
+			if (mode === "allow") return ctx.ui.theme.fg("success", label);
+			if (mode === "ask") return ctx.ui.theme.fg("warning", label);
+			return ctx.ui.theme.fg("error", label);
+		};
+		const part = (inProject: string, outside: string): string =>
+			`${color(inProject, shortMode(inProject as "allow"))}/${color(outside, shortMode(outside as "allow"))}`;
+		ctx.ui.setStatus(
+			PERMISSION_STATUS_KEY,
+			`${ctx.ui.theme.fg("muted", "perm")} i:${part(modes.inRead, modes.inWrite)} o:${part(modes.outRead, modes.outWrite)}`,
+		);
+	}
+
+	/** Session roots, refreshed only when the branch grew. */
+	function rootsFor(ctx: ExtensionContext): string[] {
+		try {
+			const branch = ctx.sessionManager.getBranch();
+			if (
+				!rootsCache ||
+				rootsCache.cwd !== ctx.cwd ||
+				rootsCache.branchLength !== branch.length
+			) {
+				rootsCache = {
+					cwd: ctx.cwd,
+					branchLength: branch.length,
+					roots: sessionRoots(ctx.cwd, readAddedDirectories(branch)),
+				};
+			}
+			return rootsCache.roots;
+		} catch {
+			// No session manager (unexpected context): fail closed on the cwd only.
+			return [canonicalize(ctx.cwd)];
+		}
+	}
+
+	function unitsFor(event: ToolCallEvent, cwd: string): CommandUnit[] {
+		if (event.toolName === "bash") {
+			const command = (event.input as { command?: unknown }).command;
+			return parseCommandUnits(typeof command === "string" ? command : "", cwd);
+		}
+		if (event.toolName === "powershell") {
+			// PowerShell is not decomposed: a script's writes and exec targets stay
+			// invisible, so the call is asked about instead of judged by its cwd.
+			return [
+				{
+					raw: "powershell",
+					headWord: "powershell",
+					command: "powershell",
+					args: [],
+					effect: "write",
+					opaque: true,
+					base: canonicalize(cwd),
+					targets: [],
+					note: "PowerShell commands are not analysed",
+				},
+			];
+		}
+		if (READ_PATH_TOOLS.has(event.toolName)) {
+			return [toolUnit(event.toolName, "read", inputPath(event.input), cwd)];
+		}
+		if (WRITE_PATH_TOOLS.has(event.toolName)) {
+			return [toolUnit(event.toolName, "write", inputPath(event.input), cwd)];
+		}
+		// Every other tool (MCP, subagent, …) has no path to judge: it is
+		// treated as an exec and answered by the working directory's scope.
+		return [toolUnit(event.toolName, "write", undefined, cwd)];
+	}
+
+	function askRequest(
+		decision: PolicyDecision,
+		fallbackCwd: string,
+		units: readonly CommandUnit[],
+	): AskRequest {
+		const root = decisionGrantRoot(decision, () => fallbackCwd);
+		const effect = decisionEffect(decision);
+		const scope =
+			decision.target?.scope === "out" ? "outside project" : "inside project";
+		const details = [
+			`Command: ${decision.unit.raw || decision.unit.command}`,
+			...(decision.target
+				? [`Target: ${decision.target.path} (${scope}, ${effect})`]
+				: []),
+			...(decision.reason ? [`Reason: ${decision.reason}`] : []),
+			decision.unit.opaque
+				? "Session grant would cover: this exact command"
+				: `Session grant would cover: ${root}`,
+		];
+		return {
+			title: "Permission required",
+			details,
+			root,
+			present: (ctx) =>
+				askPermission(ctx, { title: "Permission required", details }),
+			apply: (choice) => {
+				if (choice === "allow-session") {
+					if (decision.unit.opaque) rules.allowCommand(programKey(units));
+					else rules.allow({ effect, root });
+				}
+				if (choice === "deny-session") {
+					if (decision.unit.opaque) rules.denyCommand(programKey(units));
+					else rules.deny({ effect, root });
+				}
+			},
+			denyReason: (choice) =>
+				formatDenial({
+					...decision,
+					reason:
+						choice === "deny-session"
+							? `${decision.reason ?? "operation"} — denied for this session`
+							: (decision.reason ?? "denied by the operator"),
+				}),
+		};
+	}
+
+	// ── Lifecycle ──────────────────────────────────────────────────────────
+
+	pi.on("session_start", (_event, ctx) => {
+		reset();
+		syncStatus(ctx);
+	});
+	pi.on("session_shutdown", () => {
+		reset();
+	});
+
+	// ── Command ────────────────────────────────────────────────────────────
+
+	pi.registerCommand("ask-perm", {
+		description:
+			"Toggle permission checks; with arguments: /ask-perm [in-read] [in-write] [out-read] [out-write]",
+		handler: async (args, ctx) => {
+			const raw = args.trim();
+
+			if (raw !== "") {
+				const parsed = parsePermissionArgs(raw);
+				if ("error" in parsed) {
+					ctx.ui.notify(`ask-perm: ${parsed.error}`, "error");
+					return;
+				}
+				modes = parsed.modes;
+				// A new policy invalidates grants made under the old one.
+				rules.clear();
+				enabled = true;
+				syncStatus(ctx);
+				ctx.ui.notify(
+					`Permission ON — ${formatModes(modes)}. /ask-perm to turn off.`,
+					"info",
+				);
+				return;
+			}
+
+			if (enabled) {
+				enabled = false;
+				rules.clear();
+				syncStatus(ctx);
+				ctx.ui.notify(
+					"Permission OFF — no boundary checks in this session.",
+					"info",
+				);
+				return;
+			}
+
+			const chosen = await openPermissionPanel(ctx, modes);
+			if (!chosen) {
+				ctx.ui.notify(
+					"ask-perm: cancelled. Use /ask-perm allow allow allow ask to enable from the argument form.",
+					"info",
+				);
+				return;
+			}
+			modes = chosen;
+			enabled = true;
+			syncStatus(ctx);
+			ctx.ui.notify(
+				`Permission ON — ${formatModes(modes)}. /ask-perm to turn off.`,
+				"info",
+			);
+		},
+	});
+
+	// ── Gate ───────────────────────────────────────────────────────────────
+
+	gates.register({
+		name: "permission",
+		order: 20,
+		evaluate(event, ctx) {
+			if (!enabled) return undefined;
+			const units = unitsFor(event, ctx.cwd);
+			if (units.length === 0) return undefined;
+			const decision = decideProgram(units, {
+				modes,
+				roots: rootsFor(ctx),
+				rules,
+			});
+			if (decision.action === "allow") return undefined;
+			if (decision.action === "deny") {
+				return { kind: "block", reason: formatDenial(decision) };
+			}
+			return { kind: "ask", request: askRequest(decision, ctx.cwd, units) };
+		},
+	});
+
+	// ── Model-facing banner ────────────────────────────────────────────────
+
+	pi.on("before_agent_start", (event) => {
+		if (!enabled) return;
+		const banner = [
+			"",
+			"## Permission mode",
+			`Boundary checks are ON: ${formatModes(modes)}.`,
+			"Operations outside the project, destructive commands, and credential paths may require operator confirmation.",
+			"A denial is a policy decision — do not retry the same operation through an equivalent command.",
+			"",
+		].join("\n");
+		return { systemPrompt: `${event.systemPrompt}${banner}` };
+	});
+}

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

@@ -0,0 +1,66 @@
+/**
+ * Mode defaults, argument parsing, and formatting.
+ */
+import { describe, expect, it } from "vitest";
+import { DEFAULT_MODES, IN_VALUES, OUT_VALUES } from "./constants.js";
+import { formatModes, parsePermissionArgs, shortMode } from "./modes.js";
+
+describe("modes", () => {
+	it("ships the documented defaults", () => {
+		expect(DEFAULT_MODES).toEqual({
+			inRead: "allow",
+			inWrite: "allow",
+			outRead: "allow",
+			outWrite: "ask",
+		});
+		expect(IN_VALUES).toEqual(["allow", "ask"]);
+		expect(OUT_VALUES).toEqual(["allow", "ask", "deny"]);
+	});
+
+	it("merges missing arguments from the defaults", () => {
+		expect(parsePermissionArgs("ask")).toEqual({
+			modes: { inRead: "ask", inWrite: "allow", outRead: "allow", outWrite: "ask" },
+		});
+		expect(parsePermissionArgs("ask ask")).toEqual({
+			modes: { inRead: "ask", inWrite: "ask", outRead: "allow", outWrite: "ask" },
+		});
+		expect(parsePermissionArgs("ask allow deny deny")).toEqual({
+			modes: { inRead: "ask", inWrite: "allow", outRead: "deny", outWrite: "deny" },
+		});
+	});
+
+	it("uses the current defaults, not the previous mode, for omitted arguments", () => {
+		const parsed = parsePermissionArgs("allow");
+		expect("modes" in parsed ? parsed.modes : undefined).toEqual(DEFAULT_MODES);
+	});
+
+	it("rejects deny for in-project modes", () => {
+		expect(parsePermissionArgs("deny")).toEqual({
+			error: expect.stringContaining("in-read"),
+		});
+	});
+
+	it("rejects unknown values and too many arguments", () => {
+		expect(parsePermissionArgs("maybe")).toEqual({
+			error: expect.stringContaining("in-read"),
+		});
+		expect(parsePermissionArgs("allow allow allow nope")).toEqual({
+			error: expect.stringContaining("out-write"),
+		});
+		expect(parsePermissionArgs("allow allow allow ask extra")).toEqual({
+			error: expect.stringContaining("at most 4"),
+		});
+		expect(parsePermissionArgs("")).toEqual({
+			error: expect.stringContaining("at least one"),
+		});
+	});
+
+	it("formats the four modes and their short letters", () => {
+		expect(formatModes(DEFAULT_MODES)).toBe("in allow/allow, out allow/ask");
+		expect([shortMode("allow"), shortMode("ask"), shortMode("deny")]).toEqual([
+			"A",
+			"a",
+			"D",
+		]);
+	});
+});

package/src/features/permission/modes.ts

@@ -0,0 +1,82 @@
+/**
+ * permission feature — argument parsing and display formatting.
+ *
+ * `/ask-perm` with no argument toggles: on → off, off → panel. With arguments
+ * it configures and enables in one step (this is the autostart path, and it
+ * never opens a dialog):
+ *
+ *   /ask-perm [in-read] [in-write] [out-read] [out-write]
+ *
+ * Missing arguments take their default value — not the current one — so
+ * `/ask-perm allow` always means "defaults, which also happens to be all
+ * allow on the inside".
+ */
+import {
+	DEFAULT_MODES,
+	IN_VALUES,
+	OUT_VALUES,
+	type PermissionModes,
+	type TriMode,
+} from "./constants.js";
+
+export type ParsedArgs =
+	| { readonly modes: PermissionModes }
+	| { readonly error: string };
+
+function isPair(value: string): boolean {
+	return (IN_VALUES as readonly string[]).includes(value);
+}
+
+function isTri(value: string): boolean {
+	return (OUT_VALUES as readonly string[]).includes(value);
+}
+
+/**
+ * Parse the command arguments. An empty string yields an error — callers must
+ * check for "no arguments" before calling this.
+ */
+export function parsePermissionArgs(raw: string): ParsedArgs {
+	const words = raw.trim().split(/\s+/).filter(Boolean);
+	if (words.length === 0) return { error: "expected at least one mode" };
+	if (words.length > 4) {
+		return { error: "expected at most 4 modes (in-read in-write out-read out-write)" };
+	}
+	const [inRead, inWrite, outRead, outWrite] = words;
+	if (inRead !== undefined && !isPair(inRead)) {
+		return { error: `in-read must be one of ${IN_VALUES.join("|")} (got "${inRead}")` };
+	}
+	if (inWrite !== undefined && !isPair(inWrite)) {
+		return { error: `in-write must be one of ${IN_VALUES.join("|")} (got "${inWrite}")` };
+	}
+	if (outRead !== undefined && !isTri(outRead)) {
+		return { error: `out-read must be one of ${OUT_VALUES.join("|")} (got "${outRead}")` };
+	}
+	if (outWrite !== undefined && !isTri(outWrite)) {
+		return { error: `out-write must be one of ${OUT_VALUES.join("|")} (got "${outWrite}")` };
+	}
+	return {
+		modes: {
+			inRead: (inRead ?? DEFAULT_MODES.inRead) as PermissionModes["inRead"],
+			inWrite: (inWrite ?? DEFAULT_MODES.inWrite) as PermissionModes["inWrite"],
+			outRead: (outRead ?? DEFAULT_MODES.outRead) as TriMode,
+			outWrite: (outWrite ?? DEFAULT_MODES.outWrite) as TriMode,
+		},
+	};
+}
+
+/** `allow/allow · allow/ask`, the human-readable summary used in notices. */
+export function formatModes(modes: PermissionModes): string {
+	return `in ${modes.inRead}/${modes.inWrite}, out ${modes.outRead}/${modes.outWrite}`;
+}
+
+/** Single-letter form for the footer status (`A` allow, `a` ask, `D` deny). */
+export function shortMode(mode: TriMode | "allow"): string {
+	switch (mode) {
+		case "allow":
+			return "A";
+		case "ask":
+			return "a";
+		case "deny":
+			return "D";
+	}
+}

package/src/features/permission/panel.ts

@@ -0,0 +1,118 @@
+/**
+ * permission feature — the mode panel.
+ *
+ * A `SettingsList` (the same component the built-in settings dialogs use)
+ * supplies rendering, ↑↓ navigation, space-cycle and Esc-cancel. A thin
+ * wrapper adds the one behaviour this dialog needs on top: **Enter anywhere
+ * applies the current values**, so typing `/ask-perm` then Enter enables the
+ * defaults without navigating.
+ *
+ * TUI only: `SettingsList` is a custom component, and rpc/print modes cannot
+ * host one. Callers fall back to the argument form there.
+ */
+import { getSettingsListTheme } from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	type Component,
+	matchesKey,
+	type SettingItem,
+	SettingsList,
+} from "@earendil-works/pi-tui";
+import {
+	IN_VALUES,
+	OUT_VALUES,
+	type PermissionModes,
+} from "./constants.js";
+
+/** Intercepts Enter globally; everything else belongs to the list. */
+class ApplyOnEnter implements Component {
+	constructor(
+		private readonly list: SettingsList,
+		private readonly snapshot: () => PermissionModes,
+		private readonly done: (value: PermissionModes | undefined) => void,
+	) {}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, "enter")) {
+			this.done(this.snapshot());
+			return;
+		}
+		this.list.handleInput(data);
+	}
+
+	render(width: number): string[] {
+		return this.list.render(width);
+	}
+
+	invalidate(): void {
+		this.list.invalidate();
+	}
+}
+
+/** Build the settings rows for one mode set. */
+function buildItems(modes: PermissionModes): SettingItem[] {
+	return [
+		{
+			id: "apply",
+			label: "Enable with these modes",
+			description: "Press Enter to enable permission checks",
+			currentValue: "enter",
+		},
+		{
+			id: "inRead",
+			label: "In-project read",
+			description: "Reads inside the working directory and added directories",
+			currentValue: modes.inRead,
+			values: [...IN_VALUES],
+		},
+		{
+			id: "inWrite",
+			label: "In-project write / exec",
+			description: "Writes and command execution inside the project",
+			currentValue: modes.inWrite,
+			values: [...IN_VALUES],
+		},
+		{
+			id: "outRead",
+			label: "Outside read",
+			description: "Reads outside the project boundary",
+			currentValue: modes.outRead,
+			values: [...OUT_VALUES],
+		},
+		{
+			id: "outWrite",
+			label: "Outside write / exec",
+			description: "Writes and execution outside the project boundary",
+			currentValue: modes.outWrite,
+			values: [...OUT_VALUES],
+		},
+	];
+}
+
+/**
+ * Open the mode panel. Resolves with the chosen modes, or `undefined` when the
+ * operator cancels (Esc) or the host cannot render a custom component.
+ */
+export function openPermissionPanel(
+	ctx: ExtensionContext,
+	modes: PermissionModes,
+): Promise<PermissionModes | undefined> {
+	if (!ctx.hasUI || ctx.mode !== "tui") return Promise.resolve(undefined);
+
+	return ctx.ui.custom<PermissionModes | undefined>(
+		(_tui, _theme, _keybindings, done) => {
+			let current: PermissionModes = { ...modes };
+			const items = buildItems(current);
+			const list = new SettingsList(
+				items,
+				8,
+				getSettingsListTheme(),
+				(id, value) => {
+					current = { ...current, [id]: value } as PermissionModes;
+				},
+				() => done(undefined),
+			);
+			return new ApplyOnEnter(list, () => current, done);
+		},
+	);
+}