@astralyn/pi 0.82.1 → 0.82.2

package/docs/compaction.md

@@ -34,6 +34,12 @@ contextTokens > contextWindow - reserveTokens
 
 By default, `reserveTokens` is 16384 tokens (configurable in `~/.pi/agent/settings.json` or `<project-dir>/.pi/settings.json`). This leaves room for the LLM's response.
 
+During an active tool-calling run, Pi evaluates this threshold after each complete tool batch, including the newly appended tool results, and before another provider request. If compaction succeeds, Pi rebuilds the context and continues the same agent run without inserting a continuation prompt. If compaction is cancelled, fails, has no safe cut point, or leaves the estimated retained context above the threshold, Pi fails closed before queue polling or another provider request. Because the upstream stateful Agent does not expose its low-level graceful turn-stop hook, this exceptional path ends with an explicit error/aborted assistant lifecycle; the preceding `compaction_end` event contains the underlying warning or failure.
+
+This between-tool-batch trigger is separate from **split-turn compaction** below: the trigger determines *when* compaction runs, while split-turn support determines *where* a very long turn can be cut.
+
+Before a new user prompt, Pi also refuses to send an existing context whose estimate remains above the threshold after compaction. This check happens before adding the new prompt itself. Reduce `keepRecentTokens`, remove unusually large retained content, or switch to a model with a larger context window before continuing.
+
 You can also trigger manually with `/compact [instructions]`, where optional instructions focus the summary.
 
 ### How It Works
@@ -42,7 +48,7 @@ You can also trigger manually with `/compact [instructions]`, where optional ins
 2. **Extract messages**: Collect messages from the previous kept boundary (or session start) up to the cut point
 3. **Generate summary**: Call LLM to summarize with structured format, passing the previous summary as iterative context when present
 4. **Append entry**: Save `CompactionEntry` with summary and `firstKeptEntryId`
-5. **Reload**: Session reloads, using summary + messages from `firstKeptEntryId` onwards
+5. **Reload and verify**: Rebuild context using the summary plus messages from `firstKeptEntryId` onwards, then verify the estimated retained context is below the auto-compaction threshold before continuing automatically
 
 ```
 Before compaction:
@@ -290,7 +296,7 @@ pi.on("session_before_compact", async (event, ctx) => {
 
   // branchEntries - all entries on current branch (for custom state)
   // reason - "manual" (/compact), "threshold", or "overflow"
-  // willRetry - whether the aborted turn is retried after compaction (overflow recovery)
+  // willRetry - whether overflow recovery intends to retry if compaction produces a safe retained context
   // signal - AbortSignal (pass to LLM calls)
 
   // Cancel:

package/docs/containerization.md

@@ -24,7 +24,7 @@ Use the [example extension](../examples/extensions/gondolin) when you want `pi`
 Setup:
 
 ```bash
-cp -R packages/coding-agent/examples/extensions/gondolin ~/.pi/agent/extensions/gondolin
+cp -R examples/extensions/gondolin ~/.pi/agent/extensions/gondolin
 cd ~/.pi/agent/extensions/gondolin
 npm install --ignore-scripts
 ```

package/docs/development.md

@@ -1,71 +1,68 @@
 # Development
 
-See [AGENTS.md](https://github.com/earendil-works/pi-mono/blob/main/AGENTS.md) for additional guidelines.
+See the repository [AGENTS.md](../AGENTS.md) for the distribution contract and coding conventions.
 
 ## Setup
 
 ```bash
-git clone https://github.com/earendil-works/pi-mono
-cd pi-mono
-npm install
+git clone https://github.com/ming-kang/pi
+cd pi
+npm install --ignore-scripts
 npm run build
+npm run check
 ```
 
+The repository is the standalone `@astralyn/pi` package. AI, Agent core, and TUI are installed as exact upstream npm dependencies; no sibling workspace build is required.
+
 Run from source:
 
 ```bash
