pi-extended-agent 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 1.0.0
+
+First release of Pi Extended Agent, bundling Pi 1.4.0.
+
+- Shared terminal interface for configuration, models, effort, permissions, skills, usage, status, and context.
+- Automatic project memory with a short MEMORY.md index, topic editing, and shared Git worktree storage.
+- Persistent planning with a read-only tool barrier, explicit execution approval, and step tracking.
+- Session, project, and global prompt additions that preserve Pi's native system prompt.
+- Shift+Tab switches normal/plan modes; Shift+Left/Right adjusts supported reasoning effort.
+- Per-action tool approval and read-only permissions, including nested tool calls.
+- Managed engine updates with compatibility checks, rollback, and background update notices.
+- Native Pi authentication, model discovery, session history, and automatic compaction.
+- English Nextra documentation with static search and a GitHub Pages deployment workflow.
+- Repository instructions in AGENTS.md and a documented npm release procedure.
+- Reserved memory index identifier to prevent note loss on case-insensitive filesystems.

package/README.md

@@ -1,3 +1,370 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <a href="https://pi.dev">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="ui/pi-logo.svg">
+      <img src="ui/pi-logo-light.svg" alt="Pi logo" width="128" height="128">
+    </picture>
+  </a>
+</p>
+
+<h1 align="center">Pi Extended Agent</h1>
+
+<p align="center">
+  A personal Pi setup with a quiet terminal interface.<br>
+  One package. The <code>pi</code> command. Managed engine updates.
+</p>
+
+<p align="center">
+  <a href="https://svjszn.github.io/pi-extended-agent/">Documentation</a> &nbsp; / &nbsp;
+  <a href="#installation">Installation</a> &nbsp; / &nbsp;
+  <a href="#already-have-pi">Existing Pi users</a> &nbsp; / &nbsp;
+  <a href="#updates">Updates</a> &nbsp; / &nbsp;
+  <a href="#development">Development</a> &nbsp; / &nbsp;
+  <a href="#contributing">Contributing</a>
+</p>
+
+## At a glance
+
+| Component | Version / default |
+| :--- | :--- |
+| Package | `pi-extended-agent` · `1.0.0` |
+| Bundled Pi fallback | `1.4.0` |
+| Managed engine | Updated separately with `pi update` |
+| Startup model | Selected by the active Pi engine from its settings and catalog |
+| Node.js | `>=22.19.0` |
+
+Pi provides the agent loop, tools, authentication, and sessions. This package provides the CLI entry point, interface extensions, and engine updater. Pi is installed automatically; users do not install it separately.
+
+```text
+  ██████     pi coding agent v1.4.0
+  ██  ██     Your model with medium effort
+  ████  ██   ~/project
+  ██    ██
+
+  ...conversation...
+
+  ────────────────────────────────────────────────────────────
+  >
+  ────────────────────────────────────────────────────────────
+  auto mode
+```
+
+The header shows the actual engine version, model, effort, and current working directory. Short conversations sit above the input; the footer shows the permissions mode at the left: `auto mode` for full access, `ask mode` for approvals, or `read only`.
+
+The terminal tab is titled **Pi Coding Agent**. Chat messages and input align with the logo's two-column inset. User messages have a subtle dark gray background with light text; assistant replies keep the terminal background. Below the input, **auto mode** appears on the left and current context usage on the right, for example `~24k / 200k · 12% context`. Narrow terminals show a shorter indicator.
+
+## Installation
+
+You need **Node.js 22.19.0 or newer** and npm. On Windows, Git for Windows supplies the Bash shell used by Pi's default shell tool. Existing Pi users should read the migration instructions below first.
+
+### From npm
+
+Install the package and start the agent:
+
+```sh
+npm install -g --ignore-scripts pi-extended-agent
+pi
+```
+
+The package also provides `pi-extended-agent` as an alternative command. Both launch the same agent.
+
+### From source
+
+```sh
+git clone https://github.com/svjszn/pi-extended-agent.git agent
+cd agent
+npm ci --ignore-scripts
+npm run build
+npm link --force --ignore-scripts
+pi
+```
+
+**`npm ci` installs the bundled Pi dependency. `npm link` connects the global commands to this checkout.** Keep the checkout in place while using the link. To run without linking: `npm run pi`.
+
+### Already have Pi?
+
+Upstream Pi and this package both provide a command named `pi`. npm may reject the new installation with `EEXIST` rather than replace the existing command.
+
+The recommended migration for an npm-installed upstream Pi is:
+
+```sh
+npm uninstall -g @earendil-works/pi-coding-agent
+npm install -g --ignore-scripts pi-extended-agent
+```
+
+For a linked source checkout, replace the second command with `npm link --force --ignore-scripts` from that checkout, or install a locally packed `.tgz` file.
+
+If you linked an early checkout under the old name `local-coding-agent`, run `npm unlink -g local-coding-agent` before linking this renamed package.
+
+**Your existing `~/.pi/agent/` profile is preserved**, including sign-in, personal settings, and sessions. The upstream package is removed; its user data is not.
+
+An explicit takeover is also possible with `npm install -g --force --ignore-scripts pi-extended-agent`, but it leaves the upstream package installed. Reinstalling that upstream package later can claim `pi` again. Removing it first avoids that ambiguity.
+
+For a standalone Pi installation or a different npm prefix, inspect the shell's command resolution instead of deleting executables manually:
+
+```powershell
+# PowerShell
+Get-Command pi -All
+```
+
+```sh
+# Bash / Zsh
+type -a pi
+```
+
+If another installation appears earlier on PATH, launch `pi-extended-agent` directly while fixing PATH or removing the old installation through its own package manager.
+
+### Sign in and verify
+
+Run `pi` from the project you want to work on. Inside Pi:
+
+1. Enter `/login`, select ChatGPT/Codex, and complete the browser sign-in if needed. Existing standard-profile credentials are reused.
+2. Enter `/status` to check the active Pi version, selected model, and authentication status. `/config info` shows configuration paths.
+
+If the selected provider has no configured authentication, startup shows a warning and the header keeps a `/login PROVIDER` hint. The hint disappears after sign-in. This checks local configuration only; it does not verify token validity with the provider.
+
+Each computer needs its own sign-in. The standard profile is `~/.pi/agent/`, normally `C:\Users\YOUR_NAME\.pi\agent\` on Windows. `PI_CODING_AGENT_DIR` remains available for an explicitly chosen alternative profile.
+
+## Updates
+
+### Update the internal Pi engine
+
+```sh
+pi update
+```
+
+The launcher checks the latest upstream release through npm, installs it into a separate managed version directory, and checks our extension loading, terminal layout, and Escape handling. The version check uses your npm registry, proxy, and certificate settings, with a 30-second request timeout and one retry. These compatibility checks do not call a model. Only after they pass does it switch the active engine. A failed download, installation, or compatibility check leaves the previous engine selected.
+
+**Engine updates do not install a global upstream Pi package, change the global command, edit this repository, or touch your credentials.** Restart Pi after a successful update.
+
+| Command | Behavior |
+| :--- | :--- |
+| `pi update` | Install the latest Pi release and activate it if compatibility checks pass |
+| `pi update --check` | Show the active and latest engine versions |
+| `pi update --to 1.4.0` | Install a specific engine version |
+| `pi update --offline` | Check and activate the newest complete cached engine |
+| `pi update --rollback` | Restore the previous engine, or the bundled fallback |
+| `pi update --all` | Update the engine, then configured extension packages |
+| `pi update --models` | Refresh model catalogs through Pi |
+| `pi update --extensions` | Update configured extension packages through Pi |
+
+The managed engine lives under `~/.pi/pi-extended-agent/`, separately from the authentication profile. Version directories remain available for rollback. `active.json` selects the active release. The bundled dependency is used until an updated engine is activated.
+
+At interactive startup, this package checks npm in the background and shows `Pi VERSION is available … Run pi update` when a newer engine exists. Successful checks are cached for 12 hours under the managed runtime directory. The check uses your npm registry settings, has a short timeout, and never blocks the editor. Offline mode (`PI_OFFLINE`) skips it; network failures stay quiet. Print and RPC sessions do not check. Updates are installed only when you run `pi update`.
+
+For testing or custom storage, set `PI_EXTENDED_RUNTIME_DIR`. The launcher disables upstream self-update notices because updates belong to this package's updater; the notification above points to our managed update command. It does not automatically switch engines at startup.
+
+### Update Pi Extended Agent itself
+
+```sh
+npm install -g --ignore-scripts pi-extended-agent@latest
+```
+
+For a linked source checkout:
+
+```sh
+git pull
+npm ci --ignore-scripts
+npm run build
+```
+
+Restart Pi afterward. Source edits do not require relinking. If you move the checkout or change the CLI entry points, run `npm link --force --ignore-scripts` again.
+
+## Daily use
+
+### Commands
+
+| Command | Shows |
+| :--- | :--- |
+| `/usage` | Active provider, available account usage limits, and local reset times |
+| `/stats` | Annual activity calendar and local history statistics |
+| `/status` | Pi version, session ID, login method, active model, MCP servers, and tools |
+| `/config` | Configuration overview with an integrated Preferences tab |
+| `/context` | Context window map, estimated breakdown, loaded instructions, skills, and active tools |
+| `/effort [level]` | Choose reasoning effort or set a supported level directly |
+| `/permissions [mode]` | Choose full access, per-action approval, or read-only agent tools |
+| `/memory` | Inspect, edit, delete, and toggle automatic project memory |
+| `/plan [goal]` | Research a task, edit its plan, and explicitly approve execution |
+| `/prompt [scope]` | View the native system prompt and edit session, project, or global additions |
+| `/model [query]` | Search and select a model in the shared full-screen interface |
+| `/skills [query]` | Installed skills, skills.sh search, preview, and installation |
+
+The commands open full terminal screens below the Pi header, aligned to its two-column inset. They have no enclosing border. Read-only screens show `esc to close` in the input row; `/skills` uses that row for search and filtering. Usage bars show the remaining allowance; configuration values align in columns. The shared white and gray palette lives in `ui/theme.ts`, ready for a future `/theme` command. Press **Escape** or **Enter** to close a read-only screen. Scroll with **↑/↓**, **Page Up/Down**, **Home/End**, or the mouse wheel. Opening a viewer does not call a model. Starting `/plan <goal>` or choosing Execute sends the corresponding task to the agent.
+
+`/usage` names the active provider. It has account-usage readers for ChatGPT OAuth (`openai-codex`) and Claude OAuth (`anthropic`), using credentials resolved by Pi. It does not import credentials from a separate Claude Code installation. The Claude reader has fixture coverage; it has not been verified with a live Claude account. These account backends are not public API contracts, and availability depends on account access and OAuth scopes. Limits are fetched only when the screen opens; remaining allowances are never estimated from local token counts. API keys, unsupported providers, missing data, and network errors show an explicit unavailable state. Credentials and usage responses are not copied or stored.
+
+`/stats` shows an annual calendar above two columns of statistics, with **All time / Last 7 days / Last 30 days** filters. Switch filters with **Tab / Shift+Tab** or **←/→**. Filters affect the statistics; the calendar always covers the latest year and crops to recent weeks in a narrow terminal. Intensity follows recorded daily tokens, with prompt counts as a fallback when token data is absent.
+
+Statistics come from the active profile's local sessions, including the current session and a custom session directory. They include favorite model (by assistant response count), recorded tokens, session count, active days, most active day, and streaks. Session length is the span between its first and last recorded messages, including idle gaps. Token totals include reported tool, compaction, and summary usage; reasoning tokens are not added twice. Forked entries count once. Statistics cover all recorded history or the selected period, while the calendar uses local dates for the latest 365 days. Activity on other computers or in the Codex app is not included.
+
+`/config` opens the original Configuration overview, with Current session, Saved preferences, and Files in aligned columns. Press Tab to switch to the integrated Preferences tab in the same full-screen panel, keeping the header, footer, inset, and white/gray palette. Preferences include all settings previously available as `/settings`: themes, model defaults, effort defaults, transport, compaction, image handling, terminal behavior, and warnings. Use arrow keys to navigate, Enter to edit, and type to filter. Escape backs out of a submenu, returns to the overview, then closes the screen. Tab switches between the overview and preferences. Native save callbacks apply settings to the session; changing TUI mode briefly closes and reopens the panel so Pi can switch renderers safely. `/config info` remains an alias for the overview. Project preferences respect Pi's trust decision, and credentials are excluded. In print/RPC mode, `/config` shows the read-only overview.
+
+The command menu omits `/settings`, `/tree`, `/thinking`, `/scoped-models`, `/import`, `/export`, `/share`, `/bug`, `/copy`, `/session`, `/changelog`, `/hotkeys`, `/fork`, `/clone`, `/trust`, `/about-agent`, `/llama`, and `/mcp`. These commands are also rejected when entered manually. Use `/config` for preferences, `/effort` for session reasoning effort, and `/status` for engine and session information. The runtime adapter applies to both bundled and managed engines and is checked before engine updates activate. It does not modify upstream package files.
+
+`/status` shows the active Pi engine version, session ID, provider login method, model, MCP servers, and active tool names. The model appears with MCP and tools, and shows only its model ID. Login reflects configured credentials without resolving or refreshing them. MCP metadata combines the engine's configuration reader with extension registrations and tool namespaces; project settings respect Pi's trust decision. Registered tools do not prove a live connection. Engines without a native MCP configuration reader show the servers inferred from registered tools and extensions.
+
+`/effort` opens a selector containing only levels supported by the current model, as reported by Pi's `getSupportedThinkingLevels(model)`. Choose with **↑/↓** or **Tab / Shift+Tab**, apply with **Enter**, or cancel with **Escape**. `/effort high` sets a level directly; argument completion follows the selected model. Changes apply to the current session through Pi's native thinking-level API. The current level comes from `pi.getThinkingLevel()` and appears right-aligned on a separate line above the input. It stays synchronized with native shortcuts and model changes. The label is hidden when the terminal is too narrow to fit its name.
+
+`/model` uses the same header, two-column inset, borderless body, monochrome palette, and input dock as the other command screens. Search stays in the input row; the current model uses `●` and the highlighted row is bold. Native model discovery, scoped-model switching with Tab, selection with Enter, and saving the default with Ctrl+S retain Pi's behavior. Escape cancels the selector and its background catalog refresh. Model-screen compatibility is checked before activating an engine update.
+
+### Agent permissions
+
+Open `/permissions` to choose a mode in the shared white/gray full-screen interface, or set it directly:
+
+```text
+/permissions full
+/permissions ask
+/permissions read-only
+```
+
+- **Full access** preserves the previous behavior: tools execute without this package's approval prompts. It is the default for new sessions.
+- **Ask before actions** allows Pi's built-in `read`, `find`, `grep`, and `ls` without prompting. File changes, shell commands, and other tools (including MCP and nested tools) require approval for each call. TUI approval screens show the complete tool input with scrolling, start on Deny, and support Allow once. RPC uses Pi's confirmation request; a client must respond. Without an interactive UI, calls requiring approval are denied.
+- **Read only** permits those four built-in reading/search tools. Write, edit, Bash, PowerShell, and external tools are blocked. External tools' read-only hints do not grant permission. Our own memory reads and plan updates are also allowed: they only access the app's project notebook. Memory saves and deletes follow the normal permissions policy.
+
+The selection is saved as session metadata and restored on resume or reload. It applies to subsequent tool calls; it does not stop a tool already running. Pending approval dialogs are cancelled when the mode changes or the session shuts down. The footer reflects the selected mode. These controls govern agent tool calls, including calls through other tools; they are not an operating-system sandbox or a project-directory boundary. Explicit user shell commands (`!` / `!!`), command actions such as installing skills, and extensions' direct code execution keep their existing behavior. Project trust remains separate.
+
+### Automatic project memory
+
+Automatic memory is enabled by default. During normal work the agent can save useful preferences, corrections, environment facts, and project decisions through `project_memory`. It does not run a separate model request or an extraction pass after each message. Source-control history, transient progress, and credentials do not belong in memory. Common credential patterns are rejected when saving.
+
+`/memory` opens the project notebook. **Tab** changes topics; **e** edits the selected topic, **n** creates one, **d** deletes it after confirmation, and **t** toggles automatic memory. Document editors use **Enter** for newlines, **Ctrl+S** to save, and **Escape** to discard changes. Direct commands include `/memory on`, `/memory off`, `/memory read TOPIC`, `/memory edit TOPIC`, `/memory add`, and `/memory delete TOPIC`. Disabling memory preserves notes but stops loading and agent access until re-enabled.
+
+Notes live under the active profile's `pi-extended/projects/PROJECT_KEY/memory/`. Git worktrees of the same repository share a notebook; separate repositories are isolated. Outside Git, the canonical working directory identifies the project. The short `MEMORY.md` index contains at most 32 summaries (160 bytes each); each topic has up to 12 KB of details read by the model only on demand. The notebook stays outside the source tree and persists across sessions. These local files are sent to the selected model when loaded into context.
+
+### Plan before executing
+
+**Shift+Tab** in the chat input switches between normal mode (`auto mode` with Full access) and `plan mode`. Switching out pauses and preserves the plan; switching back restores the draft. It keeps your input text, effort, and permission choice. It does not start execution. Finish the current run and queued messages before switching. **Shift+Left/Right** decreases/increases reasoning effort through the current model's supported levels, stopping at the lowest/highest level; `/effort` also remains available. Inside command screens, Shift+Tab keeps its usual navigation behavior.
+
+Use `/plan <goal>` to start research, or open `/plan` and press **s** to enable planning before describing the task. The agent saves the goal, steps, affected areas, and checks with `update_plan`. The footer shows `plan mode`. A tool hook allows only built-in reading/search tools, memory reads, and our internal plan updates. Available built-in `find`, `grep`, and `ls` tools are temporarily activated so research works without shell access; the previous selection is restored on execution or cancellation. Changes, external tools, nested mutation calls, and shell commands are blocked even under Full access. Interactive/RPC user shell commands are also blocked while planning.
+
+Review the result with `/plan`, edit with **e** or `/plan edit`, and explicitly choose **x** or `/plan execute` to start implementation. Only a user command can approve execution. The existing `/permissions` mode stays in force; executing a plan never grants Full access. `/plan cancel` leaves planning without starting work. Plans are saved per session in the profile, survive compaction, and restore when that session is resumed or reloaded. During execution the agent tracks pending, in-progress, and completed steps; changing the approved scope requires another edit and approval.
+
+### System prompt additions
+
+`/prompt` shows a preview for the next run, the native Pi prompt, and **session**, **project**, and **global** additions. Use **Tab** to choose a section, **e** to edit additions, or **d** to clear them after confirmation. Native Pi instructions remain intact. `/prompt session`, `/prompt project`, and `/prompt global` open the corresponding editor directly; `/prompt project Use npm for this repository.` saves text without opening an editor.
+
+Global and project additions live in the active profile; session additions are stored in Pi session metadata. Additions are limited to 12 KB per scope and apply on the next run, in global → project → session order. Other extensions can add their own instructions at run start. Pi's existing system-prompt files, instruction discovery, and automatic compaction remain in use; this package does not replace them.
+
+### Inspect context
+
+`/context` shows a white and gray map of the active model's context window, followed by estimates for the system prompt, tool definitions, loaded instructions, skill descriptions, messages, and tool results. Free space and the configured compaction buffer appear separately. The screen also lists instruction paths, skill names, active tool names, and compaction settings. It reads in-memory session data without making a model request or adding content to the conversation.
+
+The total follows Pi's current-window estimate, based on its latest valid assistant usage and estimates for newer messages. Before the first response, the indicator also estimates the prompt and active tool schemas. These are not cumulative billed tokens. `~` marks estimated values. Categories use Pi's character-based heuristic and reconcile to the total; unclassified differences appear as **Other context**. Individual source lists show raw estimates. Provider formatting, images, and extension hooks can affect final request sizes.
+
+Compacted history and inactive branches are excluded. After compaction, Pi may report an unknown total until the next response; the footer shows `—` instead of retaining the previous usage. The indicator refreshes on session, model, message, and compaction events, without recounting tokens on every terminal frame. Use Pi's native `/compact` to summarize the current session or `/new` to begin a fresh one.
+
+### Find and install skills
+
+Open `/skills` for **Installed** and **Search** tabs, or enter `/skills react` to search immediately. The installed list comes from skills already loaded by Pi, including shared folders, configured paths, and packages. Type to filter it. In Search, type at least two characters to search [skills.sh](https://skills.sh/). A filled circle **●** marks a skill available in the current session; an empty circle **○** marks one that is not loaded. Results also show the source repository and install count. Descriptions appear when the catalog supplies them; the preview reads the description and full `SKILL.md` from GitHub.
+
+- **Tab / Shift+Tab** switches tabs; **↑/↓** selects a skill; **Enter** opens its preview.
+- In a new skill's preview, **Tab / ←/→** chooses **This project** or **All projects**, then **Enter** installs.
+- **Page Up/Down** and **↑/↓** scroll the preview; **Escape** goes back, closes the manager, or cancels an active download.
+- After installation, **Enter** returns to the chat and reloads Pi's skills without restarting the process.
+
+Project skills go to `.pi/skills/`; global skills go to the active profile's `skills/` folder (`~/.pi/agent/skills/` by default). Project installation requires Pi's existing trust decision; choose a global installation or reopen Pi and approve the project when prompted. `--no-skills` and Pi's resource-discovery settings continue to apply.
+
+The first version supports public GitHub skills from the catalog. Preview and installation use one pinned commit. The selected skill's directory is downloaded with its references, scripts, and assets, and each file is verified against its Git blob hash. Installation does not run scripts or install the skill's dependencies. Existing directories are never replaced. A failed or cancelled download is cleaned up before activation. Each installed folder includes `.pi-extended-source.json` with its source revision for future management.
+
+Large repositories, symlinks, submodules, conflicting filenames, and skills over 200 files, 2 MiB per file, or 25 MiB total are not supported in this first version. Search uses the same public catalog endpoint as the Skills CLI; GitHub's unauthenticated request limits also apply to previews. No model-provider credentials are sent to either service. `/skills` in print/RPC mode is read-only: it lists or searches, without installing.
+
+Use `/model` to switch models and `/effort` to choose reasoning effort. Model selection follows the active Pi engine's settings and catalog, including its provider defaults. This package does not inject a fixed model ID, so engine updates can change the provider default without leaving an obsolete CLI override. Explicit CLI model/provider choices, `--models`, and resumed sessions keep Pi's native behavior. Choosing a custom model ID explicitly remains supported by Pi. Before sign-in, Pi may have no model selected; the header shows a `/login` hint.
+
+Press **Escape** to exit when the input is empty and Pi is idle. During work, in menus, and in autocomplete, Escape keeps its normal cancellation behavior. An unsent draft prevents Escape from exiting. **Ctrl+D** remains available.
+
+```sh
+pi --continue
+pi --model openai-codex/gpt-6-astra
+pi --thinking medium
+pi --tui-mode regular
+pi --no-extensions
+```
+
+## Development
+
+| File | Responsibility |
+| :--- | :--- |
+| [`bin/pi.mjs`](bin/pi.mjs) | Stable npm entry point for installed and linked commands |
+| [`bin/main.ts`](bin/main.ts) | Own the commands and launch the active Pi engine |
+| [`bin/runtime.ts`](bin/runtime.ts) | Resolve bundled and managed engine versions |
+| [`bin/update.ts`](bin/update.ts) | Install, activate, and roll back engines |
+| [`bin/verify-runtime.ts`](bin/verify-runtime.ts) | Check candidate engine compatibility |
+| [`extensions/`](extensions/) | Register commands, UI, and keyboard behavior |
+| [`lib/`](lib/) | Read account usage, local activity, and selected configuration |
+| [`ui/chrome.ts`](ui/chrome.ts) | Render the header, footer, and spacing |
+| [`ui/escape-exit.ts`](ui/escape-exit.ts) | Preserve native behavior around Escape |
+| [`ui/pi-logo.svg`](ui/pi-logo.svg) | Reference Pi logo geometry |
+| [`test/`](test/) | Check UI, startup, and update behavior |
+
+Source code uses TypeScript with `strict` enabled. Plain `npm ci` builds it through `prepare`; when using `npm ci --ignore-scripts`, run `npm run build` explicitly. Compilation writes JavaScript to `dist/`, which is ignored by Git and included in the npm package. Extensions load from `dist/extensions/`; installed users do not need TypeScript or a build step. Keep TypeScript paths in `tsconfig.json` aligned with the bundled Pi dependency; updated engines resolve their own modules at runtime.
+
+After editing source files, run `npm run build` before restarting a directly linked `pi`. `npm run pi`, `npm start`, and `npm test` build automatically. For continuous compilation in another terminal, use `npm run build -- --watch`. Tests exercise the compiled JavaScript that ships to users. `npm pack` builds before creating an archive.
+
+The startup resource listing is hidden; skills and extensions still load normally. UI integration relies on some Pi component structure, so engine updates are checked before activation.
+
+```sh
+npm run check
+npm run build
+npm test
+```
+
+Before publishing a release, run `npm run release:check`. It runs type checking and tests, packs the exact npm artifact, installs it into an isolated global prefix, and checks the installed CLI and extensions with an empty profile. The archive is saved under `.local/releases/`. This check never publishes or changes your normal global installation. Windows is the currently verified platform; Linux/macOS need their own runs before claiming support.
+
+Repository instructions live in [AGENTS.md](AGENTS.md). The English documentation
+site lives in `docs/` as an independent Nextra project. Run `npm ci --prefix docs`
+and `npm run dev --prefix docs` to work on it. Production builds export static
+pages and a search index; the Documentation workflow deploys them to GitHub
+Pages. See [RELEASING.md](RELEASING.md) for verification and publication steps.
+
+To check credentials and make one short model request:
+
+```sh
+npm run pi -- auth check --provider openai-codex --no-refresh --json
+npm run smoke
+```
+
+The auth check should report `"status":"ready"`. The smoke request runs without tools or session storage and should return `PI_OK`. To use another model: `npm run smoke -- --model MODEL_ID`.
+
+## Contributing
+
+Bug reports, fixes, documentation improvements, and interface refinements are
+welcome. For a larger feature, you can open an
+[issue](https://github.com/svjszn/pi-extended-agent/issues) to discuss the approach.
+
+Fork the repository, create a branch for your change, and follow the setup in
+[Development](#development). Keep pull requests focused and explain the problem,
+the resulting behavior, and how you checked it.
+
+For agent code changes, run:
+
+```sh
+npm run check
+npm test
+```
+
+For documentation changes, install the docs dependencies and build the site:
+
+```sh
+npm ci --prefix docs
+npm run build --prefix docs
+```
+
+Add regression coverage for behavior fixes and include screenshots for interface
+changes when possible. Keep generated files, local profiles, and credentials out
+of commits. Read [AGENTS.md](AGENTS.md) for repository conventions and the
+[contributing guide](https://svjszn.github.io/pi-extended-agent/contributing/)
+for the full workflow.
+
+## Troubleshooting
+
+**The original Pi interface opens or `/effort` is missing.** A different installation owns `pi`. Check PATH as shown above. Remove the old npm-installed Pi, then reinstall or relink this package. The unique `pi-extended-agent` command can also launch our package directly.
+
+**An engine update fails.** The previous engine stays selected. Check the error, fix connectivity or npm access, and retry. If the version check times out, `pi update --to VERSION` skips that lookup and installs an exact version (installation still needs npm access or cached packages). Use `pi update --rollback` to select the previous version after a successful update.
+
+**The updater reports a lock.** Another update may be running. If the updater was interrupted and no update process remains, remove the reported `update.lock` file and retry.
+
+**Authentication is missing.** Check `PI_CODING_AGENT_DIR` and use `/login` on this computer. Early local experiments used `.local/pi/`; the current package does not select that directory automatically.
+
+---
+
+Built on [Pi](https://pi.dev) by Earendil and contributors. Uses the official pixel mark in a terminal-friendly form.

package/bin/pi.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// Keep the npm bin path stable for existing global links.
+await import("../dist/bin/main.js");

package/dist/bin/command-policy.js

@@ -0,0 +1,222 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { commandName, removedCommand, removedCommandMessage } from "../lib/command-policy.js";
+import { CONFIG_PREFERENCES } from "../lib/config-preferences.js";
+import { createRequire } from "node:module";
+import { installModelInterface } from "./model-interface.js";
+const installed = new WeakSet();
+/** Runtime-only adapters: never edit upstream files or duplicate its settings callbacks. */
+export function installCommandPolicy(api) {
+    const ui = api.InteractiveMode?.prototype;
+    const runner = api.ExtensionRunner?.prototype;
+    const session = api.AgentSession?.prototype;
+    for (const method of [ui?.createBaseAutocompleteProvider, ui?.setupEditorSubmitHandler, ui?.showSettingsSelector, ui?.createExtensionUIContext,
+        runner?.getRegisteredCommands, runner?.getCommand, session?.prompt]) {
+        if (typeof method !== "function")
+            throw new Error("This Pi engine does not support the command-menu adapter.");
+    }
+    if (installed.has(ui))
+        return;
+    const autocomplete = ui.createBaseAutocompleteProvider;
+    ui.createBaseAutocompleteProvider = function () {
+        const provider = autocomplete.call(this);
+        if (!Array.isArray(provider.commands))
+            throw new Error("Pi command autocomplete has changed.");
+        provider.commands = provider.commands.filter((command) => !removedCommand(command.name));
+        return provider;
+    };
+    const setupSubmit = ui.setupEditorSubmitHandler;
+    ui.setupEditorSubmitHandler = function () {
+        setupSubmit.call(this);
+        const submit = this.defaultEditor.onSubmit;
+        if (!submit)
+            throw new Error("Pi command submission has changed.");
+        this.defaultEditor.onSubmit = (text) => {
+            const name = commandName(text);
+            if (name && removedCommand(name)) {
+                this.editor.setText("");
+                this.showStatus(removedCommandMessage(name));
+                return;
+            }
+            return submit(text);
+        };
+    };
+    const commands = runner.getRegisteredCommands;
+    runner.getRegisteredCommands = function () {
+        return commands.call(this).filter((command) => !removedCommand(command.name)
+            && !removedCommand(command.invocationName ?? command.name));
+    };
+    const getCommand = runner.getCommand;
+    runner.getCommand = function (name) {
+        if (removedCommand(name))
+            return undefined;
+        const command = getCommand.call(this, name);
+        return command && !removedCommand(command.name) ? command : undefined;
+    };
+    const prompt = session.prompt;
+    session.prompt = function (text, options) {
+        const name = commandName(text);
+        if (name && removedCommand(name))
+            return Promise.reject(new Error(removedCommandMessage(name)));
+        return prompt.call(this, text, options);
+    };
+    const createUI = ui.createExtensionUIContext;
+    ui.createExtensionUIContext = function () {
+        const context = createUI.call(this);
+        context[CONFIG_PREFERENCES] = () => captureConfigPreferences(this);
+        return context;
+    };
+    installed.add(ui);
+}
+/** Reuse every native item and save callback, without mounting the native menu. */
+export function captureConfigPreferences(host) {
+    let list, cancelled = false, pending;
+    const originalSelector = host.showSelector;
+    try {
+        host.showSelector = (create) => { list = create(() => { cancelled = true; }).component.getSettingsList(); };
+        host.showSettingsSelector();
+    }
+    finally {
+        host.showSelector = originalSelector;
+    }
+    if (!list || typeof list.render !== "function" || typeof list.onChange !== "function") {
+        throw new Error("Pi preferences are incompatible with the configuration screen.");
+    }
+    const settings = list;
+    const change = settings.onChange;
+    settings.onChange = (id, value) => {
+        // Changing renderers requires the overlay to close before invoking Pi's callback.
+        if (id === "tui-mode")
+            pending = () => change(id, value);
+        else
+            change(id, value);
+    };
+    return {
+        get cancelled() { return cancelled; },
+        get hasPendingChange() { return Boolean(pending); },
+        applyPendingChange() { const apply = pending; pending = undefined; apply?.(); },
+        handleInput: (data) => settings.handleInput(data),
+        render(width, rows, theme) {
+            settings.maxVisible = Math.max(1, rows - 7);
+            settings.theme = {
+                label: (text, selected) => theme.fg(selected ? "primary" : "muted", text),
+                value: (text) => theme.fg("text", text), description: (text) => theme.fg("dim", text),
+                cursor: theme.fg("primary", "› "), hint: (text) => theme.fg("dim", text),
+            };
+            // Native menus assume a minimum label width; the shared panel clips tiny terminals.
+            const lines = settings.render(Math.max(40, width));
+            // Submenus obtain their own native theme. Keep them monochrome as well.
+            return settings.submenuComponent
+                ? lines.map((line) => theme.fg("text", line.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "")))
+                : lines;
+        },
+        dispose() {
+            // Cancel nested theme previews before leaving the preferences tab.
+            for (let i = 0; settings.submenuComponent && i < 10; i++)
+                settings.handleInput("\x1b");
+        },
+    };
+}
+export async function prepareRuntimeCommands(runtime) {
+    // The executable and bundle index share classes. Patching dist/index.js alone
+    // would leave the actual bundled CLI's menu and submit handler unchanged.
+    const bundle = join(runtime.packageDir, "dist", "bundle", "index.js");
+    if (!existsSync(bundle))
+        throw new Error("Pi engine is missing its bundled command API.");
+    const api = await import(pathToFileURL(bundle).href);
+    installCommandPolicy(api);
+    const require = createRequire(pathToFileURL(runtime.entry));
+    const measure = await import(pathToFileURL(require.resolve("@earendil-works/pi-tui")).href);
+    installModelInterface(api, measure, runtime.version);
+    return api;
+}
+/** Probe private adapter surfaces without creating a session or accessing a profile. */
+export async function verifyCommandPolicy(api) {
+    const host = Object.create(api.InteractiveMode.prototype);
+    Object.defineProperties(host, {
+        session: { configurable: true, value: { scopedModels: [], promptTemplates: [],
+                extensionRunner: { getRegisteredCommands: () => [{ name: "config", invocationName: "config" }] },
+                resourceLoader: { getSkills: () => ({ skills: [] }) } } },
+        sessionManager: { value: { getCwd: () => process.cwd() } },
+        settingsManager: { configurable: true, value: { getEnableSkillCommands: () => false } },
+        skillCommands: { value: new Map() },
+    });
+    const provider = host.createBaseAutocompleteProvider();
+    if (provider.commands.some((command) => removedCommand(command.name))
+        || !provider.commands.some((command) => command.name === "config")
+        || !provider.commands.some((command) => command.name === "model")) {
+        throw new Error("Pi command-menu filtering is incompatible.");
+    }
+    let settingsOpened = false, removedNotice = false, submitted = "";
+    host.defaultEditor = {};
+    host.editor = { setText() { } };
+    host.showStatus = () => { removedNotice = true; };
+    host.showSettingsSelector = () => { settingsOpened = true; };
+    host.setupEditorSubmitHandler();
+    await host.defaultEditor.onSubmit("/settings");
+    if (!removedNotice || settingsOpened)
+        throw new Error("Pi still executes removed commands.");
+    // /config must reach our extension rather than mount the native settings menu.
+    Object.assign(host, { flushPendingBashComponents() { }, onInputCallback: (text) => { submitted = text; } });
+    await host.defaultEditor.onSubmit("/config");
+    if (settingsOpened || submitted !== "/config")
+        throw new Error("Pi bypasses the custom configuration screen.");
+    // Probe the settings-data bridge as well as command submission. Native data
+    // and callbacks can change even when the old menu method still exists.
+    api.initTheme("dark", false);
+    const engineSettings = api.SettingsManager.inMemory();
+    Object.defineProperty(host, "settingsManager", { value: engineSettings });
+    Object.defineProperty(host, "session", { configurable: true, value: {
+            settingsManager: engineSettings, autoCompactionEnabled: true,
+            modelRuntime: { getAvailableSnapshot: () => [] }, steeringMode: "all", followUpMode: "all",
+        } });
+    Object.assign(host, {
+        showSettingsSelector: api.InteractiveMode.prototype.showSettingsSelector,
+        themeController: { getThemeSelection: () => "dark", getTerminalTheme: () => "dark" },
+        ui: { mode: "fullscreen" }, chatContainer: { children: [] },
+    });
+    const preferences = captureConfigPreferences(host);
+    try {
+        if (!preferences.render(80, 24, { fg: (_role, text) => text, bold: (text) => text }).length) {
+            throw new Error("Pi configuration preferences are empty.");
+        }
+    }
+    finally {
+        preferences.dispose();
+    }
+    // Verify the controller fields consumed by our model renderer against the
+    // candidate executable, without authentication or a catalog network request.
+    const model = { provider: "compat", id: "compat-model", name: "Compatibility model" };
+    Object.defineProperty(host, "session", { value: {
+            model, thinkingLevel: "medium", settingsManager: engineSettings, scopedModels: [],
+            modelRuntime: { getAvailableSnapshot: () => [model], getModel: () => model, getError: () => undefined,
+                refresh: async () => ({ errors: new Map(), aborted: false }) },
+        } });
+    const tui = { children: [], terminal: { rows: 24, columns: 80 }, requestRender() { } };
+    let modelScreen;
+    Object.assign(host, {
+        ui: tui, footerContainer: { render: () => [] },
+        showError: (message) => { throw new Error(message); },
+        createExtensionUIContext: () => ({ custom: (create) => {
+                modelScreen = Promise.resolve().then(async () => {
+                    const panel = create(tui, {}, {}, () => panel.dispose());
+                    try {
+                        await panel.ready;
+                        if (!panel.render(80).some((line) => line.includes("compat-model")))
+                            throw new Error("Pi model selection has changed.");
+                        panel.handleInput("\x1b");
+                    }
+                    finally {
+                        panel.dispose();
+                    }
+                });
+                return modelScreen;
+            } }),
+    });
+    host.showModelSelector("compat-model");
+    if (!modelScreen)
+        throw new Error("Pi bypasses the styled model screen.");
+    await modelScreen;
+}
+//# sourceMappingURL=command-policy.js.map