@maxiaochao/pi-toolkit 0.9.2 → 0.9.4

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 2026-09-30 - v0.9.4
+
+- retain Codex Edit in the root toolkit while restoring `@maxiaochao/pi-codex-edit` as an independently installable child package; both distributions share the implementation under `packages/codex-edit`
+- align repeated-region hunk matching with Codex by selecting the first match at or after the current cursor
+- reorganize the repository as an npm workspace: todo, cache-export, codex-edit, tiny-subagent, and worktree own their source, docs, tests, versions, and child-package releases while the root manifest loads their entrypoints directly; BTW remains root-only
+- expand every child README with motivation or upstream alignment, usage examples, screenshots and animated demos captured from the real implementation; document Cache Export's alignment with Hugging Face Tau
+- coordinate child and toolkit releases from one commit with two version updates, two tags, and one atomic push so standalone and bundled users cannot receive mismatched source revisions
+
+## 2026-09-30 - v0.9.3
+
+- refine global agent guidance and add repository issue, triage, and domain instructions
+
 ## 2026-09-30 - v0.9.2
 
 - show contiguous queue positions in the todo widget while retaining stable internal task IDs

package/README.md

@@ -1,125 +1,75 @@
 # pi-toolkit
 
-Personal Pi toolkit with the `/todos`, `/btw`, `/cache_export`, and `apply_patch` extensions, bundled agent skills including Chrome/Chromium automation, the Night Owl theme, and the `pi-worktree` CLI.
+Personal Pi distribution that bundles focused extensions, agent skills, the Night Owl theme, global instructions, and the `pi-worktree` CLI.
 
 ## Install
 
-Install the root package to enable the toolkit extensions globally:
+Install the complete toolkit:
 
 ```bash
 pi install npm:@maxiaochao/pi-toolkit
 ```
 
-The package also provides the `/btw` side-chat extension, the `web-browser` and `chrome-cdp` skills for Chrome/Chromium CDP automation, and the `nightowl` theme. On npm installation, the postinstall hook selects `nightowl` only when no theme has been configured yet; an existing Pi theme setting is preserved.
-
-The package postinstall hook synchronizes the bundled global instructions to:
-
-```text
-~/.pi/agent/AGENTS.md
-```
-
-It also selects `nightowl` as the default theme only when `~/.pi/agent/settings.json` does not already contain a theme. To switch manually, use `/settings` or:
-
-```bash
-pi --use-theme nightowl
-```
-
-An installed package can expose a theme through `pi.themes`, but Pi has no package-manifest field for a default theme, so the guarded postinstall step is used for the npm install case.
-
-When `global/AGENTS.md` changes, publish a new `@maxiaochao/pi-toolkit` version and update installed copies:
+Update it:
 
 ```bash
 pi update npm:@maxiaochao/pi-toolkit
 ```
 