-/path/to/pi-mono/pi-test.sh
+./pi-test.sh
 ```
 
-The script can be run from any directory. Pi keeps the caller's current working directory.
+The script can be invoked from any directory. Pi keeps the caller's current working directory. Use `./pi-test.sh --no-env` to clear provider credentials for the source run.
 
-## Forking / Rebranding
+## Package identity
 
-Configure via `package.json`:
+Distribution identity and configuration directory defaults are defined in `package.json`:
 
 ```json
 {
+  "name": "@astralyn/pi",
   "piConfig": {
-    "name": "pi",
     "configDir": ".pi"
+  },
+  "bin": {
+    "pi": "dist/cli.js"
   }
 }
 ```
 
-Change `name`, `configDir`, and `bin` field for your fork. Affects CLI banner, config paths, and environment variable names.
-
-## Path Resolution
-
-Three execution modes: npm install, standalone binary, tsx from source.
-
-**Always use `src/config.ts`** for package assets:
+## Path resolution
 
-```typescript
-import { getPackageDir, getThemeDir } from "./config.js";
-```
-
-Never use `__dirname` directly for package assets.
+Pi supports npm installation and `tsx` source execution. Always use `src/config.ts` helpers such as `getPackageDir()` and `getThemeDir()` for package assets; do not derive asset paths directly from `__dirname`.
 
-## Debug Command
+## Debug command
 
-`/debug` (hidden) writes to `~/.pi/agent/pi-debug.log`:
-- Rendered TUI lines with ANSI codes
-- Last messages sent to the LLM
+`/debug` (hidden) writes rendered TUI lines and the latest model messages to `~/.pi/agent/pi-debug.log`.
 
 ## Testing
 
 ```bash
-./test.sh                         # Run non-LLM tests (no API keys needed)
-npm test                          # Run all tests
-npm test -- test/specific.test.ts # Run specific test
+npm run check
+node node_modules/vitest/dist/cli.js --run test/specific.test.ts
+./test.sh  # complete isolated test suite
 ```
 
-## Project Structure
+Release CI runs the full suite on Ubuntu. Interactive UI changes should also be verified in a real terminal.
 
-```
-packages/
-  ai/           # LLM provider abstraction
-  agent/        # Agent loop and message types  
-  tui/          # Terminal UI components
-  coding-agent/ # CLI and interactive mode
+## Project structure
+
+```text
+src/                 runtime source
+ test/                automated tests and local test helpers
+ docs/                product and public API documentation
+ examples/            SDK and extension examples
+ docs/distribution/   standalone distribution documentation
+ scripts/             package maintenance scripts
 ```

package/docs/distribution/README.md

@@ -0,0 +1,34 @@
+# Distribution documentation
+
+This directory contains documentation owned by the standalone `@astralyn/pi` distribution. Product usage and public API documentation inherited from upstream coding-agent lives one level above under `docs/`.
+
+## User documentation
+
+- [Distribution overview](../../README.md) — package identity, installation, bundled features, and development entry points.
+- [Quickstart](../quickstart.md) — install, authenticate, and run a first session.
+- [User and API documentation](../index.md) — interactive mode, settings, customization, SDK, RPC, and platform notes.
+- [Extension API](../extensions.md) — write external TypeScript extensions.
+- [Theme API](../themes.md) — create and load custom themes.
+
+## Architecture and design
+
+- [Architecture and dependency boundaries](architecture.md)
+- [Native tool presentation](tool-presentation.md)
+- [Bundled theme design](themes.md)
+
+## Bundled extensions
+
+- [Catalog](extensions/README.md)
+- [deepwiki](extensions/deepwiki.md)
+- [question](extensions/question.md)
+- [rewind](extensions/rewind.md)
+- [router](extensions/router.md)
+- [statusline](extensions/statusline.md)
+- [subagent](extensions/subagent.md)
+- [todo](extensions/todo.md)
+
+## Maintainer documentation
+
+- [Upstream synchronization](maintenance.md)
+- [OIDC npm release checklist](release.md)
+- [Repository contract](../../AGENTS.md)

package/docs/distribution/architecture.md

