@andares/pi-toolkits 0.7.3 → 0.9.0

package/src/features/autostart/autostart.test.ts

@@ -16,6 +16,7 @@ import {
 	AUTOSTART_CONFIG_PATH,
 	AutostartParseError,
 	commandNameOf,
+	GLOBAL_AUTOSTART_FILENAME,
 	parseAutostartConfig,
 	RUNNABLE_REASONS,
 } from "./autostart.js";
@@ -138,8 +139,16 @@ interface Harness {
 async function makeHarness(
 	config: string | null,
 	configAsDir = false,
+	globalConfig: string | null = null,
 ): Promise<Harness> {
 	const cwd = await mkdtemp(join(tmpdir(), "pi-autostart-test-"));
+	// The agent dir lives inside the temp project so cleanup covers it; passing
+	// it explicitly keeps the real ~/.pi/agent out of the test.
+	const agentDir = join(cwd, "agent");
+	await mkdir(agentDir, { recursive: true });
+	if (globalConfig !== null) {
+		await writeFile(join(agentDir, GLOBAL_AUTOSTART_FILENAME), globalConfig, "utf8");
+	}
 	if (configAsDir) {
 		// EISDIR setup: the config path exists but is a directory.
 		await mkdir(join(cwd, ".pi"), { recursive: true });
@@ -172,7 +181,7 @@ async function makeHarness(
 			}
 		},
 	} as unknown as ExtensionAPI;
-	registerAutostart(pi);
+	registerAutostart(pi, { agentDir });
 	return {
 		handler,
 		sent,
@@ -209,8 +218,9 @@ afterEach(async () => {
 async function harness(
 	config: string | null,
 	configAsDir = false,
+	globalConfig: string | null = null,
 ): Promise<Harness> {
-	const h = await makeHarness(config, configAsDir);
+	const h = await makeHarness(config, configAsDir, globalConfig);
 	current = h;
 	return h;
 }
@@ -312,4 +322,37 @@ describe("registerAutostart", () => {
 		expect(h.notifications).toHaveLength(1);
 		expect(h.notifications[0]?.type).toBe("error");
 	});
+
+	it("runs the global config before the project config", async () => {
+		const h = await harness(
+			'[command]\nrun = ["/add-dir ../project"]',
+			false,
+			'[command]\nrun = ["/ask on"]',
+		);
+		await h.start("startup");
+		expect(h.sent.map((entry) => entry.command)).toEqual([
+			"/ask on",
+			"/add-dir ../project",
+		]);
+		expect(h.notifications).toEqual([]);
+	});
+
+	it("runs the global config in an untrusted project but skips the project one", async () => {
+		const h = await harness(
+			'[command]\nrun = ["/add-dir ../project"]',
+			false,
+			'[command]\nrun = ["/ask on"]',
+		);
+		h.setTrusted(false);
+		await h.start("startup");
+		expect(h.sent.map((entry) => entry.command)).toEqual(["/ask on"]);
+		expect(h.notifications).toHaveLength(1);
+		expect(h.notifications[0]?.type).toBe("warning");
+	});
+
+	it("keeps running the project config when the global one is absent", async () => {
+		const h = await harness('[command]\nrun = ["/ask on"]', false, null);
+		await h.start("startup");
+		expect(h.sent.map((entry) => entry.command)).toEqual(["/ask on"]);
+	});
 });

package/src/features/autostart/autostart.ts

@@ -18,10 +18,12 @@
  */
 import { parse as parseToml } from "smol-toml";
 
-/** Project-relative location of the autostart config (`.pi/` is pi's
- *  project-config convention, precedent: `.pi/mcp.json`). */
+/** Project-relative location of the project autostart config. */
 export const AUTOSTART_CONFIG_PATH = ".pi/autostart.toml";
 
+/** File name of the operator's global autostart config, inside the agent dir. */
+export const GLOBAL_AUTOSTART_FILENAME = "autostart.toml";
+
 /**
  * session_start reasons that replay autostart commands:
  *  - startup / new: fresh session in the project — replay

package/src/features/autostart/index.ts

@@ -1,81 +1,120 @@
 /**
- * autostart feature — run project-declared slash commands at session start.
+ * autostart feature — run declared slash commands at session start.
  *
- * Config lives at `<project root>/.pi/autostart.toml` (see autostart.ts for
- * the schema). Execution gates, in order:
+ * Two sources, executed in order, never merged:
  *
- *  1. reason filter — only startup/new/fork replay (see RUNNABLE_REASONS)
- *  2. config file exists — a missing file is a silent opt-in skip
- *  3. `ctx.isProjectTrusted()` — an untrusted project never auto-executes
- *  4. per-command pre-validation against `pi.getCommands()`: only commands
- *     registered by an *extension* are dispatched. This is mandatory:
- *     sendUserMessage with an unhandled "/x" falls through prompt() to the
- *     model as a plain user message (pi agent-session.js), so an unknown
- *     command must be skipped here, never sent.
+ *  1. `<agentDir>/autostart.toml` — the operator's own defaults. Runs in every
+ *     project; no trust gate, because the file lives in pi's config directory
+ *     and is not controlled by the project.
+ *  2. `<project root>/.pi/autostart.toml` — project-declared commands. Gated on
+ *     `ctx.isProjectTrusted()`: an untrusted repository must not execute
+ *     anything.
+ *
+ * Execution gates, in order:
+ *
+ *  - reason filter — only startup/new/fork replay (see RUNNABLE_REASONS)
+ *  - config file exists — a missing file is a silent opt-in skip
+ *  - project trust (project source only)
+ *  - per-command pre-validation against `pi.getCommands()`: only commands
+ *    registered by an *extension* are dispatched. This is mandatory:
+ *    sendUserMessage with an unhandled "/x" falls through prompt() to the
+ *    model as a plain user message (pi agent-session.js), so an unknown
+ *    command must be skipped here, never sent.
  *
  * Dispatch uses `sendUserMessage(cmd, { expandPromptTemplates: true })` —
  * that flag is what routes "/cmd args" through _tryExecuteExtensionCommand
- * instead of the model prompt path. The wrapper defaults it to false
- * (each byte-identical across every published version of the supported
- * window, 0.99.0 → 1.2.0; see AGENTS.md host-compat
- * discipline for the version matrix).
+ * instead of the model prompt path. The wrapper defaults it to false in this
+ * package (each byte-identical across every published version of the supported
+ * window, 1.0.0 → 1.3.0; see AGENTS.md host-compat discipline for the version
+ * matrix).
  *
  * Only extension commands can run this way. Built-in commands (/compact,
  * /reload, /resume, …) are dispatched at the TUI layer and cannot be
  * triggered from the extension layer; skill commands (/skill:name) expand
- * into prompts rather than execute. First-party use case: `/add-dir`
- * (pi-add-dir), which is idempotent ("Already added" check).
+ * into prompts rather than execute. First-party use cases: `/add-dir`
+ * (pi-add-dir, idempotent) and `/ask-perm` (session-scoped permission).
  */
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
 	AUTOSTART_CONFIG_PATH,
 	AutostartParseError,
 	commandNameOf,
+	GLOBAL_AUTOSTART_FILENAME,
 	parseAutostartConfig,
 	RUNNABLE_REASONS,
 } from "./autostart.js";
 
-export function registerAutostart(pi: ExtensionAPI): void {
-	pi.on("session_start", async (event, ctx) => {
-		if (!RUNNABLE_REASONS.has(event.reason)) return;
+export interface AutostartOptions {
+	/** pi's config directory; defaults to `getAgentDir()`. */
+	readonly agentDir?: string;
+}
+
+interface Source {
+	readonly path: string;
+	readonly label: string;
+	/** Project sources require trust; the operator's global file does not. */
+	readonly requiresTrust: boolean;
+}
+
+function messageOf(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+export function registerAutostart(
+	pi: ExtensionAPI,
+	options: AutostartOptions = {},
+): void {
+	const agentDir = options.agentDir ?? getAgentDir();
 
+	async function readCommands(
+		ctx: ExtensionContext,
+		source: Source,
+	): Promise<string[] | undefined> {
 		let text: string;
 		try {
-			text = await readFile(join(ctx.cwd, AUTOSTART_CONFIG_PATH), "utf8");
+			text = await readFile(source.path, "utf8");
 		} catch (err) {
 			// Missing file = opt-in skip. Any other read failure (EACCES, EISDIR,
 			// …) is a misconfiguration the operator should hear about.
 			if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
 				ctx.ui.notify(
-					`autostart: skipped — cannot read ${AUTOSTART_CONFIG_PATH}: ${err instanceof Error ? err.message : String(err)}`,
+					`autostart: skipped ${source.label} — cannot read ${source.path}: ${messageOf(err)}`,
 					"warning",
 				);
 			}
-			return;
+			return undefined;
 		}
 
-		let commands: string[];
 		try {
-			commands = parseAutostartConfig(text);
+			return parseAutostartConfig(text);
 		} catch (err) {
 			const message = err instanceof AutostartParseError ? err.message : String(err);
 			ctx.ui.notify(
-				`autostart: skipped — ${message} (${AUTOSTART_CONFIG_PATH})`,
+				`autostart: skipped ${source.label} — ${message} (${source.path})`,
 				"error",
 			);
-			return;
+			return undefined;
 		}
-		if (commands.length === 0) return;
+	}
 
-		if (!ctx.isProjectTrusted()) {
-			ctx.ui.notify(
-				`autostart: skipped — project not trusted (${AUTOSTART_CONFIG_PATH})`,
-				"warning",
-			);
-			return;
-		}
+	pi.on("session_start", async (event, ctx) => {
+		if (!RUNNABLE_REASONS.has(event.reason)) return;
+
+		const sources: Source[] = [
+			{
+				path: join(agentDir, GLOBAL_AUTOSTART_FILENAME),
+				label: "global config",
+				requiresTrust: false,
+			},
+			{
+				path: join(ctx.cwd, AUTOSTART_CONFIG_PATH),
+				label: "project config",
+				requiresTrust: true,
+			},
+		];
 
 		// Only extension-registered commands are dispatchable; skill and
 		// prompt-template entries expand rather than execute.
@@ -87,23 +126,36 @@ export function registerAutostart(pi: ExtensionAPI): void {
 				),
 		);
 
-		for (const command of commands) {
-			const name = commandNameOf(command);
-			if (!name || !dispatchable.has(name)) {
+		for (const source of sources) {
+			const commands = await readCommands(ctx, source);
+			if (commands === undefined || commands.length === 0) continue;
+
+			if (source.requiresTrust && !ctx.isProjectTrusted()) {
 				ctx.ui.notify(
-					`autostart: skipped "${command}" — not a registered extension command`,
+					`autostart: skipped ${source.label} — project not trusted (${source.path})`,
 					"warning",
 				);
 				continue;
 			}
-			// One failing command must not cancel the rest of the list.
-			try {
-				await pi.sendUserMessage(command, { expandPromptTemplates: true });
-			} catch (err) {
-				ctx.ui.notify(
-					`autostart: "${command}" failed — ${err instanceof Error ? err.message : String(err)}`,
-					"error",
-				);
+
+			for (const command of commands) {
+				const name = commandNameOf(command);
+				if (!name || !dispatchable.has(name)) {
+					ctx.ui.notify(
+						`autostart: skipped "${command}" — not a registered extension command`,
+						"warning",
+					);
+					continue;
+				}
+				// One failing command must not cancel the rest of the list.
+				try {
+					await pi.sendUserMessage(command, { expandPromptTemplates: true });
+				} catch (err) {
+					ctx.ui.notify(
+						`autostart: "${command}" failed — ${messageOf(err)}`,
+						"error",
+					);
+				}
 			}
 		}
 	});

package/src/features/compact/index.ts

@@ -12,7 +12,7 @@
  *  - prompts, message assembly, split-turn handling, output budgets, and the
  *    summary file-list tail are verbatim pi built-in behavior (copied from
  *    0.87.1, byte-identical across every published version of the supported
- *    window, 0.99.0 → 1.2.0) — only the executing model differs. The one
+ *    window, 1.0.0 → 1.3.0) — only the executing model differs. The one
  *    exception is `serializeConversation`, which is imported from the host
  *    instead of mirrored, so it tracks whatever the running host does
  *    (1.2.0 stopped feeding assistant thinking into the request).
@@ -119,7 +119,7 @@ async function completeSummary(
 }
 
 /**
- * pi's output-budget formula (compaction.js, 0.87.1 → 1.2.0 unchanged): a
+ * pi's output-budget formula (compaction.js, 0.87.1 → 1.3.0 unchanged): a
  * fraction of reserveTokens clamped by the model's own output cap.
  */
 function summarizationBudget(
@@ -136,7 +136,7 @@ function summarizationBudget(
 /**
  * Run the full compaction summarization with the configured model,
  * replicating pi's compact() (0.87.1, byte-identical across the supported
- * 0.99.0 → 1.2.0 window):
+ * 1.0.0 → 1.3.0 window):
  * history summary (first-connection or iterative-update prompt, custom
  * focus appended), plus a separate turn-prefix checkpoint when the cut point
  * splits a turn, merged into one summary with the file-list tail. Returns

package/src/features/compact/prompt.ts

@@ -6,7 +6,7 @@
  * 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 (0.99.0 → 1.2.0): dist/core/compaction/compaction.js and
+ * 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
  * serializeConversation) does not touch the strings mirrored here — that
@@ -203,7 +203,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.2.0): used when
+ * unchanged through 1.3.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

@@ -9,7 +9,7 @@
  * keybinding conflicts arise.
  *
  * Verified against every published version of the supported window
- * (0.99.0 → 1.2.0) keybinding
+ * (1.0.0 → 1.3.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,11 @@ 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.2.0
+ * search and the selector never sees it (verified in pi-tui 1.3.0
  * `dist/tui-alt-screen.js`: the search check is the first key branch and
  * returns `{ consume: true }` unconditionally).
  *
- * Why ctrl+alt+f was discarded: clean at the pi layer across 0.99–1.2 (only
+ * Why ctrl+alt+f was discarded: clean at the pi layer across 1.0–1.3 (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,7 @@
  *    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
- *    0.99.0 → 1.2.0:
+ *    1.0.0 → 1.3.0:
  *    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 +31,9 @@ import { getFavoritesStore, modelKey } from "./store.js";
 
 /**
  * pi's `Model<any>` — the exact type of `ModelCycleResult.model`
- * (pi-coding-agent 0.99–1.2; the field is unchanged across that span).
+ * (pi-coding-agent 1.0–1.3; the field is unchanged across that span).
  * Derived here instead of importing `Model` from @earendil-works/pi-ai,
- * whose index.d.ts (0.99 through 1.2.0 alike) re-exports it via an
+ * whose index.d.ts (1.0 through 1.3.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).
  */
@@ -57,7 +57,7 @@ interface CycleSessionInternals {
 		setDefaultModelAndProvider(provider: string, id: string): void;
 	};
 	/**
-	 * pi 0.99–1.2: keeps a persisted default usable when cycling inside a
+	 * pi 1.0–1.3: keeps a persisted default usable when cycling inside a
 	 * non-empty --models scope.
 	 */
 	_addPersistedDefaultToNonEmptyScope(model: unknown): void;
@@ -140,7 +140,7 @@ export function applyCyclePatch(): boolean {
 			return original.call(this, direction, options);
 		}
 
-		// Same source and availability filtering as pi's stock cycling (0.99–1.2).
+		// Same source and availability filtering as pi's stock cycling (1.0–1.3).
 		const scoped = this._scopedModels.length > 0;
 		let candidates: CycleCandidate[];
 		if (scoped) {
@@ -185,7 +185,7 @@ export function applyCyclePatch(): boolean {
 				: this._getThinkingLevelForModelSwitch();
 		this.agent.state.model = next.model;
 		this.sessionManager.appendModelChange(next.model.provider, next.model.id);
-		// pi 0.99–1.2: only persist the default model when the caller asked for it.
+		// pi 1.0–1.3: only persist the default model when the caller asked for it.
 		if (options.persist) {
 			this.settingsManager.setDefaultModelAndProvider(
 				next.model.provider,

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

@@ -22,7 +22,7 @@
  * 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 0.99.0 → 1.2.0 (and 0.87.0 → 1.1.0 before the floor moved).
+ * pi 1.0.0 → 1.3.0 (and 0.99.0 → 1.2.0 before the floor moved).
  */
 import {
 	ModelSelectorComponent,
@@ -61,7 +61,7 @@ interface SelectorPatchTarget {
 	handleInput(keyData: string): void;
 	updateList(): void;
 	filterModels(query: string): void;
-	/** pi 0.99–1.2: default-model badge source. */
+	/** pi 1.0–1.3: default-model badge source. */
 	isDefaultModel(model: ModelRef): boolean;
 	listContainer: ListContainerLike;
 	searchInput: SearchInputLike;
@@ -116,7 +116,7 @@ let patched = false;
 export function applyModelSelectorPatches(): boolean {
 	if (patched) return true;
 	// SAFETY: ModelSelectorComponent's members are TS-private (compile-time
-	// only); the structural view matches pi 0.99–1.2's prototype shape
+	// only); the structural view matches pi 1.0–1.3's prototype shape
 	// (byte-identical across that span) and every touched method is
 	// existence-checked below before any patching happens.
 	const proto =
@@ -155,7 +155,7 @@ export function applyModelSelectorPatches(): boolean {
 	};
 
 	// ── 2. List rendering: hint row + bold bright yellow favorites ────────
-	// Replicates the built-in updateList layout (pi 0.99–1.2: fixed-width cursor
+	// Replicates the built-in updateList layout (pi 1.0–1.3: fixed-width cursor
 	// and ✓ current-marker columns, provider badge, `· default` badge, scroll
 	// indicator, empty/error states, refresh status, Model Name footer) with
 	// one change: favorited model ids render in the favorite style.

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

@@ -0,0 +1,60 @@
+/**
+ * Fixed safety tables: credential paths are denied in every mode, destructive
+ * commands always ask.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { dangerReason, secretReason } from "./constants.js";
+
+const HOME = homedir();
+
+describe("secrets table", () => {
+	it("covers the credential directories exactly", () => {
+		expect(secretReason(join(HOME, ".ssh", "id_rsa"))).toBe("credentials");
+		expect(secretReason(join(HOME, ".ssh"))).toBe("credentials");
+		expect(secretReason(join(HOME, ".gnupg", "private-keys-v1.d"))).toBe("credentials");
+		expect(secretReason(join(HOME, ".aws", "credentials"))).toBe("credentials");
+	});
+
+	it("does not over-match a sibling prefix", () => {
+		expect(secretReason(join(HOME, ".ssh-easy", "x"))).toBeUndefined();
+		expect(secretReason(join(HOME, ".ssh_evil", "x"))).toBeUndefined();
+		expect(secretReason(join(HOME, ".awsconfig", "x"))).toBeUndefined();
+	});
+
+	it("covers pi auth files but nothing else under the agent dir", () => {
+		expect(secretReason(join(HOME, ".pi", "agent", "auth.json"))).toBe("pi credentials");
+		expect(secretReason(join(HOME, ".pi", "agent", "auth-foo.json"))).toBe("pi credentials");
+		expect(secretReason(join(HOME, ".pi", "agent", "settings.json"))).toBeUndefined();
+		expect(secretReason(join(HOME, ".pi", "agent", "xauth", "auth.json"))).toBeUndefined();
+	});
+
+	it("covers .env files but not the templates", () => {
+		expect(secretReason("/proj/.env")).toBe("environment file");
+		expect(secretReason("/proj/.env.local")).toBe("environment file");
+		expect(secretReason("/proj/.env.example")).toBeUndefined();
+	});
+});
+
+describe("danger table", () => {
+	it("catches the destructive core", () => {
+		expect(dangerReason("rm", ["-rf", "/"], ["/"], "/proj")).toContain("recursive delete");
+		expect(dangerReason("rm", ["-rf", HOME], [HOME], "/proj")).toContain("recursive delete");
+		expect(dangerReason("rm", ["-rf", "/proj"], ["/proj"], "/proj")).toContain("recursive delete");
+		expect(dangerReason("git", ["push", "--force"], [], "/proj")).toBe("forced git push");
+		expect(dangerReason("git", ["push", "-f"], [], "/proj")).toBe("forced git push");
+		expect(dangerReason("git", ["reset", "--hard"], [], "/proj")).toBe("git reset --hard");
+		expect(dangerReason("git", ["clean", "-fd"], [], "/proj")).toBe("git clean -f");
+		expect(dangerReason("npm", ["publish"], [], "/proj")).toBe("package publish");
+		expect(dangerReason("dd", ["of=/dev/sda"], ["/dev/sda"], "/proj")).toBe("raw device write");
+		expect(dangerReason("sudo", ["rm", "x"], ["/proj/x"], "/proj")).toBe("privileged command");
+	});
+
+	it("does not flag ordinary commands", () => {
+		expect(dangerReason("rm", ["-rf", "/proj/build"], ["/proj/build"], "/proj")).toBeUndefined();
+		expect(dangerReason("git", ["push"], [], "/proj")).toBeUndefined();
+		expect(dangerReason("git", ["log"], [], "/proj")).toBeUndefined();
+		expect(dangerReason("npm", ["view", "react"], [], "/proj")).toBeUndefined();
+	});
+});