@andares/pi-toolkits 0.8.0 → 0.9.1

package/src/index.ts

@@ -11,21 +11,34 @@
  *  - review — third-party code review with a configured review model (third-review)
  *  - compact — dedicated compact model for /compact + auto-compact summaries
  *  - autostart — replay project-declared slash commands at session start (/add-dir persistence)
+ *  - permission — session-scoped boundary permission checks (/ask-perm)
+ *
+ * `ask` and `permission` are independent gates on one bus: each answers its own
+ * question and the strictest answer wins, so they compose rather than replace
+ * each other. The bus is installed once, after every gate is registered.
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createGateHub } from "./lib/gates.js";
 import { registerAsk } from "./features/ask/index.js";
 import { registerAutostart } from "./features/autostart/index.js";
 import { registerCompact } from "./features/compact/index.js";
 import { registerFavorites } from "./features/favorites/index.js";
+import { registerPermission } from "./features/permission/index.js";
 import { registerReview } from "./features/review/index.js";
 import { registerStash } from "./features/stash/index.js";
 
 export default function piToolkits(pi: ExtensionAPI): void {
-	registerAsk(pi);
+	const gates = createGateHub();
+
+	registerAsk(pi, gates);
+	// Permission registers its session_start reset before autostart, so a
+	// project-declared `/ask-perm ...` runs against a freshly reset mode.
+	registerPermission(pi, gates);
 	registerAutostart(pi);
 	registerCompact(pi);
 	registerFavorites(pi);
 	registerReview(pi);
 	registerStash(pi);
-	// registerXxx(pi); // future features
+
+	gates.install(pi);
 }

package/src/lib/gates.test.ts