@@ -0,0 +1,102 @@
+# Distribution architecture
+
+## Purpose
+
+This repository is a standalone personal distribution of Pi's coding-agent package. Its goals are to:
+
+- maintain only code that ships in `@astralyn/pi`;
+- consume AI, Agent core, and TUI from upstream npm releases;
+- keep native tool presentation, bundled workflow extensions, themes, and context-safety behavior local to this package;
+- avoid cross-workspace source changes and multi-package release coordination.
+
+## Package boundary
+
+The repository root is the npm package:
+
+```text
+src/                 coding-agent runtime
+ test/                coding-agent tests
+ docs/                product and API documentation
+ examples/            SDK and extension examples
+ docs/distribution/   distribution-owned documentation
+ package.json          @astralyn/pi
+ npm-shrinkwrap.json   development and published dependency lock
+```
+
+The runtime boundary is explicit and versioned in `package.json`:
+
+- `@earendil-works/pi-ai`
+- `@earendil-works/pi-agent-core`
+- `@earendil-works/pi-tui`
+
+These are exact registry dependencies. Their source is not copied into this repository and local verification resolves the same published packages that npm users install. A coding-agent synchronization that needs new upstream APIs must update all compatible dependency versions in the same change.
+
+Presentation-only metadata such as `toolGroup` uses coding-agent-local intersection types rather than changing `AgentTool`. The long-tool-loop compaction implementation uses the upstream stateful Agent's public `prepareNextTurnWithContext` callback for successful same-run continuation. Exceptional fail-closed paths are represented locally as explicit error/aborted lifecycle boundaries because the stateful Agent does not expose its low-level graceful turn-stop callback.
+
+## Core and extension boundary
+
+Pi core changes are reserved for behavior that must be global:
+
+- native tool call/result chrome and generic renderer fallback;
+- built-in renderer integration;
+- context-safety checks such as between-tool-batch auto-compaction;
+- globally configurable keybindings required by bundled UI.
+
+Personal workflow features remain self-contained extensions:
+
+```text
+src/extensions/
+├── deepwiki/
+├── question/
+├── todo/
+├── rewind/
+├── router/
+├── statusline/
+└── subagent/
+```
+
+They are registered as hidden `InlineExtension` entries in `src/extensions/index.ts`. No shared Fork framework, feature registry, or cross-extension internal API is used.
+
+## Configuration compatibility
+
+The command remains `pi`, and settings and sessions remain under `~/.pi/agent`. Built-in extensions store their first-class data alongside the normal agent data, including:
+
+```text
+~/.pi/agent/router.json
+~/.pi/agent/rewind/
+```
+
+No separate Fork configuration layer is introduced.
+
+## Themes
+
+`ice-cream-dark` and `ice-cream-light` are native theme assets under `src/modes/interactive/theme/`. The normal package build copies all theme JSON files into `dist`.
+
+## Upstream synchronization
+
+The `upstream` remote still points to `earendil-works/pi`, but upstream monorepo tags are not merged into this standalone branch. Synchronization extracts and reviews only `packages/coding-agent/**` from an upstream release tag, maps that subtree to the repository root, and updates exact registry dependency versions. See [maintenance.md](maintenance.md).
+
+Recurring review hotspots are:
+
+```text
+src/extensions/index.ts
+src/core/agent-session.ts
+src/core/keybindings.ts
+src/core/tools/*.ts
+src/modes/interactive/components/tool-execution.ts
+src/modes/interactive/interactive-mode.ts
+src/modes/interactive/theme/theme.ts
+package.json
+CHANGELOG.md
+```
+
+## Release model
+
+Only `@astralyn/pi` is published. Fork releases track the upstream `major.minor` line while using the patch number for this distribution's release sequence:
+
+```text
+upstream 0.82.x -> Fork 0.82.0, 0.82.1, 0.82.2, ...
+upstream 0.83.x -> Fork 0.83.0, 0.83.1, 0.83.2, ...
+```
+
+Tags use `pi-v<full-version>` so they do not collide with upstream `v<version>` tags. Ubuntu CI verifies the standalone package, and the manually dispatched publish workflow uploads the repository root with npm Trusted Publishing. No other package, binary release flow, model catalog, or update service is maintained here.

package/docs/distribution/extensions/README.md

