@andares/pi-toolkits 0.9.0 → 0.9.1

package/README.md

@@ -311,11 +311,14 @@ The global list runs first, so a project can override an earlier setting (for ex
 
 | session_start reason | Replayed | Why |
 | --- | --- | --- |
-| `startup` / `new` | ✅ | a new session, replay as declared |
-| `fork` | ✅ | the branch point may predate the config's appearance |
-| `resume` | ❌ | the restored branch already carries the mount state from its time, replaying would conflict |
+| `startup` / `new`, empty session | ✅ | a new session, replay as declared |
+| `startup` on a session that already has history | ❌ | that is a process started on an existing session (`pi -c` / `-r` / `--session` / `--fork`), and its branch already carries the state a replay would rebuild |
+| `fork` (in-process) | ✅ | the branch point may predate the config's appearance |
+| `resume` (in-process `/resume`) | ❌ | the restored branch already carries the mount state from its time, replaying would conflict |
 | `reload` | ❌ | extensions are rebuilt, replaying would duplicate side effects |
 
+> The `startup` split is not cosmetic: pi reports `startup` for **every** process start, including one that opens an existing session. `resume` is emitted only for in-process session switches, never for `pi -c`. Lines 1–2 of the table are therefore decided by the session's content (does it already hold a message?), not by the reason alone.
+
 **Safety gates** (in order):
 
 1. **project trust** — no command runs automatically in an untrusted directory (a warning is shown); a config parse failure likewise prevents execution (an error is shown)

package/README.zh-CN.md

@@ -311,11 +311,14 @@ run = [
 
 | session_start reason | 是否重放 | 原因 |
 | --- | --- | --- |
-| `startup` / `new` | ✅ | 新会话,按声明重放 |
-| `fork` | ✅ | 分支点可能早于配置出现 |
-| `resume` | ❌ | 恢复的分支已携带当时的挂载状态,重放反而会冲突 |
+| `startup` / `new`,空会话 | ✅ | 新会话,按声明重放 |
+| `startup`,但会话已有历史 | ❌ | 这是「进程启动即带着旧会话」(`pi -c` / `-r` / `--session` / `--fork`),其分支已携带重放本该重建的状态 |
+| `fork`(进程内) | ✅ | 分支点可能早于配置出现 |
+| `resume`(进程内 `/resume`) | ❌ | 恢复的分支已携带当时的挂载状态,重放反而会冲突 |
 | `reload` | ❌ | 扩展重建,重放会重复副作用 |
 
+> `startup` 这一行为什么要拆开:pi 对**每一次进程启动**都报 `startup`,包括「启动即打开旧会话」的情形;`resume` 只在进程内切换会话时发出,`pi -c` 永远不会报它。所以前两行的判定依据是**会话内容**(是否已有消息),不能只看 reason。
+
 **安全门**(按序):
 
 1. **project trust** —— 未信任目录不自动执行任何命令(warning 提示);配置解析失败同样不执行(error 提示)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andares/pi-toolkits",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Integrated toolkit extension for pi — ask mode (read-only Q&A), session-scoped permission checks, model favorites, prompt stash, third-party code review, session autostart, and a dedicated compaction model",
   "type": "module",
   "license": "MIT",

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

@@ -19,6 +19,7 @@ import {
 	GLOBAL_AUTOSTART_FILENAME,
 	parseAutostartConfig,
 	RUNNABLE_REASONS,
+	shouldReplay,
 } from "./autostart.js";
 import { registerAutostart } from "./index.js";
 
@@ -112,6 +113,28 @@ describe("RUNNABLE_REASONS", () => {
 	});
 });
 
