@andares/pi-toolkits 0.4.3 → 0.6.0

package/README.md

@@ -8,13 +8,13 @@
 [![npm version](https://img.shields.io/npm/v/@andares/pi-toolkits?label=npm&logo=npm)](https://www.npmjs.com/package/@andares/pi-toolkits)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Package Manager](https://img.shields.io/badge/package%20manager-pnpm-orange?logo=pnpm)](https://pnpm.io)
-[![pi >= 0.87](https://img.shields.io/badge/pi-%3E%3D0.87.0-blueviolet)](https://github.com/earendil-works/pi)
+[![pi >= 0.86](https://img.shields.io/badge/pi-%3E%3D0.86.0%20%3C2.0.0-blueviolet)](https://github.com/earendil-works/pi)
 [![GitHub](https://img.shields.io/badge/github-andares%2Fpi--toolkits-181717?logo=github)](https://github.com/andares/pi-toolkits)
 
 一句话介绍:目前包含五个开箱即用的功能——**只读咨询模式** `ask`、**模型收藏** `favorites`、**提示词暂存** `stash`、**第三方代码评审** `third-review`、**独立压缩模型** `compact-model`,后续持续追加。
 Currently ships five ready-to-use capabilities — **ask mode**, **model favorites**, **prompt stash**, **third-party code review** and a **dedicated compaction model** — with more to come.
 
-**版本要求 · Requirements**:pi ≥ 0.87.0(以 0.87.x 内建压缩行为为基准开发与验证;favorites 的两处运行时 patch 已对齐 0.87 的选择器布局与 `cycleModel` 语义)。
+**版本要求 · Requirements**:pi `>=0.86.0 <2.0.0`(覆盖最近 4 个中版本线 0.86.x / 0.87.x / 0.99.x / 1.0.x —— 0.88–0.98 从未发布。区间内全部 10 个已发布版本逐版本比对宿主 dist:用到的扩展 API 无差异,favorites 两处运行时 patch 目标 `ModelSelectorComponent` / `AgentSession.cycleModel` 字节级一致;并在 0.86.0、0.86.1、0.87.1、0.99.2、1.0.2 上逐一通过 typecheck + 全量测试,在真实 pi 1.0.2 上冒烟加载无警告)。注:pi ≥ 0.99 的宿主要求 `@earendil-works/pi-tui` 声明为 peerDependencies `"*"`(由宿主提供),本包已按要求声明。
 
 ---
 
@@ -52,6 +52,7 @@ pi -e ./src/index.ts
   - [📥 stash — 提示词暂存](#stash)
   - [🔎 review — 第三方代码评审](#review)
   - [🗜️ compact — 独立压缩模型](#compact)
+  - [🚀 autostart — 会话启动自动化](#autostart)
 - [开发 Development](#development)
 - [贡献 Contributing](#contributing)
 - [许可 License](#license)
@@ -69,6 +70,7 @@ pi -e ./src/index.ts
 | 📥 **stash** 提示词暂存 | `ctrl+alt+y` | 一段提示词的暂存槽,按键交换 / 连按两次暂存并清空输入框 |
 | 🔎 **review** 第三方代码评审 | `/third-review` | 召唤配置的评审模型,对刚完成的任务做查+修,重点检查「本轮需求实现 / 是否有遗漏 / 是否有错误」 |
 | 🗜️ **compact** 独立压缩模型 | `/compact-model` | 给 `/compact` 与 auto-compact 配一个便宜快模型做总结,主模型专注对话;未配置零开销、任何异常回落 pi 默认 |
+| 🚀 **autostart** 会话启动自动化 | `.pi/autostart.toml` | 项目内声明启动时自动执行的斜杠命令(首批用例:`/add-dir` 多仓库挂载);未信任不执行、未注册命令跳过不发给模型 |
 
 ---
 
@@ -191,7 +193,7 @@ pi 的 `/compact` 与 auto-compact 默认**用当前会话模型**做上下文
 | auto-compact 阈值触发 | 压缩模型总结 |
 | context overflow 恢复 | 压缩模型总结,重试行为不变 |
 
-**接管后与 pi 内建行为完全一致的部分**(逐字同步 0.87.1 内建实现,只换执行模型):
+**接管后与 pi 内建行为完全一致的部分**(逐字同步 pi 内建实现,0.87.1 起字节级不变、已核对至 1.0.2,只换执行模型):
 
 - **摘要格式** —— Goal / Progress / Key Decisions 结构化 checkpoint;已有摘要时用迭代更新版 prompt,信息延续不丢
 - **切分行为** —— 保留最近 `keepRecentTokens` 的策略、`firstKeptEntryId` / `tokensBefore` 原样回传,不动
@@ -222,6 +224,46 @@ pi 的 `/compact` 与 auto-compact 默认**用当前会话模型**做上下文
 
 ---
 
+## 🚀 autostart — 会话启动自动化
+
+<a name="autostart"></a>
+
+多仓库项目的第一步:在项目内声明「开新会话时要自动执行的斜杠命令」,首批用例是 `/add-dir` 挂载兄弟仓库——新会话无需手动重放。
+
+**配置**(`<项目根>/.pi/autostart.toml`,随项目进 git;`.pi/` 是 pi 的项目级配置惯例,先例 `.pi/mcp.json`):
+
+```toml
+version = 1
+
+[command]
+run = [
+  "/add-dir ../shop-frontend",
+  "/add-dir ../shop-api",
+]
+```
+
+无文件 = 功能未启用,零开销、静默跳过。
+
+**执行时机**:
+
+| session_start reason | 是否重放 | 原因 |
+| --- | --- | --- |
+| `startup` / `new` | ✅ | 新会话,按声明重放 |
+| `fork` | ✅ | 分支点可能早于配置出现 |
+| `resume` | ❌ | 恢复的分支已携带当时的挂载状态,重放反而会冲突 |
+| `reload` | ❌ | 扩展重建,重放会重复副作用 |
+
+**安全门**(按序):
+
+1. **project trust** —— 未信任目录不自动执行任何命令(warning 提示);配置解析失败同样不执行(error 提示)
+2. **命令预校验** —— 只执行「扩展注册的命令」;未注册的命令名**跳过并警告**,绝不发给模型(sendUserMessage 对未处理的 `/x` 会当作普通消息发给 LLM,这是必须预校验的原因)
+
+**关键约束:只支持扩展命令**。`/add-dir`(pi-add-dir)、`/cd`(pi-cd)等 `registerCommand` 注册的命令可以;内置命令(`/compact`、`/reload`、`/resume`…)在 TUI 层分发,扩展层触发不了;skill 命令(`/skill:name`)是展开机制而非执行机制。依赖的目标扩展(如 pi-add-dir)需要先安装。
+
+> **实现说明**:执行用 `sendUserMessage(cmd, { expandPromptTemplates: true })` —— 该选项把 `/cmd args` 路由到命令分发而不是模型 prompt 路径(包装层默认 `false`,已对照 pi 0.86–1.0.4 源码核实,见 AGENTS.md 宿主兼容纪律)。预校验用 `pi.getCommands()`(只认 `source: "extension"`)。依赖 `smol-toml`(零依赖、~10KB、TOML 1.0)。
+
+---
+
 ## 🛠️ 开发 Development
 
 <a name="development"></a>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andares/pi-toolkits",
-  "version": "0.4.3",
+  "version": "0.6.0",
   "description": "Integrated toolkit extension for pi — ask mode (read-only Q&A), model favorites, prompt stash, third-party code review, and a dedicated compaction model",
   "type": "module",
   "license": "MIT",
@@ -24,18 +24,21 @@
     "code-review",
     "compaction",
     "compact-model",
-    "toolkit"
+    "toolkit",
+    "autostart"
   ],
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*"
+    "@earendil-works/pi-coding-agent": ">=0.86.0 <2.0.0",
+    "@earendil-works/pi-tui": "*"
   },
   "dependencies": {
     "@dreki-gg/pi-command-sandbox": "^0.4.3",
-    "@earendil-works/pi-tui": "^0.87.1"
+    "smol-toml": "^1.9.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.87.1",
-    "@earendil-works/pi-coding-agent": "^0.87.1",
+    "@earendil-works/pi-ai": "^1.0.2",
+    "@earendil-works/pi-coding-agent": "^1.0.2",
+    "@earendil-works/pi-tui": "^1.0.2",
     "@types/node": "^26.6.2",
     "typescript": "^5.6.0",
     "vitest": "^4.1.10"

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

@@ -0,0 +1,315 @@
+/**
+ * autostart feature tests.
+ *
+ * Pure-logic coverage for parseAutostartConfig / commandNameOf, plus an
+ * integration pass over registerAutostart with a minimal mock of the pi
+ * extension surface (on/getCommands/sendUserMessage) and ExtensionContext
+ * (cwd/isProjectTrusted/ui.notify), using a temp directory for the config
+ * file.
+ */
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	AUTOSTART_CONFIG_PATH,
+	AutostartParseError,
+	commandNameOf,
+	parseAutostartConfig,
+	RUNNABLE_REASONS,
+} from "./autostart.js";
+import { registerAutostart } from "./index.js";
+
+describe("parseAutostartConfig", () => {
+	it("parses a full config into the ordered command list", () => {
+		const text = [
+			"# project autostart",
+			"version = 1",
+			"",
+			"[command]",
+			'run = ["/add-dir ../shop-frontend", "/add-dir ../shop-api"]',
+		].join("\n");
+		expect(parseAutostartConfig(text)).toEqual([
+			"/add-dir ../shop-frontend",
+			"/add-dir ../shop-api",
+		]);
+	});
+
+	it("accepts a config without version (defaults to 1)", () => {
+		expect(parseAutostartConfig('[command]\nrun = ["/ask on"]')).toEqual([
+			"/ask on",
+		]);
+	});
+
+	it("returns empty for a config without [command] or run", () => {
+		expect(parseAutostartConfig("version = 1")).toEqual([]);
+		expect(parseAutostartConfig("[command]\n")).toEqual([]);
+	});
+
+	it("drops blank entries", () => {
+		expect(
+			parseAutostartConfig('[command]\nrun = ["/ask on", "  "]'),
+		).toEqual(["/ask on"]);
+	});
+
+	it("rejects [[command]] array tables instead of ignoring them", () => {
+		expect(() =>
+			parseAutostartConfig('[[command]]\nrun = ["/ask on"]'),
+		).toThrow(AutostartParseError);
+	});
+
+	it("normalizes whitespace out of commands", () => {
+		expect(
+			parseAutostartConfig('[command]\nrun = ["  /add-dir ../x  "]'),
+		).toEqual(["/add-dir ../x"]);
+	});
+
+	it("rejects version != 1", () => {
+		expect(() =>
+			parseAutostartConfig("version = 2\n[command]\nrun = []"),
+		).toThrow(AutostartParseError);
+	});
+
+	it("rejects invalid TOML", () => {
+		expect(() => parseAutostartConfig("[command\nrun = [")).toThrow(
+			AutostartParseError,
+		);
+	});
+
+	it("rejects [command].run that is not a string array", () => {
+		expect(() => parseAutostartConfig('[command]\nrun = "/ask on"')).toThrow(
+			AutostartParseError,
+		);
+		expect(() => parseAutostartConfig("[command]\nrun = [1, 2]")).toThrow(
+			AutostartParseError,
+		);
+	});
+});
+
+describe("commandNameOf", () => {
+	it("extracts the command name from a slash command with args", () => {
+		expect(commandNameOf("/add-dir ../shop-frontend")).toBe("add-dir");
+	});
+	it("tolerates missing slash, extra whitespace, and bare command", () => {
+		expect(commandNameOf("add-dir ../x")).toBe("add-dir");
+		expect(commandNameOf("  /add-dir   ../x  ")).toBe("add-dir");
+		expect(commandNameOf("/ask")).toBe("ask");
+	});
+	it("returns empty for blank input", () => {
+		expect(commandNameOf("   ")).toBe("");
+	});
+});
+
+describe("RUNNABLE_REASONS", () => {
+	it("replays startup/new/fork and not resume/reload", () => {
+		expect(RUNNABLE_REASONS.has("startup")).toBe(true);
+		expect(RUNNABLE_REASONS.has("new")).toBe(true);
+		expect(RUNNABLE_REASONS.has("fork")).toBe(true);
+		expect(RUNNABLE_REASONS.has("resume")).toBe(false);
+		expect(RUNNABLE_REASONS.has("reload")).toBe(false);
+	});
+});
+
+/* ------------------------------------------------------------------ */
+/* registerAutostart integration (mocked pi surface)                   */
+/* ------------------------------------------------------------------ */
+
+type SessionStartHandler = (
+	event: { reason: string },
+	ctx: {
+		cwd: string;
+		isProjectTrusted: () => boolean;
+		ui: { notify: (message: string, type?: string) => void };
+	},
+) => Promise<void>;
+
+interface Harness {
+	cwd: string;
+	handler: SessionStartHandler;
+	sent: Array<{ command: string; options?: { expandPromptTemplates?: boolean } }>;
+	notifications: Array<{ message: string; type?: string }>;
+	commands: Array<{ name: string; source: string }>;
+	failCommands: Set<string>;
+	setTrusted(trusted: boolean): void;
+	start(reason: string): Promise<void>;
+}
+
+async function makeHarness(
+	config: string | null,
+	configAsDir = false,
+): Promise<Harness> {
+	const cwd = await mkdtemp(join(tmpdir(), "pi-autostart-test-"));
+	if (configAsDir) {
+		// EISDIR setup: the config path exists but is a directory.
+		await mkdir(join(cwd, ".pi"), { recursive: true });
+		await mkdir(join(cwd, AUTOSTART_CONFIG_PATH));
+	} else if (config !== null) {
+		await mkdir(join(cwd, ".pi"), { recursive: true });
+		await writeFile(join(cwd, AUTOSTART_CONFIG_PATH), config, "utf8");
+	}
+	let trusted = true;
+	let handler: SessionStartHandler = async () => {};
+	const sent: Harness["sent"] = [];
+	const notifications: Harness["notifications"] = [];
+	const commands: Harness["commands"] = [
+		{ name: "add-dir", source: "extension" },
+		{ name: "ask", source: "extension" },
+	];
+	const failCommands = new Set<string>();
+	const pi = {
+		on: (event: string, h: SessionStartHandler) => {
+			if (event === "session_start") handler = h;
+		},
+		getCommands: () => commands,
+		sendUserMessage: (
+			command: string,
+			options?: { expandPromptTemplates?: boolean },
+		) => {
+			sent.push({ command, options }); // records attempts, including failures
+			if (failCommands.has(command)) {
+				return Promise.reject(new Error("boom"));
+			}
+		},
+	} as unknown as ExtensionAPI;
+	registerAutostart(pi);
+	return {
+		handler,
+		sent,
+		notifications,
+		commands,
+		failCommands,
+		setTrusted(value: boolean) {
+			trusted = value;
+		},
+		async start(reason: string) {
+			await handler({ reason }, {
+				cwd,
+				isProjectTrusted: () => trusted,
+				ui: {
+					notify: (message: string, type?: string) => {
+						notifications.push({ message, type });
+					},
+				},
+			});
+		},
+		cwd,
+	};
+}
+
+let current: Harness | undefined;
+
+afterEach(async () => {
+	if (current) {
+		await rm(current.cwd, { recursive: true, force: true });
+		current = undefined;
+	}
+});
+
+async function harness(
+	config: string | null,
+	configAsDir = false,
+): Promise<Harness> {
+	const h = await makeHarness(config, configAsDir);
+	current = h;
+	return h;
+}
+
+describe("registerAutostart", () => {
+	const fullConfig =
+		'version = 1\n[command]\nrun = ["/add-dir ../frontend", "/add-dir ../api"]';
+
+	it("dispatches configured commands with expandPromptTemplates on startup", async () => {
+		const h = await harness(fullConfig);
+		await h.start("startup");
+		expect(h.sent).toEqual([
+			{ command: "/add-dir ../frontend", options: { expandPromptTemplates: true } },
+			{ command: "/add-dir ../api", options: { expandPromptTemplates: true } },
+		]);
+		expect(h.notifications).toEqual([]);
+	});
+
+	it("reports parse errors and dispatches nothing", async () => {
+		const h = await harness("/[command]\nrun = [");
+		await h.start("startup");
+		expect(h.sent).toEqual([]);
+		expect(h.notifications).toHaveLength(1);
+		expect(h.notifications[0]?.type).toBe("error");
+	});
+
+	it("replays on new and fork", async () => {
+		const h = await harness('[command]\nrun = ["/ask on"]');
+		await h.start("new");
+		await h.start("fork");
+		expect(h.sent).toEqual([
+			{ command: "/ask on", options: { expandPromptTemplates: true } },
+			{ command: "/ask on", options: { expandPromptTemplates: true } },
+		]);
+		expect(h.notifications).toEqual([]);
+	});
+
+	it("does nothing on resume or reload", async () => {
+		const h = await harness(fullConfig);
+		await h.start("resume");
+		await h.start("reload");
+		expect(h.sent).toEqual([]);
+		expect(h.notifications).toEqual([]);
+	});
+
+	it("silently skips when no config file exists", async () => {
+		const h = await harness(null);
+		await h.start("startup");
+		expect(h.sent).toEqual([]);
+		expect(h.notifications).toEqual([]);
+	});
+
+	it("skips everything when the project is not trusted", async () => {
+		const h = await harness(fullConfig);
+		h.setTrusted(false);
+		await h.start("startup");
+		expect(h.sent).toEqual([]);
+		expect(h.notifications).toHaveLength(1);
+		expect(h.notifications[0]?.type).toBe("warning");
+	});
+
+	it("skips unregistered commands instead of sending them to the model", async () => {
+		const h = await harness(
+			'[command]\nrun = ["/add-dir ../x", "/not-a-command y"]',
+		);
+		await h.start("startup");
+		expect(h.sent).toEqual([
+			{ command: "/add-dir ../x", options: { expandPromptTemplates: true } },
+		]);
+		expect(h.notifications).toHaveLength(1);
+		expect(h.notifications[0]?.type).toBe("warning");
+	});
+
+	it("skips commands only registered as skill or prompt sources", async () => {
+		const h = await harness('[command]\nrun = ["/add-dir ../x"]');
+		h.commands.length = 0;
+		h.commands.push({ name: "add-dir", source: "skill" });
+		await h.start("startup");
+		expect(h.sent).toEqual([]);
+		expect(h.notifications).toHaveLength(1);
+	});
+
+	it("warns when the config path cannot be read for a reason other than ENOENT", async () => {
+		const h = await harness(null, true); // .pi/autostart.toml is a directory → EISDIR
+		await h.start("startup");
+		expect(h.sent).toEqual([]);
+		expect(h.notifications).toHaveLength(1);
+		expect(h.notifications[0]?.type).toBe("warning");
+	});
+
+	it("keeps dispatching after one command fails", async () => {
+		const h = await harness(fullConfig);
+		h.failCommands.add("/add-dir ../frontend");
+		await h.start("startup");
+		expect(h.sent.map((entry) => entry.command)).toEqual([
+			"/add-dir ../frontend",
+			"/add-dir ../api",
+		]);
+		expect(h.notifications).toHaveLength(1);
+		expect(h.notifications[0]?.type).toBe("error");
+	});
+});

package/src/features/autostart/autostart.ts

@@ -0,0 +1,108 @@
+/**
+ * autostart feature — pure config logic, no pi imports.
+ *
+ * Schema (`.pi/autostart.toml`, checked into the project):
+ *
+ * ```toml
+ * version = 1
+ *
+ * [command]
+ * run = [
+ *   "/add-dir ../shop-frontend",
+ *   "/add-dir ../shop-api",
+ * ]
+ * ```
+ *
+ * `version` is optional (defaults to 1) but must be 1 when present, so a
+ * future schema change can fail loudly instead of silently misreading.
+ */
+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`). */
+export const AUTOSTART_CONFIG_PATH = ".pi/autostart.toml";
+
+/**
+ * session_start reasons that replay autostart commands:
+ *  - startup / new: fresh session in the project — replay
+ *  - fork: new branch of an earlier session — replay (the fork point may
+ *    predate the config)
+ *  - resume: the resumed branch already carries its /add-dir state —
+ *    replaying would at best duplicate work (pi-add-dir is idempotent) and
+ *    at worst re-add directories the user removed on that branch
+ *  - reload: extensions are being rebuilt — re-running commands would
+ *    duplicate side effects from the same session
+ */
+export const RUNNABLE_REASONS: ReadonlySet<string> = new Set([
+	"startup",
+	"new",
+	"fork",
+]);
+
+/** Parse/validation failure with a user-facing message. */
+export class AutostartParseError extends Error {}
+
+function errMessage(err: unknown): string {
+	return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * Parse autostart config text into the ordered command list.
+ * @throws AutostartParseError on invalid TOML, wrong shape, or version ≠ 1.
+ */
+export function parseAutostartConfig(text: string): string[] {
+	let doc: unknown;
+	try {
+		doc = parseToml(text);
+	} catch (err) {
+		throw new AutostartParseError(`invalid TOML: ${errMessage(err)}`);
+	}
+	if (doc === null || typeof doc !== "object" || Array.isArray(doc)) {
+		throw new AutostartParseError("top-level value must be a table");
+	}
+	const { version, command } = doc as {
+		version?: unknown;
+		command?: unknown;
+	};
+	if (version !== undefined && version !== 1) {
+		throw new AutostartParseError(
+			`unsupported version ${String(version)} (expected 1)`,
+		);
+	}
+	if (command === undefined) return [];
+	if (Array.isArray(command)) {
+		throw new AutostartParseError(
+			"[[command]] array tables are not supported — use a single [command] table with a run array",
+		);
+	}
+	if (command === null || typeof command !== "object") {
+		throw new AutostartParseError("[command] must be a table");
+	}
+	const run = (command as { run?: unknown }).run;
+	if (run === undefined) return [];
+	if (
+		!Array.isArray(run) ||
+		run.some((entry) => typeof entry !== "string")
+	) {
+		throw new AutostartParseError(
+			"[command].run must be an array of command strings",
+		);
+	}
+	// Trim each entry: `prompt()` dispatches a command only when the text
+	// literally starts with "/", so a leading-space entry would silently fall
+	// through to the model as a plain message. Normalizing here keeps the
+	// "never sent to the model" guarantee (see index.ts).
+	return (run as string[])
+		.map((cmd) => cmd.trim())
+		.filter((cmd) => cmd !== "");
+}
+
+/**
+ * Extract the command name a slash command dispatches to:
+ * `"/add-dir ../x"` → `"add-dir"`, tolerant of leading whitespace and an
+ * optional slash. Empty for blank input.
+ */
+export function commandNameOf(command: string): string {
+	const stripped = command.trim().replace(/^\//, "");
+	return stripped.split(/\s+/)[0] ?? "";
+}

package/src/features/autostart/index.ts

@@ -0,0 +1,109 @@
+/**
+ * autostart feature — run project-declared slash commands at session start.
+ *
+ * Config lives at `<project root>/.pi/autostart.toml` (see autostart.ts for
+ * the schema). Execution gates, in order:
+ *
+ *  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.
+ *
+ * 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
+ * (verified against pi 1.0.4 agent-session.js; 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).
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	AUTOSTART_CONFIG_PATH,
+	AutostartParseError,
+	commandNameOf,
+	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;
+
+		let text: string;
+		try {
+			text = await readFile(join(ctx.cwd, AUTOSTART_CONFIG_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)}`,
+					"warning",
+				);
+			}
+			return;
+		}
+
+		let commands: string[];
+		try {
+			commands = parseAutostartConfig(text);
+		} catch (err) {
+			const message = err instanceof AutostartParseError ? err.message : String(err);
+			ctx.ui.notify(
+				`autostart: skipped — ${message} (${AUTOSTART_CONFIG_PATH})`,
+				"error",
+			);
+			return;
+		}
+		if (commands.length === 0) return;
+
+		if (!ctx.isProjectTrusted()) {
+			ctx.ui.notify(
+				`autostart: skipped — project not trusted (${AUTOSTART_CONFIG_PATH})`,
+				"warning",
+			);
+			return;
+		}
+
+		// Only extension-registered commands are dispatchable; skill and
+		// prompt-template entries expand rather than execute.
+		const dispatchable = new Set(
+			pi
+				.getCommands()
+				.flatMap((cmd) =>
+					cmd.source === "extension" ? [cmd.name.replace(/^\//, "")] : [],
+				),
+		);
+
+		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 — ${err instanceof Error ? err.message : String(err)}`,
+					"error",
+				);
+			}
+		}
+	});
+}

package/src/features/compact/index.ts

@@ -10,8 +10,9 @@
  *    emits for ALL three trigger reasons (manual / threshold / overflow)
  *    before running its own compaction
  *  - prompts, message assembly, split-turn handling, output budgets, and the
- *    summary file-list tail are verbatim pi 0.87.1 built-in behavior — only
- *    the executing model differs
+ *    summary file-list tail are verbatim pi built-in behavior (copied from
+ *    0.87.1, verified unchanged through 1.0.2) — only the executing model
+ *    differs
  *  - lossless fallback: unset config, unavailable model, empty/failed
  *    summary, or user abort → return undefined and pi's default compaction
  *    (session model) runs untouched. The extension can never make
@@ -115,8 +116,8 @@ async function completeSummary(
 }
 
 /**
- * pi's output-budget formula (0.87.1 compaction.js): a fraction of
- * reserveTokens clamped by the model's own output cap.
+ * pi's output-budget formula (compaction.js, 0.87.1 → 1.0.2 unchanged): a
+ * fraction of reserveTokens clamped by the model's own output cap.
  */
 function summarizationBudget(
 	fraction: number,
@@ -131,11 +132,12 @@ function summarizationBudget(
 
 /**
  * Run the full compaction summarization with the configured model,
- * replicating pi 0.87.1's compact(): 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 undefined on any failure after
- * notifying (pi default compaction then takes over).
+ * replicating pi's compact() (0.87.1, verified unchanged through 1.0.2):
+ * 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
+ * undefined on any failure after notifying (pi default compaction then takes
+ * over).
  */
 async function runCompactModelCompaction(
 	ctx: ExtensionContext,

package/src/features/compact/prompt.ts

@@ -5,6 +5,9 @@
  * compaction (dist/core/compaction/compaction.js and utils.js) so that
  * 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 pi 1.0.2 (0.88–0.98 were never published;
+ * the only 0.87.1→1.0.2 change there is a combineUsage refactor into a
+ * shared module, no prompt or budget change).
  *
  * Update these strings whenever pi changes its built-in prompts (diff
  * dist/core/compaction/compaction.js between versions).

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

@@ -13,8 +13,9 @@
  *    favorite, backward to the last (user-confirmed)
  *  - with exactly one favorite, already on it → undefined (stock "only one
  *    model available" feedback); otherwise jump to it
- *  - the apply logic mirrors pi 0.87's _cycleScopedModel/_cycleAvailableModel
- *    (state swap, session persistence, default-model persistence only when
+ *  - the apply logic mirrors pi's _cycleScopedModel/_cycleAvailableModel
+ *    (byte-identical across every published version in 0.86.0 → 1.0.2:
+ *    state swap, session persistence, default-model persistence only when
  *    `options.persist` is set, thinking-level re-clamp, model_select emit
  *    with source "cycle")
  *
@@ -28,9 +29,10 @@ import {
 import { getFavoritesStore, modelKey } from "./store.js";
 
 /**
- * pi's `Model<any>` — the exact type of `ModelCycleResult.model` in
- * pi-coding-agent 0.87. Derived here instead of importing `Model` from
- * @earendil-works/pi-ai, whose 0.87 index.d.ts re-exports it via an
+ * pi's `Model<any>` — the exact type of `ModelCycleResult.model`
+ * (pi-coding-agent 0.86–1.0; the field is unchanged across that span).
+ * Derived here instead of importing `Model` from @earendil-works/pi-ai,
+ * whose index.d.ts (0.86 through 1.0.2 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

@@ -19,7 +19,10 @@
  *
  * Version guard: if the prototype no longer has the expected methods (pi
  * upgraded internals), patches are skipped with a warning — the extension
- * keeps loading and ctrl+p falls back to stock behavior.
+ * 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.86.0 → 1.0.2.
  */
 import {
 	ModelSelectorComponent,
@@ -113,8 +116,9 @@ 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.87's prototype shape and every
-	// touched method is existence-checked below before any patching happens.
+	// only); the structural view matches pi 0.86–1.0's prototype shape
+	// (byte-identical across that span) and every touched method is
+	// existence-checked below before any patching happens.
 	const proto =
 		ModelSelectorComponent.prototype as unknown as SelectorPatchTarget;
 	if (
@@ -151,7 +155,7 @@ export function applyModelSelectorPatches(): boolean {
 	};
 
 	// ── 2. List rendering: hint row + bold bright yellow favorites ────────
-	// Replicates the built-in updateList layout (pi 0.87: fixed-width cursor
+	// Replicates the built-in updateList layout (pi 0.86–1.0: 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/index.ts

@@ -10,9 +10,11 @@
  *  - stash — prompt stash (ctrl+alt+y swap / double-press stash-and-clear)
  *  - 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)
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 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 { registerReview } from "./features/review/index.js";
@@ -20,6 +22,7 @@ import { registerStash } from "./features/stash/index.js";
 
 export default function piToolkits(pi: ExtensionAPI): void {
 	registerAsk(pi);
+	registerAutostart(pi);
 	registerCompact(pi);
 	registerFavorites(pi);
 	registerReview(pi);

package/src/lib/model-config.ts

@@ -4,11 +4,12 @@
  * (review, compact-model — favorites keeps its own store-local key logic).
  *
  * Types are derived from pi-coding-agent's own exports (ModelRegistry)
- * rather than imported from @earendil-works/pi-ai: pi-ai 0.87's index.d.ts
- * re-exports `Model`/`Api` via extensioned `./types.ts` specifiers, which
- * tsc 5.9 bundler resolution substitutes to `.d.ts` but some tsserver
- * builds do not. Deriving from ModelRegistry keeps every resolver in
- * agreement with the exact type `ctx.modelRegistry.getAvailable()` returns.
+ * rather than imported from @earendil-works/pi-ai: pi-ai's index.d.ts (0.87
+ * through 1.0.2 alike) re-exports `Model`/`Api` via extensioned
+ * `./types.ts` specifiers, which tsc 5.9 bundler resolution substitutes to
+ * `.d.ts` but some tsserver builds do not. Deriving from ModelRegistry keeps
+ * every resolver in agreement with the exact type
+ * `ctx.modelRegistry.getAvailable()` returns.
  */
 import type {
 	ExtensionContext,

package/src/lib/model-picker.ts

@@ -9,10 +9,11 @@
  *
  * The component is driven through a small ModelRuntime facade backed by
  * ctx.modelRegistry (pi's extension-facing wrapper). SAFETY: verified
- * against pi 0.87.1 dist (modes/interactive/components/model-selector.js +
- * model-catalog-refresh.js) — the component only calls getAvailableSnapshot,
- * getModel, getError and refresh on modelRuntime, and ModelRegistry provides
- * exactly those (getAvailable/find/getError/refresh).
+ * against pi 0.86–1.0 dist (modes/interactive/components/model-selector.js +
+ * model-catalog-refresh.js — byte-identical across that span) — the
+ * component only calls getAvailableSnapshot, getModel, getError and refresh
+ * on modelRuntime, and ModelRegistry provides exactly those
+ * (getAvailable/find/getError/refresh).
  *
  * `current` is passed as the component's currentModel: the built-in selector
  * preselects, ✓-marks and sorts-first its currentModel, so one Enter accepts
@@ -41,7 +42,7 @@ function modelRuntimeFacade(ctx: ExtensionContext): ModelRuntime {
 		refresh: (options?: { signal?: AbortSignal }) =>
 			ctx.modelRegistry.refresh(options),
 	};
-	// SAFETY: the selector only touches the four members above (pi 0.87.1
+	// SAFETY: the selector only touches the four members above (pi 0.86–1.0
 	// model-selector.js); everything else on ModelRuntime is never reached
 	// from this component.
 	return facade as unknown as ModelRuntime;