@@ -0,0 +1,17 @@
+# Bundled extensions
+
+These are extensions shipped by the distribution. For the public API used to write external extensions, see the [Extension API documentation](../../extensions.md).
+
+The bundled extensions are maintained as self-contained TypeScript modules under `src/extensions/` and registered as hidden built-in extensions.
+
+| Extension | Tool or command | Documentation |
+|---|---|---|
+| `deepwiki` | `deepwiki` | [deepwiki.md](deepwiki.md) |
+| `question` | `question` | [question.md](question.md) |
+| `todo` | `todo`, `/todos` | [todo.md](todo.md) |
+| `rewind` | `/rewind`, `/tree` lifecycle | [rewind.md](rewind.md) |
+| `router` | `/router` | [router.md](router.md) |
+| `statusline` | Footer | [statusline.md](statusline.md) |
+| `subagent` | `subagent`, `/agents` | [subagent.md](subagent.md) |
+
+The extensions continue to use Pi's public Extension API. Keeping their distribution notes here does not merge their implementations into the coding-agent core.

package/docs/distribution/extensions/deepwiki.md

@@ -0,0 +1,62 @@
+# DeepWiki
+
+`deepwiki` is a Pi-native tool for querying DeepWiki's generated documentation for GitHub repositories.
+
+It is intentionally not a general MCP bridge. The extension exposes one dedicated tool with three fixed actions:
+
+| Action | Behavior |
+|---|---|
+| `structure` | List the generated wiki topics for a repository. |
+| `contents` | Read the generated wiki — one page via `page` (recommended), or everything when `page` is omitted (truncated past ~120k chars). |
+| `question` | Ask a focused question about a repository. |
+
+## Usage
+
+### Parameters
+
+- `action`: `structure`, `contents`, or `question`
+- `repoName`: one `owner/repo` string for `structure` and `contents`; for `question`, one repo as a string, or 2–10 repos as an array (comma-separated string also accepted)
+- `question`: required only for `action: "question"`
+- `page`: optional, only for `action: "contents"` — 1-based index or page title from `structure` (plain titles such as `Extension System`, not numbered outline lines like `4.4 …`). Leading outline numbers on titles are stripped when matching. Unknown `page` fails with available titles listed.
+
+`repoName` is normalized before validation (`owner/repo`, GitHub/DeepWiki URLs, JSON-array strings for multi-repo mistakes). `pageName`/`pageTitle` are accepted as `page` aliases. If `action` is omitted, defaults to `question` when a question is present, `contents` when `page` is present, else `structure`. Repositories not indexed on DeepWiki return repository-not-found errors — run `structure` first to detect that.
+
+### Strategy
+
+Recommended flow for studying a repo:
+
+1. `structure` — get the page outline.
+2. `contents` + `page` — read the specific pages you need, one at a time.
+3. Avoid `contents` without `page` (the full wiki) unless the wiki is genuinely small; oversized output is truncated at ~120k chars.
+4. `question` — when the wiki pages don't cover what you need, or directly for a quick answer without reading.
+
+Use DeepWiki when generated docs for public repositories are useful context:
+
+- Understanding an unfamiliar public repo's architecture, module layout, APIs, data flow, or extension points.
+- Researching reference implementations while designing or building a new feature or project.
+- Asking a focused question about how a public repo implements something.
+- Comparing patterns or extension surfaces across multiple public repos with `question` and a repo array.
+- Pulling a broad topic map with `structure` before deciding which part of a repo matters.
+
+The prompt is model-facing: when these conditions apply, the model should call the tool itself instead of telling the user to open DeepWiki manually.
+
+Avoid DeepWiki when the authoritative source is local or time-sensitive:
+
+- Local workspace files, private code, uncommitted changes, or exact current checkout state.
+- Latest releases, pricing, security advisories, schedules, or facts that need current primary-source verification.
+- Package names without a known GitHub repo; resolve the repo first instead of guessing.
+
+## Limits
+
+- A repository may not be indexed. DeepWiki can return that as normal text, so the extension treats repository-not-found messages as tool errors.
+- `contents` responses are truncated at a ~120k-character budget on `# Page:` boundaries (whole pages kept in order; at least the first page survives, cut mid-page if it alone exceeds the budget). A trailing notice reports shown/total pages, the full length, up to 20 omitted page titles, and points at `page` reads and `action: "question"` for the rest. Details carry `shownPages` / `truncatedChars` when this happens; `outputLength` always reflects the full untruncated response. Single-page reads set `requestedPage` / `pageIndex` instead and share the same budget.
+- Network requests time out after 45 seconds and surface as Pi tool errors.
+- Use local Pi tools (`read`, `grep`, `find`, `ls`) for workspace state. DeepWiki answers describe repository snapshots indexed by DeepWiki, not local uncommitted files.
+
+## Implementation notes
+
+DeepWiki's public MCP endpoint exposes exactly three operations: list a wiki's page titles, return the whole generated wiki as one document, and answer a question. There is no per-page fetch upstream — `page` is implemented by this extension: it fetches the full wiki (or reuses the 10-minute cache) and slices out the requested page locally. The first `contents` call for a repo pays the network cost; subsequent page reads within the cache window are instant and free.
+
+DeepWiki may return generated explanations with source-file citations and "related pages" links. The TUI uses a local renderer (`render.ts`) for a one-line collapsed summary and Markdown when expanded; Pi's default fallback would dump the full (often large) `content` text.
+
+Successful responses are cached in-process for 10 minutes, keyed by action, repo, and question. Failed, aborted, and timed-out requests are not cached. The cache stores the full response; `contents` truncation is recomputed per call, so cached and fresh calls return identical text.

