@astralyn/pi 0.82.0 → 0.82.2

package/docs/distribution/extensions/subagent.md

@@ -0,0 +1,102 @@
+# subagent — isolated foreground delegation
+
+Adds the `subagent` tool and `/agents` profile settings command. It delegates a bounded task to an isolated in-process `AgentSession`; it is not a background worker or a fleet manager.
+
+## Tool modes
+
+Exactly one mode is required per call:
+
+- **Single**: `agent`, `description`, and `prompt`.
+- **Parallel**: `tasks`, an array of independent task objects.
+- **Chain**: `chain`, an array of sequential task objects. `{previous}` in a later prompt is replaced by the previous worker's bounded final response.
+
+Every task object has:
+
+```text
+agent?       Agent profile name; defaults to general
+description  Short UI label
+prompt       Self-contained worker briefing
+cwd?         Relative directory inside the parent working directory
+model?       Temporary provider/model override
+thinking?    Temporary thinking-level override
+```
+
+Parallel and chain batches allow at most eight tasks. A session-scoped gate runs at most three workers concurrently, including sibling `subagent` calls from the same parent session.
+
+## Agent profiles
+
+Profiles are Markdown files with YAML frontmatter:
+
+```yaml
+---
+name: reviewer
+description: Read-only implementation reviewer
+tools: read, grep, find, ls
+model: anthropic/claude-sonnet-4-5
+thinking: medium
+backend: sdk
+---
+
+Review the delegated task independently and report exact evidence.
+```
+
+Sources and precedence are:
+
+```text
+built-in < ~/.pi/agent/agents/*.md < trusted-project/.pi/agents/*.md
+```
+
+Project definitions are loaded only after Pi trusts the project. Invalid Markdown definitions appear as `/agents` diagnostics without hiding valid profiles.
+
+Built-in profiles:
+
+- `general`: read, bash, edit, write, grep, find, and ls.
+- `explorer`: read-only `read`, `grep`, `find`, and `ls`, with low thinking by default.
+
+A profile may only allow Pi built-in tools. Child sessions load no extensions, skills, or prompt templates, so a worker cannot recursively call `subagent` or inherit unrelated extension capabilities. Project context files such as `AGENTS.md` remain available.
+
+## Model and thinking selection
+
+The model/thinking resolution order is:
+
+```text
+per-call tool fields
+  > saved /agents profile override
+  > profile Markdown frontmatter
+  > current parent session
+```
+
+Run `/agents` to choose a profile and set either field to:
+
+- **inherit**: force the active parent-session value;
+- **agent default**: clear the saved override and use Markdown/default inheritance;
+- a configured `provider/model` or explicit supported thinking level.
+
+Overrides are user-owned and saved atomically in:
+
+```text
+~/.pi/agent/subagent.json
+```
+
+They apply only to future subagent runs and never change the parent session's `/model` or thinking level.
+
+## Lifecycle and output
+
+- The parent tool call waits until every worker reaches a terminal state.
+- Parent abort, `/reload`, `/new`, `/resume`, `/fork`, and session shutdown abort active child sessions. Queued workers do not survive the call.
+- Parallel worker failures do not cancel other independent workers. A failed or aborted chain step skips its remaining steps.
+- Progress is rendered in Pi's native tool transcript. The collapsed view shows status, recent activity, usage, and the configured expand hint; `Ctrl+O` shows bounded activities and final Markdown reports.
+- Full child transcripts are not stored separately. Bounded run details remain in the parent tool result, so completed calls restore naturally in the parent session tree.
+- Nested usage is returned with the tool result and included in parent session accounting.
+
+## Deliberate non-features
+
+There are no background agents, persistent worker IDs, unread state, fleet panel, statusline widget, send/stop/resume control plane, completion notifications, swarm/coordinator, worktree isolation, nested agents, MCP, hooks, or agent memory.
+
+**Files:** `src/extensions/subagent/`
+
+- `index.ts` — registration, parent provider synchronization, `/agents`, shutdown cleanup
+- `agents.ts` / `settings.ts` / `resolve.ts` — profile discovery, persistent overrides, task validation
+- `sdk-runner.ts` / `runner.ts` — isolated sessions, progress, abort, concurrency, modes
+- `activity.ts` / `render.ts` — bounded evidence, usage, native transcript rendering
+- `schema.ts` / `types.ts` / `constants.ts` — public tool contract and data model

