@andares/pi-toolkits 0.8.0 → 0.9.1

package/src/features/permission/policy.ts

@@ -0,0 +1,338 @@
+/**
+ * permission feature — per-call decisions.
+ *
+ * The policy is evaluated per command unit: every touched path is canonicalized,
+ * classified as inside or outside the session roots, and answered by, in order:
+ *
+ *  1. the fixed secrets table (deny in every mode),
+ *  2. the fixed danger table (ask in every mode),
+ *  3. session grants (deny wins over allow),
+ *  4. the four modes.
+ *
+ * The strictest unit of a compound command wins (`deny > ask > allow`), so
+ * `cd safe && rm -rf /` cannot ride on the first segment's verdict.
+ */
+import type { PermissionModes } from "./constants.js";
+import { dangerReason, secretReason, type Effect } from "./constants.js";
+import { canonicalize, grantRoot, insideAnyRoot } from "./paths.js";
+import type { SessionRules } from "./session-rules.js";
+import type { CommandUnit } from "./units.js";
+
+export type PolicyAction = "allow" | "ask" | "deny";
+
+/** One resolved access a decision was made about. */
+export interface PolicyTarget {
+	/** Canonical absolute path. */
+	readonly path: string;
+	readonly effect: Effect;
+	readonly scope: "in" | "out";
+}
+
+export interface PolicyDecision {
+	readonly action: PolicyAction;
+	readonly unit: CommandUnit;
+	readonly target?: PolicyTarget;
+	/** Human/model-facing explanation for ask and deny. */
+	readonly reason?: string;
+}
+
+export interface PolicyContext {
+	readonly modes: PermissionModes;
+	/** Canonical session roots (working directory plus added directories). */
+	readonly roots: readonly string[];
+	readonly rules: SessionRules;
+}
+
+const SEVERITY: Record<PolicyAction, number> = { allow: 0, ask: 1, deny: 2 };
+
+/** What the session grants alone say about one access. */
+function decideSession(
+	effect: Effect,
+	pathValue: string,
+	ctx: PolicyContext,
+): "allow" | "deny" | undefined {
+	if (ctx.rules.denies(effect, pathValue)) return "deny";
+	if (ctx.rules.allows(effect, pathValue)) return "allow";
+	return undefined;
+}
+
+function worse(a: PolicyDecision, b: PolicyDecision): PolicyDecision {
+	return SEVERITY[b.action] > SEVERITY[a.action] ? b : a;
+}
+
+function modeFor(
+	modes: PermissionModes,
+	effect: Effect,
+	scope: "in" | "out",
+): "ask" | "allow" | "deny" {
+	if (effect === "read") return scope === "in" ? modes.inRead : modes.outRead;
+	return scope === "in" ? modes.inWrite : modes.outWrite;
+}
+
+/** Scope and session-grant answer for one already-canonical path. */
+function decidePath(
+	unit: CommandUnit,
+	pathValue: string,
+	effect: Effect,
+	ctx: PolicyContext,
+): PolicyDecision {
+	const scope = insideAnyRoot(ctx.roots, pathValue) ? "in" : "out";
+	const secret = secretReason(pathValue);
+	if (secret !== undefined) {
+		return {
+			action: "deny",
+			unit,
+			target: { path: pathValue, effect, scope },
+			reason: `${secret} — denied by the fixed safety table`,
+		};
+	}
+	const target: PolicyTarget = { path: pathValue, effect, scope };
+	if (ctx.rules.denies(effect, pathValue)) {
+		return {
+			action: "deny",
+			unit,
+			target,
+			reason: `${effect} under ${pathValue} was denied for this session`,
+		};
+	}
+	if (ctx.rules.allows(effect, pathValue)) {
+		return { action: "allow", unit, target };
+	}
+	const mode = modeFor(ctx.modes, effect, scope);
+	if (mode === "allow") return { action: "allow", unit, target };
+	if (mode === "deny") {
+		return {
+			action: "deny",
+			unit,
+			target,
+			reason: `${scope === "out" ? "outside-project" : "in-project"} ${effect} is set to deny`,
+		};
+	}
+	return {
+		action: "ask",
+		unit,
+		target,
+		reason:
+			scope === "out"
+				? `outside-project ${effect} requires confirmation`
+				: `in-project ${effect} requires confirmation`,
+	};
+}
+
+/** Decide one command unit. */
+export function decideUnit(
+	unit: CommandUnit,
+	ctx: PolicyContext,
+): PolicyDecision {
+	if (unit.opaque) {
+		// Session grants for an opaque program are keyed on the whole command
+		// text and checked in {@link decideProgram}; a single unit has no path
+		// to grant.
+		return {
+			action: "ask",
+			unit,
+			reason: unit.note ?? "this command could not be analysed",
+		};
+	}
+
+	const resolvedTargets = unit.targets.map((target) => ({
+		...target,
+		path: canonicalize(target.path),
+	}));
+	const canonicalBase = unit.base === null ? null : canonicalize(unit.base);
+
+	// The secrets table is absolute: it outranks both the danger table and the
+	// modes, so `sudo cat ~/.ssh/id_rsa` denies instead of asking.
+	const secret = resolvedTargets
+		.map((target) => ({ target, reason: secretReason(target.path) }))
+		.find((entry) => entry.reason !== undefined);
+	if (secret?.reason !== undefined) {
+		return {
+			action: "deny",
+			unit,
+			target: {
+				path: secret.target.path,
+				effect: secret.target.effect,
+				scope: insideAnyRoot(ctx.roots, secret.target.path) ? "in" : "out",
+			},
+			reason: `${secret.reason} — denied by the fixed safety table`,
+		};
+	}
+	if (resolvedTargets.length === 0 && canonicalBase !== null) {
+		const baseSecret = secretReason(canonicalBase);
+		if (baseSecret !== undefined) {
+			return {
+				action: "deny",
+				unit,
+				target: {
+					path: canonicalBase,
+					effect: unit.effect,
+					scope: insideAnyRoot(ctx.roots, canonicalBase) ? "in" : "out",
+				},
+				reason: `${baseSecret} — denied by the fixed safety table`,
+			};
+		}
+	}
+
+	// Session grants are the operator's explicit decision and outrank the danger
+	// table: once an operation is allowed for the session, repeating it must not
+	// ask again. A deny likewise turns a dangerous command into a denial instead
+	// of a prompt.
+	let sessionVerdict: "allow" | "deny" | undefined;
+	if (resolvedTargets.length === 0) {
+		sessionVerdict =
+			canonicalBase === null
+				? undefined
+				: decideSession(unit.effect, canonicalBase, ctx);
+	} else {
+		const verdicts = resolvedTargets.map((target) =>
+			decideSession(target.effect, target.path, ctx),
+		);
+		if (verdicts.includes("deny")) {
+			const denied = resolvedTargets[verdicts.indexOf("deny")];
+			return decidePath(unit, denied.path, denied.effect, ctx);
+		}
+		sessionVerdict = verdicts.every((verdict) => verdict === "allow")
+			? "allow"
+			: undefined;
+	}
+	if (sessionVerdict === "deny" && canonicalBase !== null) {
+		return decidePath(unit, canonicalBase, unit.effect, ctx);
+	}
+
+	// The fixed danger table asks regardless of mode: `rm -rf .` inside the
+	// project is still destructive, and scope alone cannot express that.
+	const danger = dangerReason(
+		unit.command,
+		unit.args,
+		resolvedTargets.map((target) => target.path),
+		canonicalBase,
+	);
+	const privileged = unit.headWord === "sudo" || unit.headWord === "doas";
+	if (sessionVerdict !== "allow" && (danger !== undefined || privileged)) {
+		const first = resolvedTargets[0];
+		let target: PolicyTarget | undefined;
+		if (first !== undefined) {
+			target = {
+				path: first.path,
+				effect: first.effect,
+				scope: insideAnyRoot(ctx.roots, first.path) ? "in" : "out",
+			};
+		}
+		return {
+			action: "ask",
+			unit,
+			target,
+			reason: danger ?? "privileged command",
+		};
+	}
+
+	if (resolvedTargets.length === 0) {
+		if (canonicalBase === null) {
+			return {
+				action: "ask",
+				unit,
+				reason: "the working directory could not be resolved",
+			};
+		}
+		return decidePath(unit, canonicalBase, unit.effect, ctx);
+	}
+
+	let decision = decidePath(
+		unit,
+		resolvedTargets[0].path,
+		resolvedTargets[0].effect,
+		ctx,
+	);
+	for (const target of resolvedTargets.slice(1)) {
+		decision = worse(decision, decidePath(unit, target.path, target.effect, ctx));
+	}
+	return decision;
+}
+
+/** Decide a whole bash program (or the single unit of a path-bearing tool). */
+/** Stable key for a session grant on an opaque program. */
+export function programKey(units: readonly CommandUnit[]): string {
+	return units.map((unit) => unit.raw).join(" ; ");
+}
+
+export function decideProgram(
+	units: readonly CommandUnit[],
+	ctx: PolicyContext,
+): PolicyDecision {
+	if (units.length === 0) {
+		return {
+			action: "allow",
+			unit: {
+				raw: "",
+				headWord: "",
+				command: "",
+				args: [],
+				effect: "read",
+				opaque: false,
+				base: null,
+				targets: [],
+			},
+		};
+	}
+	// A program the parser could not fully resolve has no path-level grant;
+	// the operator's "allow this session" covers the exact command text, so a
+	// repeat of the same opaque program does not ask again.
+	const opaqueUnit = units.find((unit) => unit.opaque);
+	if (opaqueUnit) {
+		const key = programKey(units);
+		if (ctx.rules.deniesCommand(key)) {
+			return {
+				action: "deny",
+				unit: opaqueUnit,
+				reason: "this command was denied for this session",
+			};
+		}
+		if (ctx.rules.allowsCommand(key)) {
+			return { action: "allow", unit: opaqueUnit };
+		}
+	}
+
+	let decision = decideUnit(units[0], ctx);
+	for (const unit of units.slice(1)) {
+		decision = worse(decision, decideUnit(unit, ctx));
+	}
+	return decision;
+}
+
+/** Root a session grant for this decision should cover. */
+export function decisionGrantRoot(
+	decision: PolicyDecision,
+	getCwd: () => string,
+): string {
+	if (decision.target) return grantRoot(decision.target.path);
+	if (decision.unit.base !== null) return grantRoot(canonicalize(decision.unit.base));
+	return grantRoot(canonicalize(getCwd()));
+}
+
+/** Effect a session grant for this decision should cover. */
+export function decisionEffect(decision: PolicyDecision): Effect {
+	return decision.target?.effect ?? decision.unit.effect;
+}
+
+/**
+ * Model-facing denial. The model receives this as the tool result, so it names
+ * the offending segment, the resolved target, and the policy that denied it —
+ * and tells the model not to retry an equivalent command.
+ */
+export function formatDenial(decision: PolicyDecision): string {
+	const lines = [`Permission denied: ${decision.unit.raw || "(empty command)"}`];
+	if (decision.target) {
+		const scope = decision.target.scope === "out" ? "outside project" : "inside project";
+		lines.push(
+			`Target: ${decision.target.path} (${scope}, ${decision.target.effect})`,
+		);
+	}
+	if (decision.reason) lines.push(`Reason: ${decision.reason}`);
+	lines.push(
+		decision.reason?.includes("fixed safety table") === true
+			? "This is a fixed safety rule; /ask-perm cannot override it. Do not retry an equivalent command."
+			: "The operator controls this with /ask-perm. Do not retry the same operation through an equivalent command.",
+	);
+	return lines.join("\n");
+}