package/docs/distribution/extensions/question.md

@@ -0,0 +1,59 @@
+# question — structured user questions
+
+Adds a `question` tool for asking one to four multiple-choice questions when the agent needs a user decision. A Pi-native take on AskUserQuestion: a lightweight custom dialog with concise transcript summaries and a bounded model-facing result.
+
+## Behavior
+
+- Each option requires a concise description of its consequence or trade-off. Questions, labels, descriptions, and previews have input-length limits so the dialog stays usable.
+- A single single-select question submits as soon as the user selects an option.
+- A multi-question flow advances after each single-select answer; multi-select uses `Space` to toggle choices and Enter to continue. Once every question is answered, a **Review answers** view requires explicit submission.
+- `←` / `→` switch between adjacent questions without wrapping. The tab bar marks answered questions and the Review state.
+- `Chat about this` is available after the choices. It returns a `needs_clarification` outcome so the model explains or reformulates instead of treating the user as having declined.
+- `Type something.` is appended automatically for custom answers. Authored options may not use reserved labels (`Other`, `Type something.`, `Chat about this`, `Next`).
+- `Tab` opens a note editor for the focused option; in multi-select, the option must be selected first. On the custom-answer row, it opens custom-answer input.
+- Multi-select custom answers stay on the `Type something.` row, are selected when saved, and can be toggled with `Space` without losing text.
+- `preview` shows focused single-select content beside the choices on wide terminals and beneath them on narrow terminals. Preview height is capped and reports hidden lines.
+- The dialog is available only in TUI mode. RPC, JSON, and print calls return a structured `no_ui` error rather than attempting a custom component.
+
+## Result contract
+
+`details` preserves structured state for rendering and session history:
+
+```ts
+{
+  answers,
+  outcome: "answered" | "cancelled" | "needs_clarification" | "error",
+  cancelled,
+  error?,
+}
+```
+
+Only `content` reaches the model. Successful results are numbered, clearly identify single/custom/multi answers, retain notes, and state when a preview was selected without echoing its full source. Model-facing output is capped at 12,000 characters; if it is truncated, the result instructs the model to ask a focused follow-up question. Notes and custom answers are capped at 4,000 characters in the dialog.
+
+The transcript uses a private `renderCall` / `renderResult` only to replace raw question JSON and model-oriented result text with concise user summaries. Pi retains its native tool shell, pending/error state, and collapsed/expanded behavior.
+
+## Limits
+
+- Questions, labels, descriptions, and previews have input-length limits so the dialog stays usable.
+- Notes and custom answers are capped at 4,000 characters.
+- Model-facing output is capped at 12,000 characters; if truncated, the result instructs the model to ask a focused follow-up question.
+- Only available in TUI mode. RPC, JSON, and print calls return a structured `no_ui` error.
+
+## Implementation notes
+
+- Uses Pi's native `ctx.ui.custom()` lifecycle; no state is shared with another extension.
+- The render cache is keyed by terminal width **and height**, because preview height depends on available rows and Pi resize only requests a render.
+- `validateQuestions` enforces uniqueness, reserved-label rejection, and text budgets beyond what the JSON schema can express.
+- Dialog navigation follows Pi's injected select/input keybindings where applicable; custom actions such as Space-to-toggle remain explicit in the footer.
+
+**Files:**
+
+- `constants.ts` — tool identity and model-facing prompt copy
+- `index.ts` — tool registration and execution
+- `dialog.ts` — interactive dialog, review, and discussion flow
+- `schema.ts` — params and semantic validation
+- `state.ts` — per-question dialog state helpers and answer ordering
+- `results.ts` — bounded model-result builders
+- `render.ts` — compact transcript summaries within Pi's native tool frame
+- `limits.ts` — UI and model-output budgets
+- `types.ts` — shared interfaces and the `OTHER_OPTION` sentinel