@@ -0,0 +1,171 @@
+/**
+ * Gate bus tests.
+ *
+ * The bus is the composition contract between features: a block short-circuits,
+ * an allow never overrides, dialogs are serialized, and a failing gate fails
+ * closed.
+ */
+import { describe, expect, it } from "vitest";
+import type {
+	ExtensionContext,
+	ToolCallEvent,
+} from "@earendil-works/pi-coding-agent";
+import {
+	createGateHub,
+	type AskDecision,
+	type AskRequest,
+	type ToolGate,
+} from "./gates.js";
+
+function bashEvent(command = "ls"): ToolCallEvent {
+	return {
+		type: "tool_call",
+		toolCallId: "call-1",
+		toolName: "bash",
+		input: { command },
+	} as unknown as ToolCallEvent;
+}
+
+const ctx = {} as ExtensionContext;
+
+function askRequest(
+	decide: AskDecision | undefined,
+	applied: AskDecision[] = [],
+): AskRequest {
+	return {
+		title: "Permission required",
+		details: ["Command: rm x"],
+		root: "/proj",
+		present: async () => decide,
+		apply: (choice) => applied.push(choice),
+		denyReason: (choice) => `denied:${choice}`,
+	};
+}
+
+function gate(
+	name: string,
+	order: number,
+	verdict: ReturnType<ToolGate["evaluate"]>,
+): ToolGate {
+	return { name, order, evaluate: () => verdict };
+}
+
+describe("gate hub", () => {
+	it("allows when no gate has an opinion", async () => {
+		const hub = createGateHub();
+		hub.register(gate("noop", 10, undefined));
+		await expect(hub.handle(bashEvent(), ctx)).resolves.toBeUndefined();
+	});
+
+	it("an explicit allow does not override another gate's block", async () => {
+		const hub = createGateHub();
+		hub.register(gate("allow", 10, { kind: "allow" }));
+		hub.register(gate("block", 20, { kind: "block", reason: "no" }));
+		await expect(hub.handle(bashEvent(), ctx)).resolves.toEqual({ reason: "no" });
+	});
+
+	it("blocks immediately and skips later gates", async () => {
+		const hub = createGateHub();
+		let laterRan = false;
+		hub.register(gate("first", 10, { kind: "block", reason: "stop" }));
+		hub.register({
+			name: "later",
+			order: 20,
+			evaluate: () => {
+				laterRan = true;
+				return undefined;
+			},
+		});
+		await expect(hub.handle(bashEvent(), ctx)).resolves.toEqual({ reason: "stop" });
+		expect(laterRan).toBe(false);
+	});
+
+	it("runs gates in ascending order", async () => {
+		const hub = createGateHub();
+		const seen: string[] = [];
+		hub.register({
+			name: "second",
+			order: 20,
+			evaluate: () => {
+				seen.push("second");
+				return undefined;
+			},
+		});
+		hub.register({
+			name: "first",
+			order: 10,
+			evaluate: () => {
+				seen.push("first");
+				return undefined;
+			},
+		});
+		await hub.handle(bashEvent(), ctx);
+		expect(seen).toEqual(["first", "second"]);
+	});
+
+	it("applies an allow answer and resolves", async () => {
+		const hub = createGateHub();
+		const applied: AskDecision[] = [];
+		hub.register(gate("ask", 10, { kind: "ask", request: askRequest("allow", applied) }));
+		await expect(hub.handle(bashEvent(), ctx)).resolves.toBeUndefined();
+		expect(applied).toEqual(["allow"]);
+	});
+
+	it("blocks with the request's deny reason", async () => {
+		const hub = createGateHub();
+		const applied: AskDecision[] = [];
+		hub.register(
+			gate("ask", 10, { kind: "ask", request: askRequest("deny-session", applied) }),
+		);
+		await expect(hub.handle(bashEvent(), ctx)).resolves.toEqual({
+			reason: "denied:deny-session",
+		});
+		expect(applied).toEqual(["deny-session"]);
+	});
+
+	it("treats a cancelled or unanswerable dialog as a denial", async () => {
+		const hub = createGateHub();
+		hub.register(gate("ask", 10, { kind: "ask", request: askRequest(undefined) }));
+		const result = await hub.handle(bashEvent(), ctx);
+		expect(result?.reason).toContain("was not answered");
+	});
+
+	it("fails closed when a gate throws", async () => {
+		const hub = createGateHub();
+		hub.register({
+			name: "broken",
+			order: 10,
+			evaluate: () => {
+				throw new Error("boom");
+			},
+		});
+		const result = await hub.handle(bashEvent(), ctx);
+		expect(result?.reason).toContain("broken");
+		expect(result?.reason).toContain("blocked");
+	});
+
+	it("serializes dialogs across concurrent tool calls", async () => {
+		const hub = createGateHub();
+		let active = 0;
+		let maxActive = 0;
+		const present = async (): Promise<AskDecision> => {
+			active++;
+			maxActive = Math.max(maxActive, active);
+			await new Promise((resolve) => setTimeout(resolve, 5));
+			active--;
+			return "allow";
+		};
+		const request: AskRequest = {
+			title: "Permission required",
+			details: [],
+			root: "/proj",
+			present,
+			apply: () => {},
+			denyReason: () => "denied",
+		};
+		hub.register(gate("ask", 10, { kind: "ask", request }));
+
+		await Promise.all([hub.handle(bashEvent("a"), ctx), hub.handle(bashEvent("b"), ctx)]);
+		expect(maxActive).toBe(1);
+	});
+});

package/src/lib/gates.ts