package/docs/distribution/maintenance.md

@@ -0,0 +1,121 @@
+# Distribution maintenance
+
+This guide describes how to keep the standalone `@astralyn/pi` package aligned with upstream Pi. The repository contract in [`AGENTS.md`](../../AGENTS.md) is authoritative; publishing is covered separately in [`release.md`](release.md).
+
+## Repository model
+
+```text
+origin    private distribution repository
+upstream  earendil-works/pi monorepo
+```
+
+`main` contains a standalone package, not an upstream monorepo checkout. Upstream tags must therefore be inspected and selectively imported; never merge an upstream tag directly into `main`, because that would recreate every workspace.
+
+## Ownership layers
+
+| Layer | Typical paths | Policy |
+|---|---|---|
+| Upstream-aligned coding-agent | most of `src/**`, `test/**`, `docs/**`, `examples/**` | Import compatible changes from an upstream release tag. |
+| Distribution-owned | `docs/distribution/**`, bundled personal extensions, ice-cream themes, release workflow, package identity | Preserve local design and update deliberately. |
+| Hybrid | `src/core/agent-session.ts`, native tool presentation, built-in tools, keybindings, extension registration, `package.json`, `CHANGELOG.md` | Review function by function; retain upstream lifecycle semantics and local behavior. |
+| Registry boundary | exact upstream AI, Agent core, and TUI dependencies | Upgrade together with the imported coding-agent release; never patch their installed files. |
+
+Recurring hybrid hotspots include:
+
+```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
+```
+
+## Synchronization workflow
+
+Synchronize only against upstream release tags, never upstream `main`. Start from a clean branch and fetch tags:
+
+```bash
+git status --short
+git fetch upstream --tags
+git tag --list 'v<upstream-minor>.*'
+git switch -c sync/upstream-<version> main
+```
+
+Extract the upstream coding-agent subtree into a temporary directory without changing the current checkout:
+
+```bash
+tmp="$(mktemp -d)"
+git archive v<version> packages/coding-agent | tar -x -C "$tmp"
+```
+
+Review `$tmp/packages/coding-agent/` against the standalone root. Import upstream changes in bounded groups:
+
+1. Review source and tests, paying special attention to the hybrid hotspots above.
+2. Update product/API documentation and examples while retaining distribution-specific references.
+3. Adapt upstream package and TypeScript changes to the standalone root rather than copying monorepo-relative paths.
+4. Set the exact `@earendil-works/pi-ai`, `@earendil-works/pi-agent-core`, and `@earendil-works/pi-tui` versions published for that upstream release.
+5. Run `npm install --ignore-scripts` to refresh `npm-shrinkwrap.json`, then inspect dependency and lifecycle-script changes.
+
+Do not copy these upstream monorepo assumptions into the standalone repository:
+
+- workspace declarations or `packages/*` paths;
+- TypeScript or Vitest aliases to sibling source workspaces;
+- Server, storage, model-catalog, binary, or multi-package release scripts;
+- cross-package source modifications needed only by an unreleased upstream checkout.
+
+If imported coding-agent code requires an API absent from the published upstream dependencies, stop and use a later compatible release. Do not solve the mismatch by vendoring or locally forking another package.
+
+## Conflict policy
+
+When reconciling upstream changes:
+
+1. Preserve security fixes, protocol correctness, execution semantics, and public API compatibility first.
+2. Keep local behavior only where it is intentionally documented and tested.
+3. For native UI, integrate upstream execution changes before adapting presentation.
+4. Keep model-facing output bounded and avoid schema/result changes for display-only work.
+5. Prefer a small local type intersection or adapter over changing an upstream dependency API.
+
+Git may detect many imports as renames from the historical `packages/coding-agent` path. Review content, not rename percentages.
+
+## Dependency and lock maintenance
+
+All direct registry dependencies are exact. When package metadata changes:
+
+```bash
+npm install --ignore-scripts
+npm run check:pinned-deps
+```
+
+`npm-shrinkwrap.json` is both the development lock and the lock published with `@astralyn/pi`. Review new or changed transitive packages, platform-specific optional packages, and lifecycle scripts before accepting it. The pre-commit hook requires an explicit `PI_ALLOW_LOCKFILE_CHANGE=1` acknowledgment when committing an intentional shrinkwrap change.
+
+## Verification
+
+At minimum:
+
+```bash
+npm run build
+npm run check
+```
+
+Run focused tests for each changed subsystem. For native transcript changes, verify pending, success, error, collapsed, and expanded states, plus `Ctrl+O`, `/reload`, and `/tree` in a real TTY. The Ubuntu CI workflow runs Build, Check, and the full test suite.
+
+Before integrating a synchronization branch:
+
+```bash
+git status --short
+git diff --stat main...HEAD
+git log --oneline main..HEAD
+```
+
+## Changelog and release ownership
+
+- `CHANGELOG.md` is the runtime and release changelog for `@astralyn/pi`.
+- `docs/**` remains structurally close to upstream coding-agent user/API documentation.
+- `docs/distribution/**` records standalone architecture, bundled behavior, maintenance, and release operations.
+- Dependency package changelogs are not copied; consult their upstream releases during synchronization.
+
+After synchronization and verification, follow the [release checklist](release.md).