+describe("shouldReplay", () => {
+	it("replays a genuinely new session", () => {
+		expect(shouldReplay("startup", false)).toBe(true);
+		expect(shouldReplay("new", false)).toBe(true);
+	});
+
+	it("skips a startup that already has history (a resumed process)", () => {
+		// `pi -c`, `-r`, `--session` and `--fork` all report `startup` for a
+		// session that already carries history.
+		expect(shouldReplay("startup", true)).toBe(false);
+	});
+
+	it("replays a fork even though the branch has history", () => {
+		expect(shouldReplay("fork", true)).toBe(true);
+	});
+
+	it("skips in-process resume and reload", () => {
+		expect(shouldReplay("resume", true)).toBe(false);
+		expect(shouldReplay("reload", true)).toBe(false);
+	});
+});
+
 /* ------------------------------------------------------------------ */
 /* registerAutostart integration (mocked pi surface)                   */
 /* ------------------------------------------------------------------ */
@@ -122,6 +145,7 @@ type SessionStartHandler = (
 		cwd: string;
 		isProjectTrusted: () => boolean;
 		ui: { notify: (message: string, type?: string) => void };
+		sessionManager: { buildContextEntries: () => Array<{ type: string }> };
 	},
 ) => Promise<void>;
 
@@ -133,6 +157,8 @@ interface Harness {
 	commands: Array<{ name: string; source: string }>;
 	failCommands: Set<string>;
 	setTrusted(trusted: boolean): void;
+	/** Simulate a session that already had a conversation (resumed process). */
+	setHistory(entries: Array<{ type: string }>): void;
 	start(reason: string): Promise<void>;
 }
 
@@ -158,6 +184,12 @@ async function makeHarness(
 		await writeFile(join(cwd, AUTOSTART_CONFIG_PATH), config, "utf8");
 	}
 	let trusted = true;
+	// Boot-level entries every session has; a resumed session adds messages.
+	let history: Array<{ type: string }> = [
+		{ type: "session" },
+		{ type: "model_change" },
+		{ type: "thinking_level_change" },
+	];
 	let handler: SessionStartHandler = async () => {};
 	const sent: Harness["sent"] = [];
 	const notifications: Harness["notifications"] = [];
@@ -191,6 +223,9 @@ async function makeHarness(
 		setTrusted(value: boolean) {
 			trusted = value;
 		},
+		setHistory(entries) {
+			history = entries;
+		},
 		async start(reason: string) {
 			await handler({ reason }, {
 				cwd,
@@ -200,6 +235,7 @@ async function makeHarness(
 						notifications.push({ message, type });
 					},
 				},
+				sessionManager: { buildContextEntries: () => history },
 			});
 		},
 		cwd,
@@ -266,6 +302,38 @@ describe("registerAutostart", () => {
 		expect(h.notifications).toEqual([]);
 	});
 