-To synchronize the file directly from a checkout instead:
-
-```bash
-bash scripts/install.sh
-```
-
-The `todo` tool maintains a session checklist for explicit plans and multi-step work. It automatically keeps one task active and advances the next queued task; `replace` starts a clean plan after a change of direction, while `cancelled` records obsolete work honestly. The persistent widget numbers active work by queue position; `/todos` shows active and closed tasks with their stable internal IDs.
-
-The `/btw` side chat is a separate agent session. It can inspect the main conversation and repository, and its thread stays out of the main context until you close it and choose to inject a summary. Use `/btw` to open it or `/btw <question>` to ask directly. While the BTW overlay has focus, use `Up` / `Down` to scroll its transcript one line at a time and `PageUp` / `PageDown` to move by one transcript page.
-
-Use `/cache_export [path]` to write an interactive per-request cache dashboard. It defaults to the latest Context segment for current-state diagnosis, and the View selector can show any earlier segment or all session history. Compaction and model changes both break context charts into segments; cache-hit accumulation also resets at model changes, while TTL and other inferred interruptions remain diagnostic events rather than segment boundaries.
-
-The bundled `nightowl` theme is available to Pi through the package manifest and is selected automatically on npm installation only when no theme is already configured.
-
-## pi-worktree CLI
-
-The package also ships a standalone shell command, `pi-worktree`, that wraps Git worktree creation and Pi launch into one step. On installation (Unix-like systems) the postinstall hook copies it to `~/.local/bin/pi-worktree` and installs bash completion to `~/.local/share/bash-completion/completions/pi-worktree` (no `.bashrc` edits needed).
-
-```bash
-pi-worktree start feat-ui  # create/reuse .worktrees/feat-ui, branch feat-ui, launch pi inside
-pi-worktree list           # list worktrees (main checkout marked "main checkout")
-pi-worktree info feat-ui   # base commit, ahead/behind main, unique commits
-pi-worktree out            # open a shell in the main checkout (for merging)
-pi-worktree remove feat-ui # remove the worktree (refuses unmerged branches)
-pi-worktree prune          # drop stale registrations for manually deleted dirs
-```
-
-Typical loop: `pi-worktree start <name>` to start (Tab completes existing worktree names), commit inside Pi, `pi-worktree out` + `git merge <name>` to land the work, `pi-worktree remove <name>` to clean up. New branches are created from the branch you're currently on (or `HEAD` when detached), and the base commit is recorded in `branch.<name>.base` config so `info` can always tell you where the branch came from. Bash completion covers subcommands and existing worktree names (`pi-worktree feat<Tab>`).
-
-The bundled `pi-worktree` skill documents the CLI for agents: the `start`/`list`/`info`/`out`/`remove`/`prune` commands, the isolation loop from creating a worktree to landing the merge, and which of those commands need an interactive terminal (so an agent uses `start <name> -p "<task>"` for a headless nested run).
+The root package embeds the child-package source snapshots listed below. Install the complete toolkit or selected standalone children, not both.
 
-The bundled `web-browser` skill provides reusable scripts for starting Chrome/Chromium with remote debugging, navigating tabs, evaluating JavaScript, emulating devices, taking screenshots, dismissing cookie dialogs, and inspecting browser logs. It auto-detects common Chrome/Chromium installations on macOS and Linux, including Windows Chrome when Pi runs under WSL; set `BROWSER_BIN` when the binary is elsewhere.
+## Child packages
 
-The browser skill can be loaded explicitly with `/skill:web-browser`. Its scripts are available relative to the skill directory, for example:
+| Package | Capability | Install | Update |
+|---|---|---|---|
+| [pi-todo](packages/todo/README.md) | Session plans, automatic task advancement, `/todos` | `pi install npm:@maxiaochao/pi-todo` | `pi update npm:@maxiaochao/pi-todo` |
+| [pi-cache-export](packages/cache-export/README.md) | Tau-aligned interactive cache dashboard for Pi sessions | `pi install npm:@maxiaochao/pi-cache-export` | `pi update npm:@maxiaochao/pi-cache-export` |
+| [pi-codex-edit](packages/codex-edit/README.md) | Codex-harness `apply_patch` routing for selected GPT models | `pi install npm:@maxiaochao/pi-codex-edit` | `pi update npm:@maxiaochao/pi-codex-edit` |
+| [pi-tiny-subagent](packages/tiny-subagent/README.md) | One focused task in a fresh child Pi context | `pi install npm:@maxiaochao/pi-tiny-subagent` | `pi update npm:@maxiaochao/pi-tiny-subagent` |
+| [pi-worktree](packages/worktree/README.md) | Worktree CLI, completion, installer, and agent skill | `pi install npm:@maxiaochao/pi-worktree` | `pi update npm:@maxiaochao/pi-worktree` |
 