package/docs/distribution/release.md

@@ -0,0 +1,85 @@
+# Release checklist
+
+This repository publishes one npm package from its root: `@astralyn/pi`. It does not use the upstream multi-package, binary, source-archive, or model-catalog release flows. Upstream synchronization is documented in [maintenance.md](maintenance.md).
+
+## Scope and versioning
+
+Track the upstream Pi `major.minor` line and reserve 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, ...
+```
+
+The first distribution release after moving to a new upstream minor uses patch `0`. Every later release on that line uses the next unused patch, including releases that absorb an upstream patch update. Use `pi-v<full-version>` Git tags so they remain distinct from fetched upstream tags such as `v0.82.0`.
+
+## Prepare the release
+
+1. Start from a clean `main` branch and choose the next unused distribution version.
+2. Move current `CHANGELOG.md` entries from `[Unreleased]` into one `## [<version>] - YYYY-MM-DD` section, then leave a new empty `[Unreleased]` section.
+3. Update `package.json` version.
+4. Refresh and review the authoritative shrinkwrap:
+
+```bash
+npm install --package-lock-only --ignore-scripts
+```
+
+Direct dependencies are exact. If a synchronized upstream release is still blocked by the `.npmrc` age gate, prefer waiting; use `--min-release-age=0` only after explicitly verifying the package versions, provenance, and release contents.
+
+Confirm `package.json` and the root entry in `npm-shrinkwrap.json` carry the same `@astralyn/pi` version and that the intended exact upstream AI, Agent core, and TUI versions are locked.
+
+## Verify
+
+Local development verification:
+
+```bash
+npm run build
+npm run check
+```
+
+Release verification runs on Ubuntu through GitHub Actions. The CI and publish workflows both install from `npm-shrinkwrap.json`, build, check, verify that generated files remain clean, and run the complete test suite.
+
+## Review the package
+
+After building, inspect the root package:
+
+```bash
+npm pack --dry-run
+```
+
+The tarball must contain the built `dist`, product documentation, examples, README, changelog, and `npm-shrinkwrap.json`. It must not contain source workspaces or local configuration. For stronger verification, create a real tarball, install it in a temporary directory outside the repository, and run `pi --version` and `pi --list-models`.
+
+## Publish and tag
+
+Publishing uses npm Trusted Publishing through GitHub Actions OIDC. Configure the package once on npm:
+
+```text
+Publisher: GitHub Actions
+Organization or user: ming-kang
+Repository: pi
+Workflow filename: publish-npm.yml
+Environment name: (blank)
+Allowed action: Allow npm publish
+```
+
+After the release commit is pushed and CI passes, trigger the workflow from an authenticated GitHub CLI session:
+
+```bash
+gh workflow run publish-npm.yml --repo ming-kang/pi --ref main -f version=0.82.0
+
+gh run list --repo ming-kang/pi --workflow publish-npm.yml --limit 1
+gh run watch <run-id> --repo ming-kang/pi --exit-status
+```
+
+The workflow validates the requested version, repeats Ubuntu Build/Check/Test, publishes the repository root with provenance, and verifies the registry version. A normal push to `main` never publishes.
+
+After publication, verify the registry and perform a global-install/self-update smoke test from a separate shell or after restarting Pi. Do not replace the package currently running the release session.
+
+Finally tag the exact release commit:
+
+```bash
+git tag pi-v<full-version>
+git push origin pi-v<full-version>
+```
+
+No other package is published from this repository.