package/docs/distribution/extensions/rewind.md

@@ -0,0 +1,85 @@
+# rewind — checkpoints & rewind
+
+Per-edit file backups plus a `/rewind` settings menu. Instead of snapshotting the
+whole working tree, rewind backs up **only the files Pi's `edit`/`write` tools are
+about to change** — one `copyFile` before each edit. Cost is proportional to how
+many files Pi changed, never to project size, so it never blocks the session
+lifecycle (the old shadow-git design froze the UI in large multi-project
+directories) and storage stays tiny.
+
+## Behavior
+
+Per turn: `before_agent_start` opens a snapshot frame (re-recording every tracked
+file at its turn-start state, reusing the latest backup when unchanged);
+`tool_call(edit|write)` backs up each newly edited file *before* it lands;
+`agent_settled` persists the frame to the session JSONL as a `pi-rewind-snapshot`
+custom entry **only when files changed**. Using `agent_settled` (not `agent_end`)
+keeps auto-retry, overflow compaction-retry, and queued follow-ups in one logical
+turn — `agent_end` can fire while Pi still continues. Requires **Pi ≥ 0.80.4**
+(when `agent_settled` was added); older hosts never fire that event, so frames
+would not finalize. Entries survive `/reload` and compaction; the index is
+rebuilt from them on `session_start`.
+
+- **Scope (deliberate trade-off):** rewind covers edits made through Pi's built-in
+  `edit` and `write` tools. Files written by `bash` (redirects, codegen, `mv`) or
+  edited by hand outside Pi are **not** tracked — same boundary as Claude Code's
+  file-history. Rewind undoes *Pi's edits*, not arbitrary filesystem state.
+- **Time-travel is via `/tree`.** Navigating to a node whose turn changed files
+  prompts to restore them, listing the affected files (cwd-relative, up to 8
+  then *"+N more"*) under *"Restore 3 files to this point?  (+120 / −40)"*
+  when coarse line stats are available; choosing yes restores the work tree to
+  that turn's start state. Nodes with no file changes navigate silently. Only
+  files that actually differ are rewritten. Line totals are a bag-of-lines
+  estimate (capped at 1 MB per file), not a full Myers diff.
+- **`/rewind` is a settings + storage menu**, not a restore picker:
+  - toggle rewind on/off,
+  - set the auto-clean retention window,
+  - inspect storage and prune (clean aged + orphaned / remove orphaned / remove
+    all except current).
+- **New files** created by `write` are tracked with a "did not exist" marker, so
+  rewinding deletes them.
+- **Resume/fork** hard-links the prior session's backup blobs into the new
+  session (falling back to copy), so rewind keeps working without duplicating
+  storage.
+
+## Storage & cleanup
+
+- **Layout:** `~/.pi/agent/rewind/`
+  - `config.json` — `{ enabled, retentionDays, maxSnapshots }`
+  - `backups/<sessionId>/<sha256(relpath)[:16]>@v<n>` — backup blobs (flat, hashed
+    names keep paths short on Windows; mode preserved)
+- **Auto-clean:** at `session_start`, backup directories older than
+  `retentionDays` (default **30**, set in `/rewind`) are reclaimed, plus an
+  **orphan sweep** of directories whose session id has no session JSONL (crashed
+  sessions). The GC is time-boxed and deletion-capped so it never slows startup.
+- The former `pi-config` storage layout is **not** read or migrated by this
+  engine. Remove any old `~/.pi/agent/pi-config/` data manually if it is no
+  longer needed.
+
+## Limits
+
+- Covers edits made through Pi's built-in `edit` and `write` tools only. Files written by `bash` or edited outside Pi are not tracked.
+- A backup failure is swallowed — the edit proceeds without checkpointing rather than blocking the tool.
+- `/rewind` on its own does not restore files. Restoration uses `/tree` — navigate to a turn and confirm the prompt.
+- Restore is coarse: only files that differ are rewritten, but line totals are a bag-of-lines estimate (capped at 1 MB per file), not a full Myers diff.
+
+## Implementation notes
+
+- **Never blocks the edit.** Backup runs before the write lands; a backup failure is swallowed so the session never stalls.
+- **Restore safety.** `applySnapshot` only rewrites files that differ and degrades gracefully on unreadable backups.
+- **Change detection.** A file is re-backed-up only when its stat or content differs from the latest backup. Content comparison streams in 64 KiB chunks instead of buffering whole files up to the 25 MB cap.
+- **Config is memory-cached.** `config.json` is re-read on `session_start` and updated in memory when `/rewind` saves.
+- **Restore path is single-scan.** The `/tree` confirm pass caches changed absolute paths; IO is concurrency-capped (16).
+
+**Files:**
+
+- `index.ts` — lifecycle hooks (`tool_call`, `before_agent_start`, `agent_settled`, `session_start`, `session_before_tree`/`session_tree`, `session_shutdown`) and the `/rewind` command
+- `engine.ts` — the file-history backup engine (track / snapshot / apply / resume-migrate), ported from Claude Code's file-history
+- `snapshot.ts` — persisted snapshot data shapes (pure)
+- `config.ts` — load/save `rewind/config.json`
+- `gc.ts` — age + orphan storage reclamation; storage inventory for the menu
+- `menu.ts` — the `/rewind` settings + storage menu
+- `restore.ts` — `/tree`-target → snapshot matching and restore
+- `paths.ts`, `text.ts`, `tool-path.ts` — private helpers owned by this plugin
+
+Architecture informed by oh-my-pi (GPL-3.0) and Claude Code's file-history; independent implementation.