-```bash
-node skills/web-browser/scripts/start.js --headless
-node skills/web-browser/scripts/nav.js https://example.com
-```
-
-The bundled `chrome-cdp` skill (derived from [pasky/chrome-cdp-skill](https://github.com/pasky/chrome-cdp-skill), MIT) complements `web-browser`: instead of launching an isolated browser, it attaches to a Chrome session that already runs with remote debugging (port pre-allocated at launch, or the `chrome://inspect/#remote-debugging` toggle). It is a zero-dependency CLI (`scripts/cdp.mjs`, Node 22+) with per-tab daemons so Chrome's "Allow debugging" modal fires once:
+Each child README owns its feature description, motivation or upstream alignment, examples, screenshots/demos, configuration, and test documentation.
 
-```bash
-export CDP_PORT_FILE="/mnt/c/Users/<you>/AppData/Local/Google/Chrome/CDP-Profile/DevToolsActivePort"
-node skills/chrome-cdp/scripts/cdp.mjs list          # list open tabs → target prefix
-node skills/chrome-cdp/scripts/cdp.mjs snap <target> # accessibility tree
-node skills/chrome-cdp/scripts/cdp.mjs eval <target> 'document.title'
-```
+Multiple standalone children may be installed together. Do not install a child alongside the complete toolkit because that exposes the same resource twice.
 
-Note: Chrome does not always write the `DevToolsActivePort` file (e.g. `--remote-debugging-port` launches on Chrome 152); in that case synthesize one from `GET http://127.0.0.1:<port>/json/version` — first line the port, second line the path of `webSocketDebuggerUrl`. WSL auto-discovery of Windows Chrome profiles is not built in; set `CDP_PORT_FILE` as above.
+Root and child versions remain independent, but repository release tooling publishes a modified child and a new toolkit snapshot from the same commit. Run `pi update --extensions` to update all installed packages. Explicit version sources such as `npm:@maxiaochao/pi-toolkit@0.9.3` remain pinned.
 
-The bundled `show-me` skill (derived from [humanlayer/skills](https://github.com/humanlayer/skills), MIT) explains the current topic with the smallest visual that makes the point — pseudocode, call trees, component or file trees, diffs, Mermaid, or one focused HTML artifact. It is hidden from automatic skill selection, so invoke it explicitly with `/skill:show-me`.
+## Toolkit-only features
 
-The bundled `pdlog` skill decompresses and reads Pudu `.pdlog` proprietary log files, which are binary gibberish when opened directly. It ships a self-contained `ppmd` decompressor (`skills/pdlog/tools/ppmd`, Linux x86-64) and triggers automatically on `.pdlog` files, Pudu logs, ppmd decompression, or logs that open as binary gibberish.
+### `/btw`
 
-The bundled `herdr` skill (from [herdrdev/herdr](https://github.com/herdrdev/herdr) at tag `v0.9.1` with the skill name lowercased, Apache-2.0) drives Herdr, a terminal multiplexer for coding agents: inspecting workspaces, tabs, and panes, starting and prompting other agents, running commands in background panes without stealing focus, reading pane output, and waiting on agent lifecycle states. It activates only when you explicitly mention Herdr, and only when the agent itself runs inside a Herdr pane (`HERDR_ENV=1`); outside a pane it refuses to control the session and stops.
+`/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.
 
-The bundled `agent-team` skill runs cross-vendor adversarial review: the current session acts as manager, and the roster in `skills/agent-team/models.json` (one auditor, one replicator, one adversary on different vendors) is started as long-lived herdr panes that get re-prompted round after round until no pane can produce a new finding.
+### Global instructions and theme
 
-The bundled `tapd` skill documents the third-party `tapd` CLI ([studyzy/tapd-ai-cli](https://github.com/studyzy/tapd-ai-cli)) for TAPD: requirements, defects, tasks, iterations, wikis, comments, attachments, timesheets, and workflow status maps, including the `--filter` advanced query syntax. It is the CLI's own command reference, so refresh the file with `tapd skill init` when the CLI changes.
+The postinstall hook:
 
-The bundled `calldiff` skill (copied verbatim from [tanishqkancharla/calldiff](https://github.com/tanishqkancharla/calldiff), MIT, pinned to a `main` commit because upstream has no release tags) teaches call-stack diffs across git commits: `diff` shows which callees appeared, disappeared, or moved under an entrypoint, `tree` prints one call tree, and `reach` finds call paths between two symbols, all with `--entry`/`--file` entrypoint selection, `--locs` source locations, and `--format json` for agents.
+- synchronizes `global/AGENTS.md` to `~/.pi/agent/AGENTS.md`;
+- selects `nightowl` only when no theme is configured;
+- installs the bundled worktree CLI and bash completion.
 
-## Tiny Subagent
-
-The tiny subagent is a separate npm package. Install it independently when you want the `tiny_subagents` tool:
-
-```bash
-pi install npm:@maxiaochao/pi-tiny-subagent
-```
-
-It is not included in the root package's `pi.extensions` list. The two packages have independent versions, release tags, and update commands:
+Existing theme choices are preserved. To sync only the global instructions from a checkout:
 
 ```bash
-pi update npm:@maxiaochao/pi-toolkit
-pi update npm:@maxiaochao/pi-tiny-subagent
+bash scripts/install.sh
 ```
 
-See [packages/tiny-subagent/README.md](packages/tiny-subagent/README.md) for personas, model selection, child isolation, live transcript rendering, and diagnostics.
-
-## Codex Edit (apply_patch)
-
-The `apply_patch` extension ships with the toolkit as part of `pi.extensions`. It activates Codex's freeform `apply_patch` protocol for GPT/Codex models while other models keep Pi's native `edit` tool. Routing is by model ID (`gpt-5.6-*`) plus API (`openai-responses` or `openai-codex-responses`); provider does not matter. For every other model the extension only re-syncs an already-active editor tool, so it is a no-op.
+## Bundled skills
 
-Because it ships with the toolkit, there is nothing extra to install or update — `pi update npm:@maxiaochao/pi-toolkit` covers it. The model allowlist lives in `extensions/codex-edit/config.json` inside the installed package; edit it there only if you need a different allowlist.
+| Skill | Purpose |
+|---|---|
+| `web-browser` | Launch and automate an isolated Chrome/Chromium session through CDP |
+| `chrome-cdp` | Attach to an existing Chrome debugging session |
+| `show-me` | Explain the current topic with the smallest useful visual |
+| `html-artifact` | Build self-contained HTML explainers and diagrams |
+| `pdlog` | Decompress and inspect Pudu `.pdlog` files |
+| `herdr` | Control Herdr workspaces, tabs, panes, and agents |
+| `agent-team` | Run cross-vendor adversarial review through Herdr |
+| `tapd` | Use the TAPD CLI for requirements, defects, tasks, and wikis |
+| `calldiff` | Diff call stacks across commits |
 
-See [extensions/codex-edit/README.md](extensions/codex-edit/README.md) for the routing rules and [extensions/codex-edit/summary.md](extensions/codex-edit/summary.md) for the measured tradeoffs, including why it stays limited to the `gpt-5.6-*` allowlist instead of replacing `edit` everywhere.
+Package-specific skills, such as `pi-worktree`, are documented by their child package.
 
-## Development
+## Repository
 
-Repository development and release rules are documented in [AGENTS.md](AGENTS.md).
+This repository is an npm workspace. Child implementations live under `packages/*`; `extensions/` contains only the toolkit-only BTW module. Development, testing, media generation, and release rules are documented in [AGENTS.md](AGENTS.md).

package/extensions/{btw.ts → btw/index.ts}

@@ -24,7 +24,7 @@ import {
 	type OverlayHandle,
 	type TUI,
 } from "@earendil-works/pi-tui";
-import { clampBtwScrollTop, getBtwPageScrollSize } from "./btw-scroll.ts";
+import { clampBtwScrollTop, getBtwPageScrollSize } from "./scroll.ts";
 
 const BTW_ENTRY_TYPE = "btw-thread-entry";
 const BTW_RESET_TYPE = "btw-thread-reset";

package/extensions/{tests/btw-history.mjs → btw/tests/history.mjs}

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { clampBtwScrollTop, getBtwPageScrollSize } from "../btw-scroll.ts";
+import { clampBtwScrollTop, getBtwPageScrollSize } from "../scroll.ts";
 
 assert.equal(getBtwPageScrollSize(18), 18, "page scrolling uses the transcript viewport height");
 assert.equal(getBtwPageScrollSize(8.9), 8, "page scrolling uses a whole number of lines");

package/global/AGENTS.md

@@ -1,51 +1,38 @@
 # AGENTS.md
 
-Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
-
-**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+Behavioral guidelines to reduce common LLM coding mistakes. Project-specific instructions override this file when they conflict.
 
 ## 1. Think Before Coding
 
-**Don't assume. Don't hide confusion. Surface tradeoffs.**
+**Surface tradeoffs. Name confusion instead of resolving it silently.**
 
-Before implementing:
-- State your assumptions explicitly. If uncertain, ask.
-- If multiple interpretations exist, present them - don't pick silently.
+- State your material assumptions explicitly.
+- If multiple interpretations exist, present them rather than picking one silently.
 - If a simpler approach exists, say so. Push back when warranted.
-- If something is unclear, stop. Name what's confusing. Ask.
-- If requirements conflict (e.g., durability vs latency, correctness vs speed), name the conflict explicitly. Never average conflicting requirements into something that satisfies neither.
+- If requirements conflict (durability vs latency, correctness vs speed), name the conflict explicitly. Never average conflicting requirements into something that satisfies neither.
+- When unresolved ambiguity would materially change the result, ask. When no human is reachable (headless, async, subagent), choose the interpretation you can defend, state it as an assumption, and proceed under Rule 4.
 
 ## 2. Simplicity First
 
-**Minimum code that solves the problem. Nothing speculative.**
-
-- No features beyond what was asked.
-- No abstractions for single-use code.
-- No "flexibility" or "configurability" that wasn't requested.
-- No error handling for impossible scenarios.
-- If you write 200 lines and it could be 50, rewrite.
+**YAGNI cuts what you don't need; KISS keeps what remains simple.**
 
-Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+- Build what was asked, for the callers that exist today.
+- Introduce an abstraction after repeated use reveals a stable concept.
+- For states excluded by enforced invariants, fail visibly instead of inventing fallback behavior.
+- Each function you write does one thing. If it runs past a couple of screens or nests past three levels, review whether splitting it improves clarity.
 
 ## 3. Surgical Changes
 
 **Touch only what you must. Clean up only your own mess.**
 
-When editing existing code:
-- Don't "improve" adjacent code, comments, or formatting.
-- Don't refactor things that aren't broken.
-- Match existing style, even if you'd do it differently.
-- If you notice unrelated dead code, mention it - don't delete it.
-
-When your changes create orphans:
-- Remove imports/variables/functions that YOUR changes made unused.
-- Don't remove pre-existing dead code unless asked.
+The test: every changed line traces to the user's request, or to a defect that request reveals.
 
-The test: Every changed line should trace directly to the user's request.
+- Match existing style, even if you'd do it differently.
+- Remove imports, variables, and functions that YOUR changes made unused. Leave pre-existing dead code in place and mention it.
 
 When fixing a bug, fix the root cause, not the symptom. Find where the defect actually lives:
-- Grep every caller of the function you touch; a report names a symptom, and patching only the path the ticket mentions leaves sibling callers still broken.
-- If the shared function is wrong, fix it once - do not scatter per-caller guards.
+- Find every statically discoverable caller and relevant implementation; a report names a symptom, and patching only the path the ticket mentions leaves sibling callers still broken.
+- If the shared function is wrong, fix it once - do not scatter per-caller guards. Name the sibling callers the fix now affects.
 - If one caller is wrong, fix that caller - do not add defensive handling to a correct shared function.
 
 ## 4. Goal-Driven Execution
@@ -56,11 +43,10 @@ Transform tasks into verifiable goals:
 - "Add validation" -> "Write tests for invalid inputs, then make them pass"
 - "Fix the bug" -> "Write a test that reproduces it, then make it pass"
 - "Refactor X" -> "Ensure tests pass before and after"
+- "Make X fast" -> "Write and test a simple reference implementation, then optimize against its results"
 
-For multi-step tasks, state a brief plan:
+For multi-step or materially ambiguous tasks, state a brief plan where every step carries its own check:
 1. [Step] -> verify: [check]
-2. [Step] -> verify: [check]
-3. [Step] -> verify: [check]
 
 Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
 
@@ -68,32 +54,21 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
 
 **Understand adjacent code before changing it. "Looks orthogonal" is a dangerous assumption.**
 
-Before adding code to any file:
+Before changing a file:
 - Read the file's exports and public API.
 - Read the immediate callers of the function you're modifying.
-- Check shared utilities in the same module.
-- If you're unsure why code is structured a certain way, ask before writing.
 
 ## 6. Fail Visibly, Not Silently
 
-**Silent skips are failures. Surface uncertainty instead of hiding it.**
+**Silent skips are failures.**
 
 - "Completed" is wrong if anything was silently skipped.
-- "Tests pass" is wrong if any test was skipped.
-- Default to surfacing uncertainty. When in doubt, over-communicate what you're unsure about.
+- "Tests pass" is wrong if any required test was skipped or not run.
 - If a required input, file, or tool is missing (or a step is impossible under the stated constraints), do NOT fabricate it to make a check pass. Report what is missing and what you need.
 
 ## 7. Reuse Before Writing
 
 **Before writing new code, check in order:**
-1. Does it already exist in this codebase? Reuse it - do not re-implement it yourself, even with the standard library. (If the existing helper is itself the bug, fix it once - see Rule 3.)
-2. Does the standard library cover it? Use it.
-3. Only then: write the minimum code that works.
-
-## 8. Use Available Editing Tools
-
-**Follow the current harness's tool surface; do not assume a shell patch helper exists.**
-
-- Use the native file-editing tools exposed by the current environment. In pi, use `edit` for precise replacements and `write` for new files or complete rewrites.
-- Do not run `apply_patch` as a shell command unless `command -v apply_patch` confirms that executable is available.
-- If the harness exposes `apply_patch` as a dedicated tool rather than a command, invoke it only through that tool interface.
+1. Reuse an existing project abstraction when it encodes project semantics. (If it is itself the bug, fix it once - see Rule 3.)
+2. Otherwise use the standard library or a direct dependency already declared by the project.
+3. Only then write it yourself.

package/package.json

@@ -1,16 +1,23 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "description": "Personal pi coding agent toolkit: /todos, /btw, /cache_export and apply_patch extensions, browser automation, and bundled theme/skills.",
   "type": "module",
+  "workspaces": [
+    "packages/*"
+  ],
   "keywords": [
     "pi-package",
     "pi-extension"
   ],
   "files": [
     "extensions",
+    "packages/todo",
+    "packages/cache-export",
+    "packages/codex-edit",
+    "packages/tiny-subagent",
+    "packages/worktree",
     "themes",
-    "bin",
     "README.md",
     "CHANGELOG.md",
     "global/AGENTS.md",
@@ -23,20 +30,22 @@
   },
   "pi": {
     "extensions": [
-      "./extensions/todo.ts",
-      "./extensions/cache-export/index.ts",
-      "./extensions/btw.ts",
-      "./extensions/codex-edit/index.ts"
+      "./packages/todo/extensions/todo.ts",
+      "./packages/cache-export/extensions/cache-export.ts",
+      "./extensions/btw/index.ts",
+      "./packages/codex-edit/extensions/codex-edit.ts",
+      "./packages/tiny-subagent/extensions/tiny-subagent.ts"
     ],
     "skills": [
-      "./skills"
+      "./skills",
+      "./packages/worktree/skills"
     ],
     "themes": [
       "./themes"
     ]
   },
   "bin": {
-    "pi-worktree": "bin/pi-worktree"
+    "pi-worktree": "packages/worktree/bin/pi-worktree"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
@@ -48,8 +57,8 @@
     "ws": "^8.19.0"
   },
   "scripts": {
-    "test": "cd extensions/cache-export && node --experimental-strip-types tests/run-tests.mjs && node --experimental-strip-types ../tests/btw-history.mjs && node --experimental-strip-types ../tests/todo-state.mjs && node tests/e2e-browser.mjs && cd ../codex-edit && node --experimental-strip-types --test tests/package.test.mjs tests/parser.test.mjs",
-    "load-test": "pi -ne -e ./extensions/todo.ts && pi -ne -e ./extensions/cache-export/index.ts && pi -ne -e ./extensions/btw.ts && pi -ne -e ./extensions/codex-edit/index.ts",
+    "test": "node tests/package-layout.mjs && npm --prefix packages/todo test && npm --prefix packages/cache-export test && npm --prefix packages/codex-edit test && npm --prefix packages/tiny-subagent test && npm --prefix packages/worktree test && node --experimental-strip-types extensions/btw/tests/history.mjs",
+    "load-test": "pi -ne -e ./packages/todo/extensions/todo.ts && 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/tiny-subagent/extensions/tiny-subagent.ts",
     "eval:agents": "node evaluations/agents-md/run.mjs",
     "eval:agents:test": "node evaluations/agents-md/tests/run-tests.mjs",
     "postinstall": "node scripts/install-agents.mjs"

package/packages/cache-export/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 2026-09-30 - v0.1.0
+
+- 从 `@maxiaochao/pi-toolkit` 提取 cache export 权威源码，支持主包捆绑和独立安装。

package/packages/cache-export/README.md

@@ -0,0 +1,70 @@
+# @maxiaochao/pi-cache-export
+
+Pi 的 `/cache_export [path]` 扩展，把当前会话写成可交互的缓存诊断 HTML。
+
+![Cache Export 真实 Web 仪表盘截图](docs/screenshot.png)
+
+## 为什么有这个包
+
+这个功能对齐 [Hugging Face Tau](https://github.com/huggingface/tau) coding agent 的 session usage / cache dashboard。`src/tau-assets.ts` 与仪表盘基础逻辑来自 Tau 的 `tau_coding/session_usage.py`，本包把它适配到 Pi session，并增加：
+
+- Pi 消息、tool result、模型切换和 compaction 解析。
+- 按 Context segment 查看最新上下文、历史 segment 或全部历史。
+- cache miss、TTL expiry、cache rebuild 和低命中 streak 诊断。
+- 跨图表断点的 tooltip，以及 segment 内的全局请求编号。
+
+Tau 资产保持上游一致；上述 Pi 语义和诊断规则由本包维护。
+
+## 演示
+
+![导出缓存仪表盘演示](docs/demo.gif)
+
+```text
+/cache_export
+/cache_export ./reports/cache.html
+/cache_export --open
+```
+
+命令读取当前 session，生成自包含 HTML；`--open` 在支持的桌面环境中同时打开浏览器。
+
+## 安装
+
+完整工具包已经包含本扩展：
+
+```bash
+pi install npm:@maxiaochao/pi-toolkit
+```
+
+只需要缓存仪表盘时单独安装：
+
+```bash
+pi install npm:@maxiaochao/pi-cache-export
+```
+
+两种方式二选一，避免重复注册。
+
+## 更新
+
+```bash
+pi update npm:@maxiaochao/pi-toolkit       # 更新主包内置版本
+pi update npm:@maxiaochao/pi-cache-export  # 更新独立子包
+```
+
+两个 npm 包版本独立。Cache Export 源码变更需要分别发布主包和子包，才能覆盖两类用户。
+
+## 功能
+
+- 默认展示最新 Context segment，也可切换历史 segment 或全部历史。
+- 模型切换和 compaction 切分 segment。
+- 诊断 cache miss、TTL、cache rebuild 和低命中 streak。
+- 导出的 HTML 自包含，可离线查看。
+
+## 开发与测试
+
+权威源码位于 `extensions/` 和 `src/`。`src/tau-assets.ts` 必须由上游资产重生成，禁止手改。测试流程、数据用例和结果见 [TESTING.md](TESTING.md)。
+
+```bash
+npm --prefix packages/cache-export test
+npm --prefix packages/cache-export run load-test
+npm pack ./packages/cache-export --dry-run
+```

package/packages/cache-export/TESTING.md

@@ -0,0 +1,17 @@
+# Cache Export 测试方案
+
+## 流程
+
+1. `npm --prefix packages/cache-export test`：先运行确定性逻辑测试，再运行真实 Chromium E2E。
+2. `npm --prefix packages/cache-export run load-test`：加载扩展入口。
+3. `npm pack ./packages/cache-export --dry-run`：检查 tarball。
+4. 确认 Tau 来源说明、功能示例、真实浏览器截图 `docs/screenshot.png` 和 `docs/demo.gif` 随包发布。
+
+## 用例数据
+
+- 47 个确定性断言：命中率阈值、TTL、cache rebuild、模型切换、compaction、segment 和退化输入。
+- 18 个浏览器断言：三张图的 tooltip、断点两侧、全历史视图、segment 全局请求号和浏览器异常。
+
+## 最近验证结果
+
+迁移前基线为 `47 passed, 0 failed` 和 `18 passed, 0 failed, 0 skipped`。找不到 Chrome 时 E2E 会明确报告 skip；发布验收要求可用 Chrome 的环境中 0 skip。

package/{extensions/cache-export/index.ts → packages/cache-export/extensions/cache-export.ts}

@@ -9,7 +9,7 @@ import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
-import { parseEntries, buildCacheExportHtml } from "./render.ts";
+import { parseEntries, buildCacheExportHtml } from "../src/render.ts";
 
 const DEFAULT_DIR = join(homedir(), ".cache", "pi-cache-dashboard");
 

package/packages/cache-export/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@maxiaochao/pi-cache-export",
+  "version": "0.1.0",
+  "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"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chaochaoxiaochao/pi-toolkit.git",
+    "directory": "packages/cache-export"
+  },
+  "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",
+    "load-test": "pi -ne -e ./extensions/cache-export.ts"
+  },
+  "publishConfig": { "access": "public" }
+}

package/{extensions/cache-export → packages/cache-export/src}/render.ts

@@ -1,6 +1,6 @@
 // tau-style usage/cache dashboard renderer.
 // Logic ported from huggingface/tau src/tau_coding/session_usage.py (render_usage_dashboard),
-// interactivity/styles auto-extracted into ./tau-assets.mjs.
+// interactivity/styles auto-extracted into ./tau-assets.ts.
 
 import { USAGE_STYLES, USAGE_SCRIPT } from "./tau-assets.ts";
 

package/{extensions → packages}/cache-export/tests/e2e-browser.mjs

@@ -8,14 +8,14 @@
 // test prints SKIP and exits 0 so CI without Chrome still passes; if a
 // browser IS found, failing assertions exit 1.
 //
-// Run: node tests/e2e-browser.mjs        (from extensions/cache-export)
+// Run: node tests/e2e-browser.mjs        (from packages/cache-export)
 
 import { spawn, execFileSync } from "node:child_process";
 import { existsSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
 import net from "node:net";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { parseEntries, buildCacheExportHtml } from "../render.ts";
+import { parseEntries, buildCacheExportHtml } from "../src/render.ts";
 
 let pass = 0, fail = 0, skipped = 0;
 function check(name, cond, detail = "") {

package/{extensions → packages}/cache-export/tests/run-tests.mjs

@@ -3,8 +3,8 @@
 import { mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import registerCacheExport from "../index.ts";
-import { parseEntries, analyzeStreaks, analyzeMisses, buildContextSegments, lineChartForTest, renderDashboard, chartEvents } from "../render.ts";
+import registerCacheExport from "../extensions/cache-export.ts";
+import { parseEntries, analyzeStreaks, analyzeMisses, buildContextSegments, lineChartForTest, renderDashboard, chartEvents } from "../src/render.ts";
 
 let pass = 0, fail = 0;
 function check(name, cond, detail = "") {

package/packages/codex-edit/CHANGELOG.md

@@ -0,0 +1,32 @@
+## 2026-09-30 - v0.1.7
+
+- match Codex `apply_patch` semantics by selecting the first matching region at or after the current hunk cursor
+- add standalone package testing documentation and real parser-generated screenshot/demo media
+
+## 2026-09-30 - v0.1.6
+
+- route apply_patch by API plus model-ID glob instead of requiring grammar-tool support
+
+## 2026-09-08 - v0.1.5
+
+- route gpt-5.6-* models to apply_patch by model glob
+
+## 2026-09-04 - v0.1.4
+
+- update Luna High rerun statistics and paired timing methodology
+
+## 2026-09-04 - v0.1.3
+
+- correct Luna timing analysis to count only completed correct runs
+
+## 2026-09-04 - v0.1.2
+
+- default to validated Sol routing and document Luna High benchmark variance
+
+## 2026-09-04 - v0.1.1
+
+- fix package config discovery so GPT/Codex model routing activates apply_patch
+
+## 2026-09-04 - v0.1.0
+
+- initial release of the Codex-style apply_patch Pi extension and docs