package/docs/distribution/themes.md

@@ -0,0 +1,58 @@
+# Bundled theme design
+
+This document describes the themes shipped by the distribution. For theme discovery, JSON format, and custom theme authoring, see the [Theme API documentation](../themes.md).
+
+The Fork bundles two Pi themes using the native theme schema and loader:
+
+| Theme | Use |
+|---|---|
+| `ice-cream-dark` | Cool sea-salt dark palette with warm cream tool titles. |
+| `ice-cream-light` | Light counterpart with the same semantic mapping. |
+
+Both themes are built into `@astralyn/pi`. They do not require the external `pi-config` package.
+
+## Selecting a theme
+
+Use `/settings`, or set a single theme:
+
+```json
+{
+  "theme": "ice-cream-dark"
+}
+```
+
+For automatic terminal light/dark selection:
+
+```json
+{
+  "theme": "ice-cream-light/ice-cream-dark"
+}
+```
+
+The left side is used for light terminals and the right side for dark terminals.
+
+## Design intent
+
+The palette keeps an ice-cream / sea-salt identity: cool cyan-blue accents with warm cream tooling on a calm neutral base.
+
+- `accent` and borders use the sea-salt family;
+- `toolTitle` uses cream/gold tones;
+- `toolOutput`, `muted`, and `dim` form a readable text ladder;
+- tool backgrounds remain transparent so the native `●` / `│` presentation stays light;
+- `success`, `error`, and `warning` remain semantic pastel colors;
+- thinking levels move from cool blue through green and gold to coral/red.
+
+## Extension UI
+
+Bundled dialogs, overlays, and the statusline use semantic theme helpers such as `theme.fg(...)` and `theme.bg(...)`. They do not hard-code ANSI colors or hex values.
+
+## Theme files
+
+The source assets are:
+
+```text
+src/modes/interactive/theme/ice-cream-dark.json
+src/modes/interactive/theme/ice-cream-light.json
+```
+
+The normal package build copies all theme JSON assets into the runtime package. The themes use the schema at `src/modes/interactive/theme/theme-schema.json`.

package/docs/distribution/tool-presentation.md