package/src/features/permission/prompt.ts

@@ -0,0 +1,146 @@
+/**
+ * permission feature — the confirmation dialog.
+ *
+ * Four answers, hotkey-first because this dialog appears mid-run and should be
+ * answerable with one keystroke:
+ *
+ *   a — allow once
+ *   s — allow this directory for the session
+ *   d — deny once
+ *   f — deny this directory for the session
+ *
+ * `SelectList` provides rendering, ↑↓ and Enter; the wrapper maps the four
+ * letters. Non-TUI dialog modes get the host's plain selector; with no UI at
+ * all the caller's `present` resolves `undefined` (fail closed).
+ */
+import { getSelectListTheme } from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	type Component,
+	type KeyId,
+	matchesKey,
+	SelectList,
+	Text,
+} from "@earendil-works/pi-tui";
+import type { AskDecision } from "../../lib/gates.js";
+
+export interface PermissionPromptInput {
+	readonly title: string;
+	readonly details: readonly string[];
+}
+
+interface Option {
+	readonly value: AskDecision;
+	readonly key: KeyId;
+	readonly label: string;
+	readonly description: string;
+}
+
+function optionsFor(): Option[] {
+	return [
+		{
+			value: "allow",
+			key: "a",
+			label: "Allow once (a)",
+			description: "Run this call only",
+		},
+		{
+			value: "allow-session",
+			key: "s",
+			label: "Allow for this session (s)",
+			description: "Stop asking for this operation until the session ends",
+		},
+		{
+			value: "deny",
+			key: "d",
+			label: "Deny (d)",
+			description: "Block this call",
+		},
+		{
+			value: "deny-session",
+			key: "f",
+			label: "Deny for this session (f)",
+			description: "Block this operation until the session ends",
+		},
+	];
+}
+
+/** Header plus a hotkey-aware `SelectList`. */
+class PromptComponent implements Component {
+	constructor(
+		private readonly header: Text,
+		private readonly list: SelectList,
+		private readonly options: readonly Option[],
+		private readonly choose: (value: AskDecision) => void,
+	) {}
+
+	handleInput(data: string): void {
+		const hit = this.options.find((option) => matchesKey(data, option.key));
+		if (hit) {
+			this.choose(hit.value);
+			return;
+		}
+		this.list.handleInput(data);
+	}
+
+	render(width: number): string[] {
+		return [...this.header.render(width), ...this.list.render(width)];
+	}
+
+	invalidate(): void {
+		this.header.invalidate();
+		this.list.invalidate();
+	}
+}
+
+/**
+ * Ask the operator. Resolves `undefined` when there is no way to ask or the
+ * dialog was cancelled.
+ */
+export async function askPermission(
+	ctx: ExtensionContext,
+	input: PermissionPromptInput,
+): Promise<AskDecision | undefined> {
+	if (!ctx.hasUI) return undefined;
+	const options = optionsFor();
+
+	if (ctx.mode !== "tui") {
+		const labels = options.map((option) => option.label);
+		const choice = await ctx.ui.select(input.title, labels);
+		if (choice === undefined) return undefined;
+		return options[labels.indexOf(choice)]?.value;
+	}
+
+	return ctx.ui.custom<AskDecision | undefined>(
+		(_tui, theme, _keybindings, done) => {
+			let settled = false;
+			const finish = (value: AskDecision | undefined): void => {
+				if (settled) return;
+				settled = true;
+				done(value);
+			};
+			const header = new Text(
+				[
+					theme.fg("accent", input.title),
+					...input.details.map((line) => theme.fg("muted", line)),
+					theme.fg(
+						"dim",
+						"a allow · s allow session · d deny · f deny session · esc cancel",
+					),
+				].join("\n"),
+			);
+			const list = new SelectList(
+				options.map((option) => ({
+					value: option.value,
+					label: option.label,
+					description: option.description,
+				})),
+				6,
+				getSelectListTheme(),
+			);
+			list.onSelect = (item) => finish(item.value as AskDecision);
+			list.onCancel = () => finish(undefined);
+			return new PromptComponent(header, list, options, finish);
+		},
+	);
+}