+	it("skips a process started on an existing session (pi -c reports startup)", async () => {
+		const h = await harness(fullConfig);
+		h.setHistory([
+			{ type: "session" },
+			{ type: "model_change" },
+			{ type: "message" },
+		]);
+		await h.start("startup");
+		expect(h.sent).toEqual([]);
+		expect(h.notifications).toEqual([]);
+	});
+
+	it("still replays when the session holds only boot-level entries", async () => {
+		const h = await harness(fullConfig);
+		h.setHistory([
+			{ type: "session" },
+			{ type: "model_change" },
+			{ type: "thinking_level_change" },
+			{ type: "session_info" },
+			{ type: "custom" },
+		]);
+		await h.start("startup");
+		expect(h.sent).toHaveLength(2);
+	});
+
+	it("replays a fork of a session that has history", async () => {
+		const h = await harness(fullConfig);
+		h.setHistory([{ type: "message" }]);
+		await h.start("fork");
+		expect(h.sent).toHaveLength(2);
+	});
+
 	it("silently skips when no config file exists", async () => {
 		const h = await harness(null);
 		await h.start("startup");

package/src/features/autostart/autostart.ts

@@ -41,6 +41,30 @@ export const RUNNABLE_REASONS: ReadonlySet<string> = new Set([
 	"fork",
 ]);
 
+/**
+ * Whether this session start should replay the command lists.
+ *
+ * The reason alone is not enough at process start. `pi -c` (`--continue`),
+ * `-r` (`--resume`), `--session <path>` and `--fork <path>` all open an
+ * existing session *before* the first runtime exists, and that runtime is
+ * created without an explicit session_start event, so extensions see pi's
+ * default reason — `startup` — not `resume` (verified on pi 1.0.0–1.3.0:
+ * `main.js` builds the initial session manager from those flags and calls
+ * `createAgentSessionRuntime` with no `sessionStartEvent`;
+ * `agent-session.js` defaults it to `{ reason: "startup" }`). `resume` is only
+ * emitted for in-process session switches, never for a resumed process.
+ *
+ * So the session content decides: a `startup` on a session that already has
+ * conversation history is a resumed (or forked) process, and its branch already
+ * carries the state a replay would rebuild. `hasHistory` is the same signal pi
+ * itself uses to recognise an existing session
+ * (`buildSessionContext().messages.length > 0`).
+ */
+export function shouldReplay(reason: string, hasHistory: boolean): boolean {
+	if (reason === "startup") return !hasHistory;
+	return RUNNABLE_REASONS.has(reason);
+}
+
 /** Parse/validation failure with a user-facing message. */
 export class AutostartParseError extends Error {}
 

package/src/features/autostart/index.ts

@@ -12,7 +12,9 @@
  *
  * Execution gates, in order:
  *
- *  - reason filter — only startup/new/fork replay (see RUNNABLE_REASONS)
+ *  - reason filter — see `shouldReplay`: startup/new/fork replay, but a
+ *    `startup` that already carries conversation history is a process started
+ *    on an existing session (`pi -c`/`-r`/`--session`/`--fork`) and does not
  *  - 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
@@ -44,7 +46,7 @@ import {
 	commandNameOf,
 	GLOBAL_AUTOSTART_FILENAME,
 	parseAutostartConfig,
-	RUNNABLE_REASONS,
+	shouldReplay,
 } from "./autostart.js";
 
 export interface AutostartOptions {
@@ -63,6 +65,38 @@ function messageOf(error: unknown): string {
 	return error instanceof Error ? error.message : String(error);
 }
 
+/**
+ * Entry types that prove the session already held a conversation.
+ *
+ * `buildContextEntries()` returns the active branch's entries including the
+ * boot-level ones (`session`, `model_change`, `thinking_level_change`), so
+ * presence alone is not enough — a brand-new session has those too.
+ */
+const HISTORY_ENTRY_TYPES: ReadonlySet<string> = new Set([
+	"message",
+	"custom_message",
+	"compaction",
+	"branch_summary",
+]);
+
+/**
+ * Whether the session already carries conversation history.
+ *
+ * This is how a `startup` on an existing session (a resumed process) is told
+ * apart from a genuinely new one — see {@link shouldReplay}. An unreadable
+ * session manager counts as new, which keeps the feature working in hosts where
+ * the session surface is unavailable.
+ */
+function hasConversationHistory(ctx: ExtensionContext): boolean {
+	try {
+		return ctx.sessionManager
+			.buildContextEntries()
+			.some((entry) => HISTORY_ENTRY_TYPES.has(entry.type));
+	} catch {
+		return false;
+	}
+}
+
 export function registerAutostart(
 	pi: ExtensionAPI,
 	options: AutostartOptions = {},
@@ -101,7 +135,10 @@ export function registerAutostart(
 	}
 
 	pi.on("session_start", async (event, ctx) => {
-		if (!RUNNABLE_REASONS.has(event.reason)) return;
+		// `pi -c` / `-r` / `--session` / `--fork` report `startup` for a session
+		// that already has history; the content is what tells them apart. See
+		// shouldReplay in autostart.ts for the host-side evidence.
+		if (!shouldReplay(event.reason, hasConversationHistory(ctx))) return;
 
 		const sources: Source[] = [
 			{