@@ -0,0 +1,91 @@
+# Native tool presentation
+
+This Fork changes Pi's native tool transcript presentation rather than replacing it with a separate `tools-view` extension.
+
+## Visual language
+
+```text
+● ToolName(args)
+│ result
+```
+
+States use the same shell:
+
+```text
+● ToolName(args)       completed call
+● ToolName Working...  pending call
+● ToolName(args)       failed call (error color)
+│ result               successful or failed output
+```
+
+## Implementation boundary
+
+The main entry point is:
+
+```text
+src/modes/interactive/components/tool-execution.ts
+```
+
+It owns:
+
+- the default call/result shell;
+- pending, success, and error states;
+- call titles and generic argument summaries;
+- collapsed and expanded result behavior;
+- generic fallback rendering;
+- image placement and conversion.
+
+Built-in renderers remain responsible for semantic content such as file paths, syntax highlighting, search results, Diff previews, and command output. The outer shell is native so built-in tools, bundled extensions, and compatible third-party tools share the same presentation.
+
+Consecutive tools may opt into a shared collapsed group through `toolGroup`. Built-in `read` and `find` calls use the `explore` group: their call rows render as one compact run with a single leading gap, while `Ctrl+O` restores each tool's complete call and result.
+
+## Renderer inheritance
+
+| Tool definition | Behavior |
+|---|---|
+| No `renderCall`/`renderResult` | Uses the Fork's native call and result fallback. |
+| Custom renderer with the default shell | Uses the native shell around the custom content. |
+| `renderShell: "self"` | Keeps complete ownership of the tool's layout. |
+
+Built-in tool definitions are also used when an extension overrides only one renderer slot. A custom call renderer can inherit the built-in result renderer, and vice versa.
+
+Renderer failures fall back to native generic output rather than breaking the transcript.
+
+## Generic fallback
+
+When no semantic renderer is available:
+
+- arguments are serialized into a bounded one-line summary;
+- output is collapsed to the most recent ten visual lines;
+- `Ctrl+O` expands the complete output;
+- historical tools that are no longer registered still receive the same shell;
+- failed calls use the error-colored bullet while result details keep the result bar.
+
+The fallback does not change tool schemas, execution logic, or result protocols.
+
+## Built-in behavior preserved
+
+The native path continues to preserve:
+
+- `read`, `bash`, `grep`, `find`, `ls`, `write`, and `edit` semantics;
+- faithful width-aware raw command previews for Bash;
+- running Bash duration after the two-second progress threshold, without a permanent completion timer;
+- Diff previews and first-change-line metadata for `edit`;
+- syntax highlighting;
+- image output and Kitty conversion;
+- native collapsed/expanded handling;
+- custom UI explicitly using `renderShell: "self"`.
+
+`edit` now uses the native outer shell while keeping its asynchronous Diff preview and final Diff result.
+
+## Deliberately rejected approaches
+
+This Fork does not use:
+
+- prototype patching of `ToolExecutionComponent` from an extension;
+- same-name re-registration to replace built-in tools;
+- a global renderer registry exposed through Extension API;
+- a restored `tools-view` extension;
+- forced decoration of third-party tools that explicitly own their shell.
+
+Those approaches either depend on private runtime internals, change execution ownership, or cannot reliably cover independently loaded extensions.

package/docs/extensions.md

