@maxiaochao/pi-toolkit 0.13.7 → 0.13.9

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## 2026-10-23 - v0.13.9
+
+- cache-export v0.1.1: correct request timing, usage scope and historical cache evidence
+
+## 2026-10-23 - v0.13.8
+
+- herdr-subagents v0.7.5: bound missing-report recovery and close unconfirmed child outcomes
+- Cache Export: use request timing and historical, non-secret cache-policy observations; separate auxiliary usage, mark unknowns, and resolve exports against the session cwd.
+- BTW: seed main and restored side history through SessionManager instead of transient agent state.
+- Herdr Subagents: one durable child-side missing-report reminder; terminal diagnostics for unconfirmed results, cancellation, and final errors without parent-side wake-up logic.
+- Codex Edit: preflight file/parent conflicts before writing and preserve ordinary file permissions on moves.
+- OpenAI Account Pool: classify forced-refresh failures consistently and prohibit authentication repair after output delivery.
+- Worktree: return the worktree root from already-active nested directories.
+- web-browser: refuse profile mutation while Chrome is active, including another port or missing launcher state.
+
 ## 2026-10-23 - v0.13.7
 
 - openai-account-pool v0.1.8: fix stranded account-pool references after removal and recover email labels

package/README.md

@@ -58,7 +58,7 @@ Root and child versions remain independent, but repository release tooling publi
 
 ### `/btw`
 
-`/btw` opens a separate side-chat session that can inspect the main conversation and repository without entering the main context. Closing it can optionally inject a summary. Use `Up` / `Down` for line scrolling and `PageUp` / `PageDown` for page scrolling.
+`/btw` opens a separate side-chat session that can inspect the main conversation and repository without entering the main context. Main and restored side history are seeded through SessionManager; subsequent questions reuse the side session. Closing it can optionally inject a summary. Use `Up` / `Down` for line scrolling and `PageUp` / `PageDown` for page scrolling.
 
 ### Global instructions and theme
 
@@ -105,3 +105,7 @@ npm run release:check -- v0.13.1 --timeout 900 --interval 15
 Omit the tag to use the current root `package.json` version. Requires Node.js, Git, npm, tar, authenticated GitHub CLI (`gh auth login`), and local release tags (`git fetch origin --tags` if needed).
 
 The read-only check verifies remote tag commits, waits for the matching `publish.yml` run to succeed, and checks exact public npm versions and tarball integrity. It compares every packaged file and mode against an isolated snapshot of the release tag, including an optional coordinated child release. It uses the tag rather than uncommitted checkout changes, never installs or publishes, and removes temporary downloads. Failures exit nonzero; only a pending workflow or npm `E404` is retried within the shared timeout (600 seconds by default). Local packing uses `--ignore-scripts`, matching this repository's source-only packages; packages that add generated prepack output will need this check updated.
+
+## Safety and evidence boundaries
+
+Cache Export reports provider/Pi usage, not measured server cache state. Main requests and auxiliary calls are separate; missing reasoning or retention remains unknown. Relative paths use the session cwd. Herdr children get at most one missing-report reminder and report unconfirmed outcomes explicitly. Codex Edit preflights path hierarchy conflicts and preserves executable bits on moves. Account-pool transient refresh errors never justify rotation, and delivered output forbids replay. Worktree reuse always returns the worktree root. Browser profile reset requires Chrome to be stopped.

package/extensions/btw/index.ts

@@ -12,7 +12,7 @@ import {
 	type ModelRuntime,
 	type ResourceLoader,
 } from "@earendil-works/pi-coding-agent";
-import { type AssistantMessage, type Message, type ThinkingLevel as AiThinkingLevel } from "@earendil-works/pi-ai";
+import { type AssistantMessage, type ThinkingLevel as AiThinkingLevel } from "@earendil-works/pi-ai";
 import {
 	Container,
 	Input,
@@ -140,15 +140,8 @@ function getLastAssistantMessage(session: AgentSession): AssistantMessage | null
 	return null;
 }
 