@@ -0,0 +1,153 @@
+/**
+ * Tool-call gate bus.
+ *
+ * Features that must veto or confirm tool calls (`ask`, `permission`) register
+ * a {@link ToolGate} instead of installing their own `tool_call` handler. One
+ * handler composes every gate, which keeps the features independent: each gate
+ * speaks only about its own concern, and the call is allowed only when no gate
+ * objects.
+ *
+ * Composition rules:
+ *  - A `block` is final and short-circuits the remaining gates, so a call one
+ *    feature already denies never raises another feature's dialog.
+ *  - An `allow` never overrides another gate's `ask`/`block`; "no opinion" and
+ *    "explicitly allowed" are both non-blocking.
+ *  - `ask`s are presented through a single queue. Pi runs tool calls from one
+ *    assistant message in parallel while `ctx.ui.custom` owns a single inline
+ *    slot; a second presentation would mount over the first and strand its
+ *    promise. The queue serializes our own presentations; the host slot is
+ *    still shared with other extensions (pi does not arbitrate globally).
+ *  - A gate that throws blocks the call (fail closed), matching pi's own
+ *    `tool_call` handler contract.
+ */
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	ToolCallEvent,
+} from "@earendil-works/pi-coding-agent";
+
+/** What the operator chose in an interactive ask. */
+export type AskDecision =
+	| "allow"
+	| "allow-session"
+	| "deny"
+	| "deny-session";
+
+/**
+ * One interactive confirmation a gate wants before the call may run.
+ *
+ * `present` renders the dialog (or falls back to a host selector) and resolves
+ * `undefined` when there is no way to ask or the operator cancelled — both are
+ * treated as a denial. `apply` records the decision (session grants) and runs
+ * only for a real answer.
+ */
+export interface AskRequest {
+	/** Short title, e.g. "Permission required". */
+	readonly title: string;
+	/** Context lines: command, target, scope, reason. */
+	readonly details: readonly string[];
+	/** The directory a session grant would cover. */
+	readonly root: string;
+	present(ctx: ExtensionContext): Promise<AskDecision | undefined>;
+	apply(decision: AskDecision): void;
+	/** Model-facing reason when the operator answers deny/deny-session. */
+	denyReason(decision: AskDecision): string;
+}
+
+/** A gate's opinion about one tool call. */
+export type GateVerdict =
+	| undefined
+	| { readonly kind: "allow" }
+	| { readonly kind: "block"; readonly reason: string }
+	| { readonly kind: "ask"; readonly request: AskRequest };
+
+/** One feature's tool-call policy. Lower `order` runs first. */
+export interface ToolGate {
+	readonly name: string;
+	readonly order: number;
+	evaluate(
+		event: ToolCallEvent,
+		ctx: ExtensionContext,
+	): GateVerdict | Promise<GateVerdict>;
+}
+
+/** Result of composing the gates: a block reason, or nothing (allow). */
+export type GateResult = { readonly reason: string } | undefined;
+
+export interface GateHub {
+	register(gate: ToolGate): void;
+	/** Compose every gate for one call (also the unit-test entry point). */
+	handle(event: ToolCallEvent, ctx: ExtensionContext): Promise<GateResult>;
+	/** Install the single `tool_call` handler that owns the gates. */
+	install(pi: ExtensionAPI): void;
+}
+
+function messageOf(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+export function createGateHub(): GateHub {
+	const gates: ToolGate[] = [];
+	let queue: Promise<void> = Promise.resolve();
+
+	/**
+	 * Serialize dialogs without letting one rejection poison the queue:
+	 * the tail always settles, the caller still sees its own outcome.
+	 */
+	function runExclusive<T>(present: () => Promise<T>): Promise<T> {
+		const next = queue.then(present, present);
+		queue = next.then(
+			() => undefined,
+			() => undefined,
+		);
+		return next;
+	}
+
+	async function handle(
+		event: ToolCallEvent,
+		ctx: ExtensionContext,
+	): Promise<GateResult> {
+		const pending: AskRequest[] = [];
+		for (const gate of [...gates].sort((a, b) => a.order - b.order)) {
+			let verdict: GateVerdict;
+			try {
+				verdict = await gate.evaluate(event, ctx);
+			} catch (error) {
+				return {
+					reason: `Permission check failed in "${gate.name}": ${messageOf(error)}. The call was blocked.`,
+				};
+			}
+			if (!verdict || verdict.kind === "allow") continue;
+			if (verdict.kind === "block") return { reason: verdict.reason };
+			pending.push(verdict.request);
+		}
+
+		for (const request of pending) {
+			const decision = await runExclusive(() => request.present(ctx));
+			if (decision === undefined) {
+				return {
+					reason: `Permission check "${request.title}" was not answered; the call was blocked.`,
+				};
+			}
+			request.apply(decision);
+			if (decision === "deny" || decision === "deny-session") {
+				return { reason: request.denyReason(decision) };
+			}
+		}
+		return undefined;
+	}
+
+	return {
+		register(gate) {
+			gates.push(gate);
+		},
+		handle,
+		install(pi) {
+			pi.on("tool_call", async (event, ctx) => {
+				const result = await handle(event, ctx);
+				if (!result) return;
+				return { block: true, reason: result.reason };
+			});
+		},
+	};
+}