@@ -457,7 +457,7 @@ pi.on("session_before_compact", async (event, ctx) => {
   const { preparation, branchEntries, customInstructions, reason, willRetry, signal } = event;
 
   // 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
 
   // Cancel:
   return { cancel: true };
@@ -477,7 +477,7 @@ pi.on("session_compact", async (event, ctx) => {
   // event.compactionEntry - the saved compaction
   // event.fromExtension - whether extension provided it
   // event.reason - "manual" (/compact), "threshold", or "overflow"
-  // event.willRetry - whether the aborted turn is retried after compaction (overflow recovery)
+  // event.willRetry - whether overflow recovery will actually retry after retained-context verification
 });
 ```
 
@@ -585,6 +585,8 @@ pi.on("turn_end", async (event, ctx) => {
 });
 ```
 
+Between-tool auto-compaction runs after the completed tool turn's `turn_end`. If it cannot produce a safe next context, Pi stops before queue polling or another provider request. The upstream stateful Agent represents that package-local stop as an additional assistant error/aborted message lifecycle and `turn_end`, followed by `agent_end`; SDK, JSON, and RPC consumers can use the preceding `compaction_end` event for the detailed compaction failure or retained-context warning.
+
 #### message_start / message_update / message_end
 
 Fired for message lifecycle updates.

package/docs/index.md

@@ -2,7 +2,7 @@
 
 Pi is a minimal terminal coding harness. It is designed to stay small at the core while being extended through TypeScript extensions, skills, prompt templates, themes, and pi packages.
 
-This documentation covers product usage and public APIs. Fork architecture, bundled behavior, upstream synchronization, and publishing are documented in the repository root [Fork documentation](../../../docs/README.md).
+This documentation covers product usage and public APIs. Distribution architecture, bundled behavior, upstream synchronization, and publishing are documented in [`docs/distribution/`](distribution/README.md).
 
 ## Quick start
 

package/docs/rpc.md

@@ -1359,8 +1359,8 @@ Parse errors:
 ## Types
 
 Source files:
-- [`packages/ai/src/types.ts`](../../ai/src/types.ts) - `Model`, `UserMessage`, `AssistantMessage`, `ToolResultMessage`
-- [`packages/agent/src/types.ts`](../../agent/src/types.ts) - `AgentMessage`, `AgentEvent`
+- [upstream AI types](https://github.com/earendil-works/pi/blob/main/packages/ai/src/types.ts) - `Model`, `UserMessage`, `AssistantMessage`, `ToolResultMessage`
+- [upstream Agent types](https://github.com/earendil-works/pi/blob/main/packages/agent/src/types.ts) - `AgentMessage`, `AgentEvent`
 - [`src/core/messages.ts`](../src/core/messages.ts) - `BashExecutionMessage`
 - [`src/modes/rpc/rpc-types.ts`](../src/modes/rpc/rpc-types.ts) - RPC command/response types, extension UI request/response types
 

package/docs/themes.md

@@ -298,4 +298,4 @@ See the built-in themes:
 - [ice-cream-dark.json](../src/modes/interactive/theme/ice-cream-dark.json)
 - [ice-cream-light.json](../src/modes/interactive/theme/ice-cream-light.json)
 
-The ice-cream palette and Fork-specific design notes are documented in the repository root `docs/themes.md`.
+The ice-cream palette and distribution-specific design notes are documented in [`docs/distribution/themes.md`](distribution/themes.md).

package/examples/extensions/custom-provider-anthropic/package-lock.json

@@ -1,14 +1,14 @@
 {
-  "name": "pi-extension-custom-provider",
+  "name": "pi-extension-custom-provider-anthropic",
   "version": "0.82.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "pi-extension-custom-provider",
+      "name": "pi-extension-custom-provider-anthropic",
       "version": "0.82.0",
       "dependencies": {
-        "@anthropic-ai/sdk": "^0.52.0"
+        "@anthropic-ai/sdk": "0.52.0"
       }
     },
     "node_modules/@anthropic-ai/sdk": {

package/examples/extensions/custom-provider-gitlab-duo/test.ts

@@ -8,9 +8,9 @@
  *   npx tsx test.ts claude-sonnet-4-5-20250929 --thinking
  */
 
+import { getAgentDir } from "@astralyn/pi";
 import { type Api, type Context, type Model, registerApiProvider, streamSimple } from "@earendil-works/pi-ai/compat";
 import { readFileSync } from "fs";
-import { getAgentDir } from "packages/coding-agent/src/config.js";
 import { join } from "path";
 import { MODELS, streamGitLabDuo } from "./index.ts";
 

package/examples/extensions/sandbox/package-lock.json

@@ -8,7 +8,7 @@
 			"name": "pi-extension-sandbox",
 			"version": "1.12.0",
 			"dependencies": {
-				"@anthropic-ai/sandbox-runtime": "^0.0.26"
+				"@anthropic-ai/sandbox-runtime": "0.0.26"
 			}
 		},
 		"node_modules/@anthropic-ai/sandbox-runtime": {

package/examples/extensions/with-deps/package-lock.json

@@ -8,10 +8,10 @@
       "name": "pi-extension-with-deps",
       "version": "0.82.0",
       "dependencies": {
-        "ms": "^2.1.3"
+        "ms": "2.1.3"
       },
       "devDependencies": {
-        "@types/ms": "^2.1.0"
+        "@types/ms": "2.1.0"
       }
     },
     "node_modules/@types/ms": {