@maxiaochao/pi-toolkit 0.9.3 → 0.9.4

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 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

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/package.json

@@ -1,16 +1,23 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.9.3",
+  "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

package/packages/codex-edit/README.md

@@ -0,0 +1,123 @@
+# Codex Edit (apply_patch)
+
+A Pi extension that gives selected GPT models the same `apply_patch` editing protocol used by the Codex harness, while every model outside the routing rules keeps Pi's native `edit` tool.
+
+![Codex Edit production parser screenshot](docs/screenshot.png)
+
+## Why this package exists
+
+GPT models used through the Codex harness are trained to edit with OpenAI's `apply_patch` protocol, while Pi's native editor uses a different `oldText/newText` contract. This package exposes the Codex-harness editing interface inside Pi for explicitly allowed models. Models that do not match the rules continue to see Pi's native `edit`; the extension never replaces the editor universally.
+
+The implementation follows Codex's ordered hunk matching semantics and supports the same Add/Delete/Update/Move patch shape, then adds workspace, symlink, overwrite, preflight, and mutation-queue safeguards required by Pi.
+
+## Demo
+
+![Codex apply_patch demo](docs/demo.gif)
+
+```text
+*** Begin Patch
+*** Update File: src/app.ts
+@@
+-const enabled = false;
++const enabled = true;
+*** End Patch
+```
+
+The complete patch is parsed and preflighted before any file is mutated; the result reports per-file diffs and committed paths.
+
+## Install
+
+Install it as a separate package:
+
+```bash
+pi install npm:@maxiaochao/pi-codex-edit
+```
+
+This is the standalone child package of `@maxiaochao/pi-toolkit`. The full toolkit already bundles the same implementation, so install this package only when you do not want the rest of the toolkit. Installing both is unnecessary and may register `apply_patch` twice.
+
+Update whichever distribution you installed:
+
+```bash
+pi update npm:@maxiaochao/pi-toolkit     # full toolkit, including bundled Codex Edit
+pi update npm:@maxiaochao/pi-codex-edit  # standalone child package
+```
+
+The two npm packages have independent versions. An implementation or configuration change reaches toolkit users only after a new `@maxiaochao/pi-toolkit` version is published, and reaches standalone users only after a new `@maxiaochao/pi-codex-edit` version is published.
+
+The extension registers `apply_patch` and selects the editing tool from the resolved model configuration:
+
+- Allowed model ID on a supported Responses API: Codex-harness-compatible `apply_patch`
+- Model ID outside the allowlist: Pi's native `edit`
+- Model on another API, even if its ID matches: Pi's native `edit`
+
+The default allowlist enables all `gpt-5.6-*` models regardless of provider. Other model families can be added after separate validation by editing `config.json`.
+
+The extension does not add a permanent AGENTS rule telling models not to use `apply_patch`. Only the selected editor tool is active, so the model receives one editing protocol.
+
+## What `apply_patch` does
+
+The tool accepts raw Codex patch text between `*** Begin Patch` and `*** End Patch`. It supports:
+
+- `Add File`
+- `Delete File`
+- `Update File`
+- `Move to`
+- multiple update hunks with `@@` context
+- EOF-oriented insertions
+
+Before writing, it parses the complete patch, resolves paths, rejects workspace escapes and unsafe symlink/parent paths, reads all source files, and computes every update in memory. Only after preflight succeeds does it mutate files. It returns per-file diff details and reports committed paths if a later filesystem operation fails.
+
+## Configuration
+
+The extension defaults to a model-ID allowlist in `config.json`: `"gpt-5.6-*"`. Provider does not affect routing. Each entry is a `*` glob, so this matches every `gpt-5.6-` variant. The route additionally requires:
+
+```text
+model.api = openai-responses or openai-codex-responses
+```
+
+The effective routing rule is:
+
+```text
+settings.enabled
+and model.api in ["openai-responses", "openai-codex-responses"]
+and model.id matches at least one settings.models pattern
+```
+
+Patterns are case-sensitive, match the complete model ID, and support `*` as the wildcard. Provider name is intentionally ignored.
+
+### Add model rules
+
+Edit `config.json` and add validated model-ID patterns:
+
+```json
+{
+  "enabled": true,
+  "models": [
+    "gpt-5.6-*",
+    "gpt-5.7-*",
+    "my-codex-model"
+  ]
+}
+```
+
+Examples:
+
+| Pattern | Matches | Does not match |
+|---|---|---|
+| `gpt-5.6-*` | `gpt-5.6-sol`, `gpt-5.6-terra` | `gpt-5.7-sol` |
+| `gpt-*-codex` | `gpt-5.6-codex` | `gpt-5.6-codex-mini` |
+| `my-codex-model` | exactly `my-codex-model` | `my-codex-model-v2` |
+
+Adding a pattern only changes routing; it does not prove that a model handles the Codex protocol correctly. Validate the model before adding it to the default allowlist. A matching model on `anthropic-messages`, `openai-completions`, or another unsupported API still uses Pi's native `edit`.
+
+Grammar support is not part of the route. When a provider does not emit Lark grammar tools, Pi falls back to a normal function tool, so `apply_patch` still runs there — only the grammar-enforced output shape is lost.
+
+Edit `config.json` in the standalone installed package, or `packages/codex-edit/config.json` inside an installed full toolkit, only if you need to change the default allowlist. Package updates can replace local edits. Set `"enabled": false` to disable all `apply_patch` routing. The implementation keeps both tools registered for session replay and changes only the active tool set on `session_start` and `model_select`.
+
+## Documentation
+
+- `summary.md`: benchmark summary and decision record.
+- `codex-edit-explainer.html`: self-contained interactive architecture and configuration explainer.
+- `TESTING.md`: deterministic test flow, regression fixtures, and latest baseline.
+
+The benchmark found equal final correctness in the fair 20-case comparison, with first editor-call success improving from 85% to 95%. Overall tool-call count and cache-inclusive token use were effectively unchanged, so the route stays limited to the GPT/Codex allowlist rather than replacing `edit` universally.

package/packages/codex-edit/TESTING.md

@@ -0,0 +1,20 @@
+# Codex Edit 测试方案
+
+## 流程
+
+1. `npm --prefix packages/codex-edit test`：运行 parser、matcher、路由和包结构测试。
+2. `pi -ne -e ./packages/codex-edit/extensions/codex-edit.ts`：加载权威入口；独立子包与根包 manifest 都指向该实现。
+3. `npm pack ./packages/codex-edit --dry-run`：检查独立 tarball。
+4. 确认 README 的协议示例、真实 parser 运行输出 `docs/screenshot.png` 和 `docs/demo.gif` 随包发布。
+
+## 用例数据
+
+- Add/Delete/Update/Move、多 hunk、BOM、CRLF、EOF 和 workspace escape。
+- 与 Codex 一致的 cursor 顺序匹配：重复 HTML section 与 Markdown `---`。
+- 多文件结构重构 patch 的解析，以及重复目标拒绝。
+- `gpt-5.6-*` glob、Responses API 路由和 disabled 配置。
+- 自定义精确规则与 `*` glob；相同 model ID 在不支持的 API 上必须回退到 Pi `edit`。
+
+## 最近验证结果
+
+当前基线为 12 个确定性测试全部通过；真实触发过 `Ambiguous ... regions found` 的重复 HTML/Markdown 形态已经加入回归集。发布前必须验证子包 tarball 和根包 tarball 都包含该入口。