@andares/pi-toolkits 0.9.7 → 0.10.0

package/src/features/compact/prompt.ts

@@ -6,14 +6,15 @@
  * summaries produced by the configured compact model are formatted exactly
  * like pi's own compaction output. Only the executing model differs.
  * Verified byte-identical against every published version of the supported
- * window (1.0.0 → 1.3.0): dist/core/compaction/compaction.js and
- * core/usage-totals.js are unchanged files across that span, and the only
- * utils.js change (1.2.0 dropping assistant thinking from
+ * window (1.1.0 → 1.4.0): core/usage-totals.js is unchanged across that
+ * span, the only utils.js change (1.2.0 dropping assistant thinking from
  * serializeConversation) does not touch the strings mirrored here — that
- * serializer is imported from the host, not mirrored. 0.87.0 shipped a
- * different split-turn prefix prompt; the text mirrored here is 0.87.1's
- * fix, and the mirror is the only variant any supported host gets —
- * intentional.
+ * serializer is imported from the host, not mirrored — and compaction.js
+ * changed once, in 1.4.0, in the output budget and the split-turn focus
+ * handling (both adopted here, see buildTurnPrefixPromptText). 0.87.0
+ * shipped a different split-turn prefix prompt; the text mirrored here is
+ * 0.87.1's fix, and the mirror is the only variant any supported host gets
+ * — intentional.
  *
  * Update these strings whenever pi changes its built-in prompts (diff
  * dist/core/compaction/compaction.js between versions).
@@ -146,11 +147,21 @@ export function buildHistoryPromptText(
 
 /**
  * Build the split-turn prefix prompt text (pi 0.87.1
- * generateTurnPrefixSummary): `# Conversation` block followed by
- * `# Instructions`.
+ * generateTurnPrefixSummary, extended in 1.4.0): `# Conversation` block
+ * followed by `# Instructions`, with the `/compact <instructions>` focus
+ * appended as `Additional focus: ...`. 1.4.0 added that last line (#11058:
+ * the focus used to be dropped when the split turn was the only new
+ * content since the last compaction); we use the fixed form on every host.
  */
-export function buildTurnPrefixPromptText(conversationText: string): string {
-	return `# Conversation\n${conversationText}\n\n# Instructions\n${TURN_PREFIX_SUMMARIZATION_PROMPT}`;
+export function buildTurnPrefixPromptText(
+	conversationText: string,
+	customInstructions?: string,
+): string {
+	let promptText = `# Conversation\n${conversationText}\n\n# Instructions\n${TURN_PREFIX_SUMMARIZATION_PROMPT}`;
+	if (customInstructions) {
+		promptText = `${promptText}\n\nAdditional focus: ${customInstructions}`;
+	}
+	return promptText;
 }
 
 /** File-operation sets extracted by pi's prepareCompaction. */
@@ -203,7 +214,7 @@ export function formatFileOperations(
 /**
  * Combine two provider usage records field-wise (pi 0.87.1 compaction.js
  * combineUsage, moved verbatim to core/usage-totals.js in 0.99.0 and
- * unchanged through 1.3.0): used when
+ * unchanged through 1.4.0): used when
  * a split turn produces two summarization calls.
  */
 export function combineUsage<T extends UsageLike>(first: T, second: T): T {

package/src/features/favorites/constants.ts

@@ -8,8 +8,8 @@
  * bindings — only the cycle semantics change (patch-cycle.ts), so no
  * keybinding conflicts arise.
  *
- * Verified against every published version of the supported window
- * (1.0.0 → 1.3.0) keybinding
+ * Verified against every published version of the supported range
+ * (0.99.0 → 1.4.0) keybinding
  * tables + pi-tui input dispatch on WSL2 + Windows Terminal; re-run
  * `pnpm check:keybindings` after every host upgrade before trusting this.
  */
@@ -30,11 +30,12 @@ export const FAVORITES_FILE = "pi-toolkits-favorites.json";
  * Windows/WSL `tui.altScreen.search` resolves to ctrl+f, and
  * `TuiAltScreen.handleViewportInput()` checks it before
  * `shouldDeferViewportInputToOverlay()`, so the keystroke opens transcript
- * search and the selector never sees it (verified in pi-tui 1.3.0
+ * search and the selector never sees it (verified in pi-tui 1.4.0
  * `dist/tui-alt-screen.js`: the search check is the first key branch and
- * returns `{ consume: true }` unconditionally).
+ * returns `{ consume: true }` unconditionally; the 1.4.0 changes to that
+ * file are exit/teardown only).
  *
- * Why ctrl+alt+f was discarded: clean at the pi layer across 1.0–1.3 (only
+ * Why ctrl+alt+f was discarded: clean at the pi layer across 1.1–1.4 (only
  * ctrl+alt+] is taken from that family) and byte-distinguishable without
  * kitty — but grabbed at the OS/app layer on the author's machine by a
  * Windows screenshot tool, so it never reached the terminal. Lesson: a key

package/src/features/favorites/patch-cycle.ts

@@ -15,7 +15,8 @@
  *    model available" feedback); otherwise jump to it
  *  - the apply logic mirrors pi's _cycleScopedModel/_cycleAvailableModel
  *    (byte-identical across every published version in the supported window
- *    1.0.0 → 1.3.0:
+ *    1.1.0 → 1.4.0 — `cycleModel` itself is untouched by 1.4.0's recovery and
+ *    tool-restore rewrites:
  *    state swap, session persistence, default-model persistence only when
  *    `options.persist` is set, thinking-level re-clamp, model_select emit
  *    with source "cycle")
@@ -31,9 +32,9 @@ import { getFavoritesStore, modelKey } from "./store.js";
 
 /**
  * pi's `Model<any>` — the exact type of `ModelCycleResult.model`
- * (pi-coding-agent 1.0–1.3; the field is unchanged across that span).
+ * (pi-coding-agent 1.1–1.4; the field is unchanged across that span).
  * Derived here instead of importing `Model` from @earendil-works/pi-ai,
- * whose index.d.ts (1.0 through 1.3.0 alike) re-exports it via an
+ * whose index.d.ts (1.1 through 1.4.0 alike) re-exports it via an
  * extensioned `"./types.ts"` specifier that not every TS resolver substitutes
  * to `types.d.ts` (tsc 5.9 bundler does; other tsserver builds don't).
  */

package/src/features/favorites/patch-selector.ts

@@ -21,8 +21,8 @@
  * upgraded internals), patches are skipped with a warning — the extension
  * keeps loading and ctrl+p falls back to stock behavior. The prototype
  * shape touched here (handleInput/updateList/filterModels and the instance
- * fields below) is byte-identical across every published version in
- * pi 1.0.0 → 1.3.0 (and 0.99.0 → 1.2.0 before the floor moved).
+ * fields below) is byte-identical across the mandatory window
+ * pi 1.1.0 → 1.4.0 (and exercised by the 0.99.0 → 1.0.4 backward probes).
  */
 import {
 	ModelSelectorComponent,

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

@@ -0,0 +1,159 @@
+/**
+ * Permission audit payload: the decomposition, the scope/effect of every
+ * target, and the machine-readable rule layer must survive into the log.
+ */
+import { mkdtempSync, realpathSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { buildPermissionAudit, commandDigest } from "./audit.js";
+import { DEFAULT_MODES, type PermissionModes } from "./constants.js";
+import { canonicalize } from "./paths.js";
+import {
+	decideProgram,
+	decideUnit,
+	type PolicyContext,
+} from "./policy.js";
+import { SessionRules } from "./session-rules.js";
+import { parseCommandUnits } from "./units.js";
+
+function project(): string {
+	return realpathSync(mkdtempSync(join(tmpdir(), "pi-perm-audit-")));
+}
+
+function makeContext(
+	cwd: string,
+	modes: PermissionModes = DEFAULT_MODES,
+	rules = new SessionRules(),
+): PolicyContext {
+	return { modes, roots: [canonicalize(cwd)], rules };
+}
+
+function audit(command: string, ctx: PolicyContext, prompt?: readonly string[]) {
+	const units = parseCommandUnits(command, ctx.roots[0] ?? "/");
+	return buildPermissionAudit({
+		cwd: ctx.roots[0] ?? "/",
+		modes: ctx.modes,
+		roots: ctx.roots,
+		units,
+		unitDecisions: units.map((unit) => decideUnit(unit, ctx)),
+		decision: decideProgram(units, ctx),
+		...(prompt === undefined ? {} : { prompt }),
+	});
+}
+
+describe("permission audit payload", () => {
+	it("records the decomposition, target scope and deciding layer", () => {
+		const cwd = project();
+		const payload = audit("rm -rf /tmp/outside/x", makeContext(cwd));
+
+		expect(payload.modes).toEqual({
+			inRead: "allow",
+			inWrite: "allow",
+			outRead: "allow",
+			outWrite: "ask",
+		});
+		expect(payload.roots).toEqual([canonicalize(cwd)]);
+		expect(payload.units).toEqual([
+			expect.objectContaining({
+				head: "rm",
+				command: "rm",
+				args: ["-rf", "/tmp/outside/x"],
+				base: canonicalize(cwd),
+				effect: "write",
+				opaque: false,
+				action: "ask",
+				layer: "mode",
+				targets: [
+					{
+						path: "/tmp/outside/x",
+						canonical: "/tmp/outside/x",
+						effect: "write",
+						source: "operand",
+						scope: "out",
+					},
+				],
+			}),
+		]);
+		expect(payload.verdict).toMatchObject({
+			action: "ask",
+			layer: "mode",
+			unit: 0,
+			target: "/tmp/outside/x",
+			effect: "write",
+			scope: "out",
+			grantScope: "root",
+			grantRoot: "/tmp/outside",
+		});
+	});
+
+	it("keeps the secret-table layer for a denied credential read", () => {
+		const cwd = project();
+		const payload = audit(`cat ${homedir()}/.ssh/id_rsa`, makeContext(cwd));
+		expect(payload.verdict).toMatchObject({
+			action: "deny",
+			layer: "secret",
+			scope: "out",
+			effect: "read",
+		});
+		expect(String((payload.verdict as Record<string, unknown>).reason)).toContain(
+			"fixed safety table",
+		);
+	});
+
+	it("marks an opaque command and records a command-scoped grant", () => {
+		const cwd = project();
+		const command = 'git -C "$DIR" log';
+		const ctx = makeContext(cwd);
+		const units = parseCommandUnits(command, cwd);
+		const payload = audit(command, ctx);
+
+		expect(units[0]?.opaque).toBe(true);
+		expect((payload.units as Array<Record<string, unknown>>)[0]).toMatchObject({
+			opaque: true,
+			action: "ask",
+			layer: "opaque",
+		});
+		expect(payload.verdict).toMatchObject({
+			action: "ask",
+			layer: "opaque",
+			grantScope: "command",
+			grantDigest: commandDigest(units),
+		});
+		expect(
+			(payload.verdict as Record<string, unknown>).grantRoot,
+		).toBeUndefined();
+	});
+
+	it("records an in-project mode allow with its layer", () => {
+		const cwd = project();
+		const payload = audit(`rm -rf ${cwd}/build`, makeContext(cwd));
+		expect(payload.verdict).toMatchObject({
+			action: "allow",
+			layer: "mode",
+			scope: "in",
+		});
+	});
+
+	it("carries the exact prompt lines when asked", () => {
+		const cwd = project();
+		const payload = audit("rm -rf /tmp/outside/x", makeContext(cwd), [
+			"Permission required",
+			"Command: rm -rf /tmp/outside/x",
+		]);
+		expect(payload.prompt).toEqual([
+			"Permission required",
+			"Command: rm -rf /tmp/outside/x",
+		]);
+	});
+
+	it("clips long arguments but keeps the target", () => {
+		const cwd = project();
+		const longArg = `--flag=${"x".repeat(2000)}`;
+		const payload = audit(`rm -rf /tmp/outside/x ${longArg}`, makeContext(cwd));
+		const unit = (payload.units as Array<Record<string, unknown>>)[0];
+		const args = unit.args as string[];
+		expect(args[2]).toContain("[+");
+		expect(unit.targets).toHaveLength(1);
+	});
+});

package/src/features/permission/audit.ts

@@ -0,0 +1,145 @@
+/**
+ * permission feature — the audit payload.
+ *
+ * The gate bus owns the record envelope (session, tool call, answer, outcome);
+ * this module contributes the part only the permission layer knows: the four
+ * modes and session roots in force, the bash decomposition, and which rule
+ * produced the verdict.
+ *
+ * The payload is deliberately lossless for *policy analysis* — every unit and
+ * every target survives, including the parser's `opaque` note — while being
+ * bounded: units, targets, args and long strings are capped, and the final
+ * serializer drops detail with a visible `truncated` marker rather than
+ * silently cutting a field. File contents never enter this payload.
+ */
+import { createHash } from "node:crypto";
+import type { ApprovalRecord } from "../../lib/approval-log.js";
+import { clipText } from "../../lib/approval-log.js";
+import type { PermissionModes } from "./constants.js";
+import { canonicalize, insideAnyRoot } from "./paths.js";
+import {
+	decisionGrantRoot,
+	type PolicyDecision,
+} from "./policy.js";
+import type { CommandUnit } from "./units.js";
+
+const MAX_UNITS = 32;
+const MAX_TARGETS = 32;
+const MAX_ARGS = 64;
+const ARG_CHARS = 512;
+const RAW_CHARS = 8192;
+const PATH_CHARS = 1024;
+const NOTE_CHARS = 512;
+const REASON_CHARS = 2048;
+
+export interface PermissionAuditInput {
+	readonly cwd: string;
+	readonly modes: PermissionModes;
+	/** Canonical session roots (working directory plus added directories). */
+	readonly roots: readonly string[];
+	readonly units: readonly CommandUnit[];
+	/** Verdict for each unit, in the same order as {@link units}. */
+	readonly unitDecisions: readonly PolicyDecision[];
+	/** Aggregate verdict (the strictest unit wins). */
+	readonly decision: PolicyDecision;
+	/** Exact dialog lines, when this payload belongs to an ask. */
+	readonly prompt?: readonly string[];
+}
+
+/** Short digest of the command text, for grouping opaque grants. */
+export function commandDigest(units: readonly CommandUnit[]): string {
+	return createHash("sha256")
+		.update(units.map((unit) => unit.raw).join(" ; "))
+		.digest("hex")
+		.slice(0, 16);
+}
+
+function serializeUnit(
+	unit: CommandUnit,
+	decision: PolicyDecision | undefined,
+	roots: readonly string[],
+): ApprovalRecord {
+	const targets = unit.targets.slice(0, MAX_TARGETS).map((target) => {
+		const canonical = canonicalize(target.path);
+		return {
+			path: clipText(target.path, PATH_CHARS),
+			canonical: clipText(canonical, PATH_CHARS),
+			effect: target.effect,
+			source: target.source,
+			scope: insideAnyRoot(roots, canonical) ? "in" : "out",
+		};
+	});
+	return {
+		raw: clipText(unit.raw, RAW_CHARS),
+		head: unit.headWord,
+		command: unit.command,
+		args: unit.args.slice(0, MAX_ARGS).map((arg) => clipText(arg, ARG_CHARS)),
+		base: unit.base === null ? null : clipText(canonicalize(unit.base), PATH_CHARS),
+		effect: unit.effect,
+		opaque: unit.opaque,
+		...(unit.note === undefined ? {} : { note: clipText(unit.note, NOTE_CHARS) }),
+		...(decision === undefined
+			? {}
+			: { action: decision.action, layer: decision.layer }),
+		targets,
+	};
+}
+
+function serializeVerdict(
+	input: PermissionAuditInput,
+): ApprovalRecord {
+	const decision = input.decision;
+	const unitIndex = input.units.indexOf(decision.unit);
+	const target = decision.target;
+	const grantScope = decision.unit.opaque ? "command" : "root";
+	return {
+		action: decision.action,
+		layer: decision.layer,
+		...(unitIndex < 0 ? {} : { unit: unitIndex }),
+		...(target === undefined
+			? {}
+			: {
+					target: clipText(target.path, PATH_CHARS),
+					effect: target.effect,
+					scope: target.scope,
+				}),
+		grantScope,
+		...(grantScope === "root"
+			? {
+					grantRoot: clipText(
+						decisionGrantRoot(decision, () => input.cwd),
+						PATH_CHARS,
+					),
+				}
+			: { grantDigest: commandDigest(input.units) }),
+		...(decision.reason === undefined
+			? {}
+			: { reason: clipText(decision.reason, REASON_CHARS) }),
+	};
+}
+
+/** Structured audit fields for one permission decision. */
+export function buildPermissionAudit(
+	input: PermissionAuditInput,
+): ApprovalRecord {
+	const unitDecisions = input.unitDecisions;
+	return {
+		modes: {
+			inRead: input.modes.inRead,
+			inWrite: input.modes.inWrite,
+			outRead: input.modes.outRead,
+			outWrite: input.modes.outWrite,
+		},
+		roots: input.roots
+			.slice(0, 16)
+			.map((root) => clipText(root, PATH_CHARS)),
+		units: input.units
+			.slice(0, MAX_UNITS)
+			.map((unit, index) => serializeUnit(unit, unitDecisions[index], input.roots)),
+		...(input.units.length > MAX_UNITS
+			? { unitsOmitted: input.units.length - MAX_UNITS }
+			: {}),
+		verdict: serializeVerdict(input),
+		...(input.prompt === undefined ? {} : { prompt: [...input.prompt] }),
+	};
+}

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

@@ -6,7 +6,7 @@
  * selector, and the rest through the gate's verdicts and the command handler.
  */
 import { mkdtempSync, realpathSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { beforeEach, describe, expect, it } from "vitest";
 import type {
@@ -14,6 +14,7 @@ import type {
 	ExtensionContext,
 	ToolCallEvent,
 } from "@earendil-works/pi-coding-agent";
+import type { ApprovalLog, ApprovalRecord } from "../../lib/approval-log.js";
 import type { AskDecision, GateHub, ToolGate } from "../../lib/gates.js";
 import {
 	clearJailedTool,
@@ -65,7 +66,7 @@ interface Harness {
 	banner(): { systemPrompt: string } | undefined;
 }
 
-function makeHarness(): Harness {
+function makeHarness(audit?: ApprovalLog): Harness {
 	const cwd = realpathSync(mkdtempSync(join(tmpdir(), "pi-perm-test-")));
 	const statuses: Harness["statuses"] = [];
 	const notes: Harness["notes"] = [];
@@ -116,7 +117,7 @@ function makeHarness(): Harness {
 		registerEntryRenderer() {},
 	} as unknown as ExtensionAPI;
 
-	registerPermission(pi, hub);
+	registerPermission(pi, hub, { audit });
 	const gate = captured[0];
 	if (!gate || !commandHandler) throw new Error("permission did not register");
 
@@ -154,6 +155,7 @@ interface AskVerdict {
 	request: {
 		details: readonly string[];
 		root: string;
+		audit?: ApprovalRecord;
 		present(ctx: ExtensionContext): Promise<AskDecision | undefined>;
 		apply(decision: AskDecision): void;
 	};
@@ -435,3 +437,136 @@ describe("self-jailed tools", () => {
 		expect(asAsk(await h.evaluate(customEvent("scratchpad"))).kind).toBe("ask");
 	});
 });
+
+describe("audit log", () => {
+	function makeAudit(): { audit: ApprovalLog; records: ApprovalRecord[] } {
+		const records: ApprovalRecord[] = [];
+		return {
+			records,
+			audit: {
+				dir: "/tmp/pi-perm-audit",
+				mode: "interesting",
+				active: true,
+				append: (record) => records.push(record),
+			},
+		};
+	}
+
+	it("attaches the decomposition to an ask verdict", async () => {
+		const { audit } = makeAudit();
+		const h = makeHarness(audit);
+		await h.command("allow allow allow ask");
+		const verdict = asAsk(await h.evaluate(bashEvent("rm -rf /tmp/outside/x")));
+		expect(verdict.request.audit).toMatchObject({
+			modes: { outWrite: "ask" },
+			verdict: {
+				action: "ask",
+				layer: "mode",
+				target: "/tmp/outside/x",
+				scope: "out",
+			},
+		});
+		expect(
+			(verdict.request.audit?.units as Array<Record<string, unknown>>)[0],
+		).toMatchObject({
+			command: "rm",
+			opaque: false,
+			action: "ask",
+			layer: "mode",
+		});
+	});
+
+	it("attaches the deciding layer to a deny verdict", async () => {
+		const { audit } = makeAudit();
+		const h = makeHarness(audit);
+		await h.command("allow allow allow ask");
+		const verdict = (await h.evaluate(
+			bashEvent(`cat ${homedir()}/.ssh/id_rsa`),
+		)) as {
+			kind: "block";
+			reason: string;
+			audit?: ApprovalRecord;
+		};
+		expect(verdict.kind).toBe("block");
+		expect(verdict.audit?.verdict).toMatchObject({
+			action: "deny",
+			layer: "secret",
+		});
+	});
+
+	it("records mode changes with their source", async () => {
+		const { audit, records } = makeAudit();
+		const h = makeHarness(audit);
+		await h.command("allow allow allow ask");
+		expect(records.at(-1)).toMatchObject({
+			event: "mode",
+			enabled: true,
+			source: "args",
+			via: "manual",
+			modes: { inRead: "allow", outWrite: "ask" },
+		});
+		await h.command("");
+		expect(records.at(-1)).toMatchObject({
+			event: "mode",
+			enabled: false,
+			source: "toggle",
+		});
+	});
+
+	it("marks an autostart-dispatched mode change", async () => {
+		const { audit, records } = makeAudit();
+		const h = makeHarness(audit);
+		markStartupCommand("ask-perm");
+		await h.command("allow allow allow ask");
+		expect(records.at(-1)).toMatchObject({
+			event: "mode",
+			via: "autostart",
+		});
+	});
+});
+
+describe("audit log — session-grant allows", () => {
+	function makeAudit(): { audit: ApprovalLog; records: ApprovalRecord[] } {
+		const records: ApprovalRecord[] = [];
+		return {
+			records,
+			audit: {
+				dir: "/tmp/pi-perm-audit",
+				mode: "interesting",
+				active: true,
+				append: (record) => records.push(record),
+			},
+		};
+	}
+
+	it("records the repeat call a directory grant made free", async () => {
+		const { audit, records } = makeAudit();
+		const h = makeHarness(audit);
+		await h.command("allow allow allow ask");
+		const first = asAsk(await h.evaluate(bashEvent("rm -rf /tmp/outside/x")));
+		first.request.apply("allow-session");
+		expect(await h.evaluate(bashEvent("rm -rf /tmp/outside/y"))).toBeUndefined();
+
+		const allow = records.find((record) => record.event === "allow");
+		expect(allow).toMatchObject({
+			event: "allow",
+			verdict: { action: "allow", layer: "session-allow", scope: "out" },
+		});
+	});
+
+	it("records a program-level grant on an opaque command too", async () => {
+		const { audit, records } = makeAudit();
+		const h = makeHarness(audit);
+		await h.command("allow allow allow ask");
+		const command = 'cd "$DIR" && rm x';
+		const first = asAsk(await h.evaluate(bashEvent(command)));
+		first.request.apply("allow-session");
+		expect(await h.evaluate(bashEvent(command))).toBeUndefined();
+
+		const allow = records.find((record) => record.event === "allow");
+		expect(allow).toMatchObject({
+			event: "allow",
+			verdict: { action: "allow", layer: "session-command", grantScope: "command" },
+		});
+	});
+});