package/src/features/permission/session-rules.ts

@@ -0,0 +1,99 @@
+/**
+ * permission feature — session-scoped grants.
+ *
+ * Ephemeral by design: an allow/deny recorded here lives only in this process
+ * and is cleared when the mode is switched off or the session ends. Nothing is
+ * written to disk, so a forgotten toggle cannot outlive the session it was
+ * meant for.
+ *
+ * A grant is `(effect, directory root)`. Read grants do not imply write grants.
+ * Matching is containment — no globs — because the operator grants "this
+ * directory", not "this pattern".
+ */
+import type { Effect } from "./constants.js";
+import { insideAnyRoot } from "./paths.js";
+
+/** One session-scoped allow or deny. */
+export interface Grant {
+	readonly effect: Effect;
+	/** Canonical directory root; the file that triggered it was folded in. */
+	readonly root: string;
+}
+
+export class SessionRules {
+	private readonly allowList: Grant[] = [];
+	private readonly denyList: Grant[] = [];
+	/**
+	 * Grants for commands that cannot be resolved to a path (an opaque unit).
+	 * Keyed on the command text, so only the exact command is covered.
+	 */
+	private readonly allowedCommands = new Set<string>();
+	private readonly deniedCommands = new Set<string>();
+
+	/** Record an allow for `(effect, root)`; replaces an identical grant. */
+	allow(grant: Grant): void {
+		this.add(this.allowList, grant);
+	}
+
+	/** Record a deny for `(effect, root)`; replaces an identical grant. */
+	deny(grant: Grant): void {
+		this.add(this.denyList, grant);
+	}
+
+	private add(list: Grant[], grant: Grant): void {
+		const index = list.findIndex(
+			(entry) => entry.effect === grant.effect && entry.root === grant.root,
+		);
+		if (index >= 0) list[index] = grant;
+		else list.push(grant);
+	}
+
+	/** `true` when an allow covers this access. */
+	allows(effect: Effect, pathValue: string): boolean {
+		return this.allowList.some(
+			(grant) =>
+				grant.effect === effect && insideAnyRoot([grant.root], pathValue),
+		);
+	}
+
+	/** `true` when a deny covers this access. */
+	denies(effect: Effect, pathValue: string): boolean {
+		return this.denyList.some(
+			(grant) =>
+				grant.effect === effect && insideAnyRoot([grant.root], pathValue),
+		);
+	}
+
+	/** Record an allow for an opaque command's exact text. */
+	allowCommand(command: string): void {
+		this.allowedCommands.add(command);
+	}
+
+	/** Record a deny for an opaque command's exact text. */
+	denyCommand(command: string): void {
+		this.deniedCommands.add(command);
+	}
+
+	/** `true` when this exact command was allowed for the session. */
+	allowsCommand(command: string): boolean {
+		return this.allowedCommands.has(command);
+	}
+
+	/** `true` when this exact command was denied for the session. */
+	deniesCommand(command: string): boolean {
+		return this.deniedCommands.has(command);
+	}
+
+	/** Drop every grant (mode off, session boundary). */
+	clear(): void {
+		this.allowList.length = 0;
+		this.denyList.length = 0;
+		this.allowedCommands.clear();
+		this.deniedCommands.clear();
+	}
+
+	/** Counts for `/ask-perm status` and tests. */
+	counts(): { allow: number; deny: number } {
+		return { allow: this.allowList.length, deny: this.denyList.length };
+	}
+}