package/docs/distribution/extensions/router.md

@@ -0,0 +1,139 @@
+# `router` — Codex-style API relays
+
+`/router` connects Pi to OpenAI-compatible API relays — self-hosted gateways such as sub2api, CPA, or codex2api, and any similar proxy — using a **Codex-shaped** Responses client.
+
+Configuration lives at `~/.pi/agent/router.json`.
+
+Providers are registered at extension load via `pi.registerProvider` (config form + `streamSimple`). They do **not** go through `models.json`. This follows Pi's documented custom-provider path ([providers.md](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/providers.md), [custom-provider.md](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/custom-provider.md)): the stream wraps the built-in `openAIResponsesApi()` from `@earendil-works/pi-ai/compat` (same approach as the GitLab Duo example), then reshapes the request for Codex-style relays.
+
+---
+
+## Usage
+
+```
+/router          Browse relays
+/router add      Add a relay
+/router reload   Re-register from disk
+/router <id>     Open a relay
+```
+
+### UI map
+
+```
+API relays                  ← relays first; add / reload at bottom
+ └─ Relay · {id}            ← models · base URL · API key · remove
+     └─ Models              ← Fetch catalog + one row per configured model
+         └─ {model id}      ← display name · thinking levels
+```
+
+Edits **auto-save** to `router.json` and re-register the provider. There is no separate Save step — Back never discards committed field or model changes.
+
+Nested multi-select (catalog) and the thinking-level editor require **Ctrl+S to apply** that screen's working set. If you press Esc with unsaved toggles, the footer warns once; pressing Esc again discards that screen only.
+
+### Add flow
+
+1. **Name** — provider id (e.g. `my-relay`); appears as `my-relay/gpt-5.6-sol` in `/model`
+2. **Base URL** — usually ends with `/v1`
+3. **API key** — literal `sk-…` or `$ENV_VAR`
+4. **Fetch models** — `GET {baseUrl}/models`
+5. **Select** — Space to toggle, Ctrl+S to apply (TUI); the relay is then written immediately
+
+Each selected model gets these defaults:
+
+| Field | Default |
+|:-:|:-:|
+| `name` | **Omitted** — `/model` shows the model **id** |
+| `reasoning` | `true` |
+| `input` | `text` + `image` |
+| `contextWindow` | 272000 |
+| `maxTokens` | 128000 |
+| `thinkingLevelMap` | off…medium hidden; high / xhigh / max on |
+
+### Customize models
+
+Relay → **Models** → pick a model:
+
+- **Display name** — optional label (e.g. `Luna`). Leave empty to show the id. Saved on confirm.
+- **Thinking levels** — toggle each Pi level between **on** and **hidden** (`null`). Ctrl+S applies, then auto-saves the relay.
+
+---
+
+## Config shape
+
+```jsonc
+{
+  "version": 1,
+  "relays": [
+    {
+      "id": "my-relay",
+      "baseUrl": "https://relay.example/v1",
+      "apiKey": "sk-…",
+      "models": [
+        {
+          "id": "gpt-5.6-sol",
+          "reasoning": true,
+          "input": ["text", "image"],
+          "contextWindow": 272000,
+          "maxTokens": 128000,
+          "thinkingLevelMap": {
+            "off": null,
+            "minimal": null,
+            "low": null,
+            "medium": null,
+            "high": "high",
+            "xhigh": "xhigh",
+            "max": "max"
+          }
+        },
+        {
+          "id": "gpt-5.6-luna",
+          "name": "Luna",
+          "reasoning": true,
+          "input": ["text", "image"],
+          "contextWindow": 272000,
+          "maxTokens": 128000
+        }
+      ]
+    }
+  ]
+}
+```
+
+There is **no migration** from any older models-manager config. Add relays with `/router add` (or edit `router.json` and run `/router reload`).
+
+---
+
+## Limits
+
+- SSE only — no Codex WebSocket or zstd-compressed request body.
+- Catalog probe expects OpenAI-style `{ data: [{ id }] }` response format.
+- Empty model list → provider is not registered (nothing appears in `/model`).
+- Body is Codex-oriented for transparent gateways; auth and URL remain Platform Responses (`sk-` + `/responses`).
+- Same relay + same model: tool/reasoning multi-turn matches Codex-style Responses. Switching model or provider mid-session may normalize tool-call ids more strictly (upstream allow-list); this is not worked around here.
+- Interactive `/router` requires a TUI (`ctx.hasUI`); otherwise a warning is shown and no dialog opens.
+- Catalog multi-select and thinking editor are apply-on-Ctrl+S screens; only those screens can be discarded with double Esc.
+
+## Implementation notes
+
+**Request shape.** `stream.ts` calls `openAIResponsesApi().streamSimple` with a model configured as Platform Responses (`api: "openai-responses"`). The `onPayload` callback reshapes the body toward Pi's built-in `openai-codex-responses` format, with `store: false`, system prompt as `instructions`, `parallel_tool_calls: true`, and rejected fields such as `prompt_cache_retention` and `temperature` dropped.
+
+Session affinity headers use hyphenated form (`session-id`, `x-client-request-id`). Compat settings: `sessionAffinityFormat: "openai-nosession"`, `supportsLongCacheRetention: false`. Originator header: `codex`.
+
+**Differences from ChatGPT Codex OAuth.** Auth uses Bearer `sk-…` (not OAuth JWT), endpoint is `{baseUrl}/responses` (not `/codex/responses`), transport is SSE only (no WebSocket or zstd), and `OpenAI-Beta` is not set. These match **sk- relays**, not the official ChatGPT backend.
+
+**Multi-turn tool calls.** On a fixed relay + fixed model, tool-call ids preserve the Responses form and replay like Codex. Pi only rewrites ids across model boundaries. Staying on one model for long tool + reasoning sessions avoids id sanitization.
+
+**Files:**
+
+| File | Role |
+|:-:|:-:|
+| `index.ts` | Async factory: load config, register providers, handle `/router` commands |
+| `store.ts` | `router.json` read / write |
+| `register.ts` | `registerProvider` / unregister |
+| `stream.ts` | Wraps `openAIResponsesApi` + payload reshape |
+| `probe.ts` | `GET …/models` catalog fetch |
+| `presets.ts` | 272k defaults + thinking-level map helpers |
+| `dialog.ts` | Selectors, multi-select, thinking editor (dirty Esc warning) |
+| `ui.ts` | Command flows; auto-save on relay mutations |
+| `constants.ts` | Command name, defaults, `router-codex` API tag |
+| `types.ts` | Config types |