-function buildSeedMessages(ctx: ExtensionContext, thread: BtwDetails[]): Message[] {
-	const seed: Message[] = [];
-
-	try {
-		const contextMessages = buildSessionContext(ctx.sessionManager.getEntries(), ctx.sessionManager.getLeafId()).messages;
-		seed.push(...(contextMessages.filter((message) => "role" in message) as Message[]));
-	} catch {
-		// Ignore context seed failures and continue with an empty side thread.
-	}
+function buildSeedMessages(ctx: ExtensionContext, thread: BtwDetails[]): ReturnType<typeof buildSessionContext>["messages"] {
+	const seed = buildSessionContext(ctx.sessionManager.getEntries(), ctx.sessionManager.getLeafId()).messages;
 
 	for (const item of thread) {
 		seed.push(
@@ -631,8 +624,11 @@ export default function (pi: ExtensionAPI) {
 			return null;
 		}
 
+		const sessionManager = SessionManager.inMemory(ctx.cwd);
+		for (const message of buildSeedMessages(ctx, thread)) sessionManager.appendMessage(message);
 		const { session } = await createAgentSession({
-			sessionManager: SessionManager.inMemory(),
+			cwd: ctx.cwd,
+			sessionManager,
 			model: ctx.model,
 			modelRuntime: getParentModelRuntime(ctx),
 			thinkingLevel: pi.getThinkingLevel() as SessionThinkingLevel,
@@ -640,11 +636,6 @@ export default function (pi: ExtensionAPI) {
 			resourceLoader: createBtwResourceLoader(ctx),
 		});
 
-		const seedMessages = buildSeedMessages(ctx, thread);
-		if (seedMessages.length > 0) {
-			session.agent.state.messages = seedMessages as typeof session.agent.state.messages;
-		}
-
 		const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
 			if (!sideBusy || !pendingQuestion) {
 				return;

package/extensions/btw/tests/context.mjs

@@ -0,0 +1,78 @@
+// Exercise the real SessionManager projection and actual provider input.
+import "../../../packages/background-tasks/tests/runtime.mjs";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+const { createAgentSession, DefaultResourceLoader, ModelRuntime, SessionManager, SettingsManager } = await import("@earendil-works/pi-coding-agent");
+const { createAssistantMessageEventStream } = await import("@earendil-works/pi-ai");
+const { default: btw } = await import("../index.ts");
+
+const root = mkdtempSync(join(tmpdir(), "btw-context-"));
+const originalAgentDir = process.env.PI_CODING_AGENT_DIR;
+const originalCwd = process.cwd();
+process.chdir(root);
+process.env.PI_CODING_AGENT_DIR = root;
+const settings = { retry: { enabled: false }, compaction: { enabled: false }, cacheWarming: "off" };
+writeFileSync(join(root, "settings.json"), JSON.stringify(settings));
+const runtime = await ModelRuntime.create({ authPath: join(root, "auth.json"), modelsPath: join(root, "models.json"), refreshOnCreate: false });
+const requests = [];
+const sessions = new Set();
+runtime.registerProvider("btw-fixture", {
+  name: "Offline fixture", api: "btw-fixture", apiKey: "not-secret", baseUrl: "http://127.0.0.1:1",
+  models: [{ id: "offline", name: "Offline", reasoning: false, input: ["text"], contextWindow: 128000, maxTokens: 4096, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 } }],
+  streamSimple(model, context) {
+    requests.push(structuredClone(context));
+    const answer = `ANSWER_${requests.length}`;
+    const stream = createAssistantMessageEventStream();
+    queueMicrotask(() => {
+      const message = { role: "assistant", api: model.api, provider: model.provider, model: model.id, timestamp: Date.now(), content: [{ type: "text", text: answer }], stopReason: "stop", usage: { input: 1, output: 1, cacheRead: 0, cacheWrite: 0, totalTokens: 2, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } } };
+      stream.push({ type: "start", partial: message });
+      stream.push({ type: "done", reason: "stop", message });
+    });
+    return stream;
+  },
+});
+async function create(manager) {
+  const settingsManager = SettingsManager.inMemory(settings);
+  const loader = new DefaultResourceLoader({ cwd: root, agentDir: root, settingsManager, noExtensions: true, noSkills: true, noPromptTemplates: true, noThemes: true, noContextFiles: true, extensionFactories: [btw] });
+  await loader.reload();
+  const { session, extensionsResult } = await createAgentSession({ cwd: root, agentDir: root, modelRuntime: runtime, model: runtime.getModel("btw-fixture", "offline"), thinkingLevel: "off", resourceLoader: loader, sessionManager: manager, settingsManager, tools: [] });
+  assert.deepEqual(extensionsResult.errors, []);
+  sessions.add(session);
+  await session.bindExtensions({});
+  return session;
+}
+async function dispose(session) {
+  await session.abort();
+  await session.extensionRunner.emit({ type: "session_shutdown", reason: "quit" });
+  session.dispose();
+  sessions.delete(session);
+}
+try {
+  const manager = SessionManager.inMemory(root);
+  const parent = await create(manager);
+  await parent.prompt("MAIN_CONTEXT");
+  const mainMessages = structuredClone(parent.messages);
+  await parent.prompt("/btw SIDE_FIRST");
+  assert.equal(requests.length, 2);
+  for (const text of ["MAIN_CONTEXT", "ANSWER_1", "SIDE_FIRST"]) assert.ok(JSON.stringify(requests[1].messages).includes(text), `first BTW request lost ${text}`);
+  await parent.prompt("/btw SIDE_SECOND");
+  assert.equal(requests.length, 3);
+  for (const text of ["MAIN_CONTEXT", "SIDE_FIRST", "ANSWER_2", "SIDE_SECOND"]) assert.ok(JSON.stringify(requests[2].messages).includes(text), `continuous side session lost ${text}`);
+  assert.deepEqual(parent.messages, mainMessages, "side messages must stay outside the main context");
+  await dispose(parent);
+  const restored = await create(manager);
+  await restored.prompt("/btw SIDE_RESTORED");
+  assert.equal(requests.length, 4);
+  for (const text of ["MAIN_CONTEXT", "ANSWER_1", "SIDE_FIRST", "ANSWER_2", "SIDE_SECOND", "ANSWER_3", "SIDE_RESTORED"]) {
+    assert.ok(JSON.stringify(requests[3].messages).includes(text), `restored BTW request lost ${text}`);
+  }
+  console.log("PASS BTW provider input: main history, continuous side session, restored side history, main-context isolation");
+} finally {
+  for (const session of sessions) await dispose(session);
+  if (originalAgentDir === undefined) delete process.env.PI_CODING_AGENT_DIR;
+  else process.env.PI_CODING_AGENT_DIR = originalAgentDir;
+  process.chdir(originalCwd);
+  rmSync(root, { recursive: true, force: true });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.13.7",
+  "version": "0.13.9",
   "description": "Personal pi coding agent toolkit: background tasks, scheduler, /btw, /cache_export, apply_patch, browser automation, and bundled theme/skills.",
   "type": "module",
   "workspaces": [
@@ -61,8 +61,9 @@
     "ws": "^8.19.0"
   },
   "scripts": {
-    "test": "node tests/package-layout.mjs && node tests/release-check.mjs && node tests/post-release-check.mjs && npm --prefix packages/todo test && npm --prefix packages/cache-export test && npm --prefix packages/codex-edit test && npm --prefix packages/herdr-subagents test && npm --prefix packages/openai-account-pool test && npm --prefix packages/scheduler test && npm --prefix packages/background-tasks test && npm --prefix packages/worktree test && node --experimental-strip-types extensions/btw/tests/history.mjs",
-    "test:root": "node tests/package-layout.mjs && node tests/release-check.mjs && node tests/post-release-check.mjs && node --experimental-strip-types extensions/btw/tests/history.mjs",
+    "test": "node tests/package-layout.mjs && node tests/release-check.mjs && node tests/post-release-check.mjs && npm --prefix packages/todo test && npm --prefix packages/cache-export test && npm --prefix packages/codex-edit test && npm --prefix packages/herdr-subagents test && npm --prefix packages/openai-account-pool test && npm --prefix packages/scheduler test && npm --prefix packages/background-tasks test && npm --prefix packages/worktree test && node --experimental-strip-types extensions/btw/tests/history.mjs && node --experimental-strip-types extensions/btw/tests/context.mjs",
+    "test:web-browser": "node tests/web-browser.mjs",
+    "test:root": "node tests/package-layout.mjs && node tests/release-check.mjs && node tests/post-release-check.mjs && node --experimental-strip-types extensions/btw/tests/history.mjs && node --experimental-strip-types extensions/btw/tests/context.mjs",
     "load-test": "pi -ne -e ./packages/cache-export/extensions/cache-export.ts && pi -ne -e ./extensions/btw/index.ts && pi -ne -e ./packages/codex-edit/extensions/codex-edit.ts && pi -ne -e ./packages/herdr-subagents/extensions/herdr-subagents.ts && pi -ne -e ./packages/scheduler/extensions/scheduler.ts && pi -ne -e ./packages/background-tasks/extensions/background-tasks.ts && pi -ne -e ./packages/worktree/extensions/worktree.ts && npm --prefix packages/background-tasks run load-test -- --toolkit",
     "load-test:root": "pi -ne -e ./extensions/btw/index.ts",
     "release:check": "node scripts/post-release-check.mjs",

package/packages/cache-export/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 2026-10-23 - v0.1.1
+
+- correct request timing, usage scope and historical cache evidence
+- Keep mixed historical TTLs and partial one-hour writes unknown at request scope; a one-hour subset must not override mixed-policy evidence.
+
+- Show main-request usage separately from completed cache-warm, compaction, and other auxiliary usage.
+- Use message timestamps and response durations; remove universal TTL and inferred expiry propagation. Retention references are historical observations, never server expiry measurements.
+- Track context edits, label segment cumulative rates, and show unreported reasoning as Unknown without plotting zero.
+- Persist allowlisted cache parameters and model-policy references without prompts, cache keys, headers, URLs, or credentials.
+- Resolve relative export paths against the session cwd; add deterministic, native Pi, and real Chrome regressions.
+
 ## 2026-09-30 - v0.1.0
 
 - 从 `@maxiaochao/pi-toolkit` 提取 cache export 权威源码，支持主包捆绑和独立安装。

package/packages/cache-export/README.md

@@ -68,3 +68,17 @@ npm --prefix packages/cache-export test
 npm --prefix packages/cache-export run load-test
 npm pack ./packages/cache-export --dry-run
 ```
+
+## 数据与证据口径
+
+主曲线只包含当前分支的主对话 assistant usage。保温、压缩等辅助 usage 单独列出，不计入主曲线或主对话合计。保温只认已完成的 `usage/cache_warm` 记录，不把准备事件当成功。
+
+命中率是服务商/Pi 报告的 `cacheRead / (input + cacheRead + cacheWrite)`，不是服务端缓存状态探针。横轴是请求序号；模型切换、压缩和 `context_edit` 等上下文变更会分段，累计曲线标为 segment cumulative。分段首条不等于会话冷启动。
+
+请求开始取 `message.timestamp`，响应耗时取 `durationMs`；落盘时间另列，不充当请求开始或空闲时间。未报告的时间、reasoning、保留期显示 Unknown。
+
+扩展从启用后的 `before_provider_request` 观察已知 retention/TTL 枚举和模型 `promptCache` 参考值，在对应 assistant 消息结束时写入 `cache-export-request` 自定义记录。只存非秘密白名单字段；不存提示词、cache key、headers、URL 或凭据。不用当前配置补历史；hook 之后其他扩展仍可能修改请求。这些值只表示观察到的请求/策略参考，不证明服务端采用、续期或到期。混合 TTL、缺字段或未记录历史保持未知，不套用通用 5 分钟，也不把 OpenAI 公共 API 的期限直接套给 Codex 订阅接口。
+
+已观察 usage/上下文事件、策略参考和可能原因分开表述。Pi 自带的缓存推断不是服务端真值，也不是本报告的校准标准。
+
+相对输出路径以当前 Pi session 的 cwd 为基准（包括切换后的 worktree）。

package/packages/cache-export/TESTING.md

@@ -9,9 +9,15 @@
 
 ## 用例数据
 
-- 47 个确定性断言：命中率阈值、TTL、cache rebuild、模型切换、compaction、segment 和退化输入。
-- 18 个浏览器断言：三张图的 tooltip、断点两侧、全历史视图、segment 全局请求号和浏览器异常。
+- 47 个基础确定性断言：命中率阈值、保留期未知、可能原因、模型切换、compaction、segment 和退化输入。
+- `tests/evidence.mjs`：慢响应不冒充空闲、历史策略缺失/混合 TTL、不传播推算到期、真实保温 usage、context_edit、reasoning 未知、白名单无秘密、相对 cwd。
+- `tests/extension.mjs`：真实 Pi SDK、离线 provider 的 payload hook、assistant 关联和 session-relative 导出。用 `PI_TEST_BINARY` 选 Pi 1.4.0。
+- 21 个浏览器断言：原有 tooltip/断点/segment 验证，加真实 CDP 点击和键盘切换、主/辅助范围标签、Unknown reasoning 不画零线或零点。`CACHE_EXPORT_SCREENSHOT_DIR` 可保留真实截图。
 
 ## 最近验证结果
 
 迁移前基线为 `47 passed, 0 failed` 和 `18 passed, 0 failed, 0 skipped`。找不到 Chrome 时 E2E 会明确报告 skip；发布验收要求可用 Chrome 的环境中 0 skip。
+
+验证依据是输入 usage 与渲染结果、真实 SDK 事件和 Chrome 行为；不是 Pi 自带缓存推断，更不是对服务端实际 TTL 的校准。
+
+混合 TTL 回归同时包含 `cacheWrite1h` 为零、部分写入及全部写入的情况；所有已知混合策略均保持请求级 Unknown。只有写入计数揭示混合、没有 payload 历史时也不得推断为单一 1h。

package/packages/cache-export/extensions/cache-export.ts

@@ -60,6 +60,47 @@ function defaultOutputPath(ctx) {
 }
 
 export default function (pi) {
+  let observed;
+  pi.on("turn_start", () => { observed = undefined; });
+  pi.on("agent_end", () => { observed = undefined; });
+  pi.on("session_start", () => { observed = undefined; });
+  pi.on("before_provider_request", (event, ctx) => {
+    if (!ctx.model) return;
+    const payload = event.payload ?? {};
+    const explicitTtlsSeconds = new Set();
+    const controls = [
+      payload.cache_control,
+      ...(Array.isArray(payload.system) ? payload.system.map((block) => block?.cache_control) : []),
+      ...(Array.isArray(payload.tools) ? payload.tools.map((tool) => tool?.cache_control) : []),
+      ...(Array.isArray(payload.messages) ? payload.messages.flatMap((message) =>
+        Array.isArray(message?.content) ? message.content.map((block) => block?.cache_control) : []) : []),
+    ];
+    for (const control of controls) {
+      if (control?.type === "ephemeral" && control.ttl === "1h") explicitTtlsSeconds.add(3600);
+      if (control?.type === "ephemeral" && control.ttl === "5m") explicitTtlsSeconds.add(300);
+    }
+    const retention = ["in_memory", "24h"].includes(payload.prompt_cache_retention) ? payload.prompt_cache_retention : null;
+    if (retention === "24h") explicitTtlsSeconds.add(86400);
+    const modelReference = {};
+    for (const tier of ["short", "long"]) {
+      const seconds = ctx.model.promptCache?.[tier];
+      if (Number.isFinite(seconds) && seconds > 0) modelReference[tier] = seconds;
+    }
+    // Allowlist only. Never persist prompts, headers, URLs, cache keys, or tokens.
+    observed = {
+      provider: ctx.model.provider, model: ctx.model.id, api: ctx.model.api,
+      observedAt: Date.now(),
+      policy: { retention, explicitTtlsSeconds: [...explicitTtlsSeconds], modelReference },
+    };
+  });
+  pi.on("message_end", (event) => {
+    const message = event.message;
+    if (message?.role !== "assistant") return;
+    if (observed && observed.provider === message.provider && observed.model === message.model && observed.api === message.api) {
+      pi.appendEntry("cache-export-request", { ...observed, messageTimestamp: message.timestamp });
+    }
+    observed = undefined;
+  });
   pi.registerCommand("cache_export", {
     description: "Export an interactive cache dashboard (latest Context segment by default, all-history switch, per-request charts)",
     handler: async (args, ctx) => {
@@ -77,13 +118,13 @@ export default function (pi) {
       const pathArg = tokens.find((t) => !t.startsWith("-"));
 
       const data = parseEntries(entries);
-      if (data.requests.length === 0) {
-        ctx.ui.notify("No assistant requests with usage data yet.", "error");
+      if (data.requests.length === 0 && data.auxiliary.length === 0) {
+        ctx.ui.notify("No main or auxiliary usage data yet.", "error");
         return;
       }
       const info = ctx.sessionManager;
       const sessionId = info.getSessionId ? info.getSessionId() : undefined;
-      const outPath = resolve(pathArg || defaultOutputPath(ctx));
+      const outPath = pathArg ? resolve(ctx.cwd, pathArg) : defaultOutputPath(ctx);
 
       mkdirSync(dirname(outPath), { recursive: true });
       writeFileSync(outPath, buildCacheExportHtml(data, { title: "cache export", sessionId }), "utf8");

package/packages/cache-export/package.json

@@ -1,22 +1,40 @@
 {
   "name": "@maxiaochao/pi-cache-export",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Interactive cache usage dashboard export for Pi sessions.",
   "type": "module",
-  "keywords": ["pi-package", "pi-extension", "cache", "dashboard"],
-  "files": ["extensions", "src", "docs", "README.md", "TESTING.md", "CHANGELOG.md"],
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "cache",
+    "dashboard"
+  ],
+  "files": [
+    "extensions",
+    "src",
+    "docs",
+    "README.md",
+    "TESTING.md",
+    "CHANGELOG.md"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/chaochaoxiaochao/pi-toolkit.git",
     "directory": "packages/cache-export"
   },
-  "pi": { "extensions": ["./extensions/cache-export.ts"] },
+  "pi": {
+    "extensions": [
+      "./extensions/cache-export.ts"
+    ]
+  },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*"
   },
   "scripts": {
-    "test": "node --experimental-strip-types tests/run-tests.mjs && node tests/e2e-browser.mjs",
+    "test": "node --experimental-strip-types tests/run-tests.mjs && node --experimental-strip-types tests/evidence.mjs && node --experimental-strip-types tests/extension.mjs && node tests/e2e-browser.mjs",
     "load-test": "pi -ne -e ./extensions/cache-export.ts"
   },
-  "publishConfig": { "access": "public" }
+  "publishConfig": {
+    "access": "public"
+  }
 }