@andares/pi-toolkits 0.9.8 → 0.10.0

package/src/lib/gates.ts

@@ -23,12 +23,22 @@
  *    at a time instead of a pile of stacked dialogs on 1.4.0.
  *  - A gate that throws blocks the call (fail closed), matching pi's own
  *    `tool_call` handler contract.
+ *
+ * The hub is also the single audit point (`lib/approval-log.ts`): it is the
+ * only place that sees the gate verdict, the prompt, the operator's answer,
+ * and the final outcome in one frame. Features attach a structured `audit`
+ * payload; the hub writes blocks and asks, while a gate that auto-allows an
+ * operation it considers worth recording writes its own `allow` record through
+ * the same log (permission's session-grant allows). Logging never changes a
+ * verdict: the writer fails open and the hub swallows payload errors.
  */
 import type {
 	ExtensionAPI,
 	ExtensionContext,
 	ToolCallEvent,
 } from "@earendil-works/pi-coding-agent";
+import type { ApprovalLog, ApprovalRecord } from "./approval-log.js";
+import { auditBase, auditTool, clipText, sessionIdOf } from "./approval-log.js";
 
 /** What the operator chose in an interactive ask. */
 export type AskDecision =
@@ -52,17 +62,37 @@ export interface AskRequest {
 	readonly details: readonly string[];
 	/** The directory a session grant would cover. */
 	readonly root: string;
+	/**
+	 * Structured context written with the audit record when the log is on.
+	 * Built by the feature; the hub adds the tool call, answer and outcome.
+	 */
+	readonly audit?: ApprovalRecord;
 	present(ctx: ExtensionContext): Promise<AskDecision | undefined>;
 	apply(decision: AskDecision): void;
 	/** Model-facing reason when the operator answers deny/deny-session. */
 	denyReason(decision: AskDecision): string;
+	/**
+	 * Called exactly once when the ask settles — answer, cancel, or "never
+	 * shown because an earlier gate blocked". Returned fields are merged into
+	 * the audit record (for example the session grant an answer created).
+	 * A throwing settle is ignored: auditing must not affect the verdict.
+	 */
+	settle?(
+		decision: AskDecision | undefined,
+		meta: { presented: boolean; ms: number },
+	): ApprovalRecord | undefined;
 }
 
 /** A gate's opinion about one tool call. */
 export type GateVerdict =
 	| undefined
 	| { readonly kind: "allow" }
-	| { readonly kind: "block"; readonly reason: string }
+	| {
+			readonly kind: "block";
+			readonly reason: string;
+			/** Structured context for the audit log. */
+			readonly audit?: ApprovalRecord;
+	  }
 	| { readonly kind: "ask"; readonly request: AskRequest };
 
 /** One feature's tool-call policy. Lower `order` runs first. */
@@ -78,6 +108,11 @@ export interface ToolGate {
 /** Result of composing the gates: a block reason, or nothing (allow). */
 export type GateResult = { readonly reason: string } | undefined;
 
+export interface GateHubOptions {
+	/** Write-only audit sink; absent in tests and when logging is off. */
+	readonly audit?: ApprovalLog;
+}
+
 export interface GateHub {
 	register(gate: ToolGate): void;
 	/** Compose every gate for one call (also the unit-test entry point). */
@@ -86,14 +121,74 @@ export interface GateHub {
 	install(pi: ExtensionAPI): void;
 }
 
+interface PendingAsk {
+	readonly gate: string;
+	readonly request: AskRequest;
+}
+
+interface SessionCounters {
+	session?: string;
+	startedAt: number;
+	calls: number;
+	asks: number;
+	blocks: number;
+	answers: Record<string, number>;
+	base?: ApprovalRecord;
+}
+
 function messageOf(error: unknown): string {
 	return error instanceof Error ? error.message : String(error);
 }
 
-export function createGateHub(): GateHub {
+function emptyCounters(session?: string, base?: ApprovalRecord): SessionCounters {
+	return {
+		session,
+		startedAt: Date.now(),
+		calls: 0,
+		asks: 0,
+		blocks: 0,
+		answers: {},
+		base,
+	};
+}
+
+/**
+ * Outcome label plus the counter key for a settled ask. A plain nested ternary
+ * chain here was unreadable and easy to get wrong, so the mapping lives in one
+ * named place.
+ */
+function answerLabel(
+	decision: AskDecision | undefined,
+	presented: boolean,
+	error: unknown,
+): { outcome: string; key: string } {
+	if (error !== undefined) return { outcome: "error", key: "error" };
+	if (!presented) return { outcome: "not-presented", key: "not-presented" };
+	if (decision === undefined) return { outcome: "cancelled", key: "cancelled" };
+	if (decision === "allow" || decision === "allow-session") {
+		return { outcome: "allowed", key: decision };
+	}
+	return { outcome: "blocked", key: decision };
+}
+
+export function createGateHub(options: GateHubOptions = {}): GateHub {
 	const gates: ToolGate[] = [];
 	let queue: Promise<void> = Promise.resolve();
 
+	const audit = options.audit;
+	const logging = audit !== undefined && audit.mode !== "off";
+	/**
+	 * Counters per session id. A single slot would be wrong as soon as two
+	 * sessions run in one process (a child/subagent session or a parent and a
+	 * replaced runtime): each call from the other session would flush the first
+	 * one's partial counters and start over, producing a burst of tiny summaries
+	 * with misattributed numbers. Keyed storage keeps each session's counters
+	 * intact regardless of interleaving.
+	 */
+	const countersBySession = new Map<string, SessionCounters>();
+	/** Sessions kept in memory at once; each entry is a handful of numbers. */
+	const MAX_TRACKED_SESSIONS = 8;
+
 	/**
 	 * Serialize dialogs without letting one rejection poison the queue:
 	 * the tail always settles, the caller still sees its own outcome.
@@ -107,27 +202,203 @@ export function createGateHub(): GateHub {
 		return next;
 	}
 
+	/**
+	 * One summary record per session gives the analysis a denominator without
+	 * filling the ring buffer with auto-allowed read/grep calls. It is written on
+	 * shutdown (quit / reload / session replacement) and when a stale session is
+	 * evicted; a crash loses at most the live sessions' counters.
+	 */
+	function flushSession(
+		key: string,
+		reason: string,
+		fallback?: ApprovalRecord,
+	): void {
+		const counters = countersBySession.get(key);
+		if (!counters) return;
+		countersBySession.delete(key);
+		if (!logging) return;
+		const base = counters.base ?? fallback;
+		const hadWork =
+			counters.calls > 0 || counters.asks > 0 || counters.blocks > 0;
+		if (base && hadWork) {
+			audit?.append({
+				...base,
+				ts: new Date().toISOString(),
+				event: "session",
+				reason,
+				durationMs: Date.now() - counters.startedAt,
+				counts: {
+					calls: counters.calls,
+					asks: counters.asks,
+					blocks: counters.blocks,
+					answers: counters.answers,
+				},
+			});
+		}
+	}
+
+	/** Counters for this call's session, creating the slot on first use. */
+	function countersFor(
+		session: string | undefined,
+		base: ApprovalRecord,
+	): SessionCounters {
+		const key = session ?? "";
+		let counters = countersBySession.get(key);
+		if (!counters) {
+			counters = emptyCounters(session, base);
+			countersBySession.set(key, counters);
+			if (countersBySession.size > MAX_TRACKED_SESSIONS) {
+				const oldest = countersBySession.keys().next().value;
+				if (oldest !== undefined && oldest !== key) {
+					flushSession(oldest, "evicted");
+				}
+			}
+		} else {
+			// Keep the newest envelope (cwd / model) for the summary.
+			counters.base = base;
+		}
+		return counters;
+	}
+
+	function logBlock(
+		gateName: string,
+		reason: string,
+		base: ApprovalRecord,
+		tool: ApprovalRecord,
+		payload: ApprovalRecord | undefined,
+		counters: SessionCounters | undefined,
+	): void {
+		if (!logging) return;
+		if (counters) counters.blocks++;
+		audit?.append({
+			...base,
+			...tool,
+			...(payload ?? {}),
+			event: "block",
+			gate: gateName,
+			reason: clipText(reason, 2048),
+		});
+	}
+
+	/**
+	 * Settle one ask and write its record. `presented: false` means an earlier
+	 * gate blocked before this dialog could run — recorded, not silently lost.
+	 */
+	function logAsk(
+		pending: PendingAsk,
+		base: ApprovalRecord,
+		tool: ApprovalRecord,
+		decision: AskDecision | undefined,
+		presented: boolean,
+		ms: number,
+		counters: SessionCounters | undefined,
+		queueMs?: number,
+		error?: unknown,
+	): void {
+		if (!logging) return;
+		let patch: ApprovalRecord | undefined;
+		try {
+			patch = pending.request.settle?.(error ? undefined : decision, {
+				presented,
+				ms,
+			});
+		} catch {
+			// Auditing must never change the verdict.
+		}
+		const { outcome, key } = answerLabel(decision, presented, error);
+		if (counters) counters.answers[key] = (counters.answers[key] ?? 0) + 1;
+
+		const request = pending.request;
+		const prompt = Array.isArray(request.audit?.prompt)
+			? request.audit.prompt
+			: [request.title, ...request.details];
+		audit?.append({
+			...base,
+			...tool,
+			...(request.audit ?? {}),
+			...(patch ?? {}),
+			event: "ask",
+			gate: pending.gate,
+			title: request.title,
+			prompt,
+			answer: decision
+				? { choice: decision, ms, ...(queueMs === undefined ? {} : { queueMs }) }
+				: null,
+			outcome,
+			...(error === undefined
+				? {}
+				: { error: clipText(messageOf(error), 1024) }),
+		});
+	}
+
 	async function handle(
 		event: ToolCallEvent,
 		ctx: ExtensionContext,
 	): Promise<GateResult> {
-		const pending: AskRequest[] = [];
+		const base = logging ? auditBase(ctx) : {};
+		const counters = logging ? countersFor(sessionIdOf(ctx), base) : undefined;
+		const tool = logging ? auditTool(event) : {};
+		if (counters) counters.calls++;
+
+		const pending: PendingAsk[] = [];
 		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.`,
-				};
+				const reason = `Permission check failed in "${gate.name}": ${messageOf(error)}. The call was blocked.`;
+				logBlock(gate.name, reason, base, tool, {
+					verdict: { action: "block", layer: "gate-error" },
+				}, counters);
+				for (const abandoned of pending) {
+					logAsk(abandoned, base, tool, undefined, false, 0, counters);
+				}
+				return { reason };
 			}
 			if (!verdict || verdict.kind === "allow") continue;
-			if (verdict.kind === "block") return { reason: verdict.reason };
-			pending.push(verdict.request);
+			if (verdict.kind === "block") {
+				logBlock(
+					gate.name,
+					verdict.reason,
+					base,
+					tool,
+					verdict.audit,
+					counters,
+				);
+				for (const abandoned of pending) {
+					logAsk(abandoned, base, tool, undefined, false, 0, counters);
+				}
+				return { reason: verdict.reason };
+			}
+			if (counters) counters.asks++;
+			pending.push({ gate: gate.name, request: verdict.request });
 		}
 
-		for (const request of pending) {
-			const decision = await runExclusive(() => request.present(ctx));
+		for (const current of pending) {
+			const request = current.request;
+			const started = Date.now();
+			let presentedAt = 0;
+			let decision: AskDecision | undefined;
+			let error: unknown;
+			try {
+				decision = await runExclusive(() => {
+					presentedAt = Date.now();
+					return request.present(ctx);
+				});
+			} catch (caught) {
+				error = caught;
+			}
+			const ms = Date.now() - started;
+			// `ms` is how long the call waited in total; `queueMs` is the part spent
+			// behind another dialog in the same assistant message. Analysis needs
+			// the split, otherwise a batch looks like a slow operator.
+			const queueMs = presentedAt === 0 ? ms : presentedAt - started;
+			logAsk(current, base, tool, decision, true, ms, counters, queueMs, error);
+			if (error !== undefined) {
+				return {
+					reason: `Permission dialog "${request.title}" failed: ${messageOf(error)}. The call was blocked.`,
+				};
+			}
 			if (decision === undefined) {
 				return {
 					reason: `Permission check "${request.title}" was not answered; the call was blocked.`,
@@ -152,6 +423,16 @@ export function createGateHub(): GateHub {
 				if (!result) return;
 				return { block: true, reason: result.reason };
 			});
+			// `session_shutdown` fires for quit / reload / session replacement;
+			// the summary closes the current segment before the runtime goes away.
+			pi.on("session_shutdown", (event, ctx) => {
+				if (!logging) return;
+				// `ctx` is the session being torn down, so this flushes exactly that
+				// session's counters. Other tracked sessions stay untouched: an
+				// in-process child session ending must not truncate its parent's
+				// summary into two halves. Stale slots are reclaimed by eviction.
+				flushSession(sessionIdOf(ctx) ?? "", event.reason, auditBase(ctx));
+			});
 		},
 	};
 }