@astralyn/pi 0.82.2 → 0.82.3

package/docs/distribution/maintenance.md

@@ -1,121 +0,0 @@
-# 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

@@ -1,85 +0,0 @@
-# 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/examples/extensions/subagent/README.md

@@ -1,175 +0,0 @@
-# Subagent Example
-
-Delegate tasks to specialized subagents with isolated context windows.
-
-## Features
-
-- **Isolated context**: Each subagent runs in a separate `pi` process
-- **Streaming output**: See tool calls and progress as they happen
-- **Parallel streaming**: All parallel tasks stream updates simultaneously
-- **Markdown rendering**: Final output rendered with proper formatting (expanded view)
-- **Usage tracking**: Shows turns, tokens, cost, and context usage per agent
-- **Abort support**: Ctrl+C propagates to kill subagent processes
-
-## Structure
-
-```
-subagent/
-├── README.md            # This file
-├── index.ts             # The extension (entry point)
-├── agents.ts            # Agent discovery logic
-├── agents/              # Sample agent definitions
-│   ├── scout.md         # Fast recon, returns compressed context
-│   ├── planner.md       # Creates implementation plans
-│   ├── reviewer.md      # Code review
-│   └── worker.md        # General-purpose (full capabilities)
-└── prompts/             # Workflow presets (prompt templates)
-    ├── implement.md     # scout -> planner -> worker
-    ├── scout-and-plan.md    # scout -> planner (no implementation)
-    └── implement-and-review.md  # worker -> reviewer -> worker
-```
-
-## Installation
-
-From the repository root, symlink the files:
-
-```bash
-# Symlink the extension (must be in a subdirectory with index.ts)
-mkdir -p ~/.pi/agent/extensions/subagent
-ln -sf "$(pwd)/packages/coding-agent/examples/extensions/subagent/index.ts" ~/.pi/agent/extensions/subagent/index.ts
-ln -sf "$(pwd)/packages/coding-agent/examples/extensions/subagent/agents.ts" ~/.pi/agent/extensions/subagent/agents.ts
-
-# Symlink agents
-mkdir -p ~/.pi/agent/agents
-for f in packages/coding-agent/examples/extensions/subagent/agents/*.md; do
-  ln -sf "$(pwd)/$f" ~/.pi/agent/agents/$(basename "$f")
-done
-
-# Symlink workflow prompts
-mkdir -p ~/.pi/agent/prompts
-for f in packages/coding-agent/examples/extensions/subagent/prompts/*.md; do
-  ln -sf "$(pwd)/$f" ~/.pi/agent/prompts/$(basename "$f")
-done
-```
-
-## Security Model
-
-This tool executes a separate `pi` subprocess with a delegated system prompt and tool/model configuration.
-
-**Project-local agents** (`.pi/agents/*.md`) are repo-controlled prompts that can instruct the model to read files, run bash commands, etc.
-
-**Default behavior:** Only loads **user-level agents** from `~/.pi/agent/agents`.
-
-To enable project-local agents, pass `agentScope: "both"` (or `"project"`). Only do this for repositories you trust.
-
-When running interactively, the tool prompts for confirmation before running project-local agents. Set `confirmProjectAgents: false` to disable.
-
-## Usage
-
-### Single agent
-```
-Use scout to find all authentication code
-```
-
-### Parallel execution
-```
-Run 2 scouts in parallel: one to find models, one to find providers
-```
-
-### Chained workflow
-```
-Use a chain: first have scout find the read tool, then have planner suggest improvements
-```
-
-### Workflow prompts
-```
-/implement add Redis caching to the session store
-/scout-and-plan refactor auth to support OAuth
-/implement-and-review add input validation to API endpoints
-```
-
-## Tool Modes
-
-| Mode | Parameter | Description |
-|------|-----------|-------------|
-| Single | `{ agent, task }` | One agent, one task |
-| Parallel | `{ tasks: [...] }` | Multiple agents run concurrently (max 8, 4 concurrent) |
-| Chain | `{ chain: [...] }` | Sequential with `{previous}` placeholder |
-
-## Output Display
-
-**Collapsed view** (default):
-- Status icon (✓/✗/⏳) and agent name
-- Last 5-10 items (tool calls and text)
-- Usage stats: `3 turns ↑input ↓output RcacheRead WcacheWrite $cost ctx:contextTokens model`
-
-**Expanded view** (Ctrl+O):
-- Full task text
-- All tool calls with formatted arguments
-- Final output rendered as Markdown
-- Per-task usage (for chain/parallel)
-
-**Parallel mode streaming**:
-- Shows all tasks with live status (⏳ running, ✓ done, ✗ failed)
-- Updates as each task makes progress
-- Shows "2/3 done, 1 running" status
-- Returns each completed task's final output to the parent model, capped at 50 KB per task
-- Returns failure diagnostics from stderr/error messages when a child exits before producing output
-
-**Tool call formatting** (mimics built-in tools):
-- `$ command` for bash
-- `read ~/path:1-10` for read
-- `grep /pattern/ in ~/path` for grep
-- etc.
-
-## Agent Definitions
-
-Agents are markdown files with YAML frontmatter:
-
-```markdown
----
-name: my-agent
-description: What this agent does
-tools: read, grep, find, ls
-model: claude-haiku-4-5
----
-
-System prompt for the agent goes here.
-```
-
-**Locations:**
-- `~/.pi/agent/agents/*.md` - User-level (always loaded)
-- `.pi/agents/*.md` - Project-level (only with `agentScope: "project"` or `"both"`)
-
-Project agents override user agents with the same name when `agentScope: "both"`.
-
-## Sample Agents
-
-| Agent | Purpose | Model | Tools |
-|-------|---------|-------|-------|
-| `scout` | Fast codebase recon | Haiku | read, grep, find, ls, bash |
-| `planner` | Implementation plans | Sonnet | read, grep, find, ls |
-| `reviewer` | Code review | Sonnet | read, grep, find, ls, bash |
-| `worker` | General-purpose | Sonnet | (all default) |
-
-## Workflow Prompts
-
-| Prompt | Flow |
-|--------|------|
-| `/implement <query>` | scout → planner → worker |
-| `/scout-and-plan <query>` | scout → planner |
-| `/implement-and-review <query>` | worker → reviewer → worker |
-
-## Error Handling
-
-- **Exit code != 0**: Tool returns error with stderr/output
-- **stopReason "error"**: LLM error propagated with error message
-- **stopReason "aborted"**: User abort (Ctrl+C) kills subprocess, throws error
-- **Chain mode**: Stops at first failing step, reports which step failed
-
-## Limitations
-
-- Output truncated to last 10 items in collapsed view (expand to see all)
-- Parallel model-visible output is capped at 50 KB per task; full results remain in tool details
-- Agents discovered fresh on each invocation (allows editing mid-session)
-- Parallel mode limited to 8 tasks, 4 concurrent

package/examples/extensions/subagent/agents/planner.md

@@ -1,37 +0,0 @@
----
-name: planner
-description: Creates implementation plans from context and requirements
-tools: read, grep, find, ls
-model: claude-sonnet-4-5
----
-
-You are a planning specialist. You receive context (from a scout) and requirements, then produce a clear implementation plan.
-
-You must NOT make any changes. Only read, analyze, and plan.
-
-Input format you'll receive:
-- Context/findings from a scout agent
-- Original query or requirements
-
-Output format:
-
-## Goal
-One sentence summary of what needs to be done.
-
-## Plan
-Numbered steps, each small and actionable:
-1. Step one - specific file/function to modify
-2. Step two - what to add/change
-3. ...
-
-## Files to Modify
-- `path/to/file.ts` - what changes
-- `path/to/other.ts` - what changes
-
-## New Files (if any)
-- `path/to/new.ts` - purpose
-
-## Risks
-Anything to watch out for.
-
-Keep the plan concrete. The worker agent will execute it verbatim.

package/examples/extensions/subagent/agents/reviewer.md

@@ -1,35 +0,0 @@
----
-name: reviewer
-description: Code review specialist for quality and security analysis
-tools: read, grep, find, ls, bash
-model: claude-sonnet-4-5
----
-
-You are a senior code reviewer. Analyze code for quality, security, and maintainability.
-
-Bash is for read-only commands only: `git diff`, `git log`, `git show`. Do NOT modify files or run builds.
-Assume tool permissions are not perfectly enforceable; keep all bash usage strictly read-only.
-
-Strategy:
-1. Run `git diff` to see recent changes (if applicable)
-2. Read the modified files
-3. Check for bugs, security issues, code smells
-
-Output format:
-
-## Files Reviewed
-- `path/to/file.ts` (lines X-Y)
-
-## Critical (must fix)
-- `file.ts:42` - Issue description
-
-## Warnings (should fix)
-- `file.ts:100` - Issue description
-
-## Suggestions (consider)
-- `file.ts:150` - Improvement idea
-
-## Summary
-Overall assessment in 2-3 sentences.
-
-Be specific with file paths and line numbers.

package/examples/extensions/subagent/agents/scout.md

@@ -1,50 +0,0 @@
----
-name: scout
-description: Fast codebase recon that returns compressed context for handoff to other agents
-tools: read, grep, find, ls, bash
-model: claude-haiku-4-5
----
-
-You are a scout. Quickly investigate a codebase and return structured findings that another agent can use without re-reading everything.
-
-Your output will be passed to an agent who has NOT seen the files you explored.
-
-Thoroughness (infer from task, default medium):
-- Quick: Targeted lookups, key files only
-- Medium: Follow imports, read critical sections
-- Thorough: Trace all dependencies, check tests/types
-
-Strategy:
-1. grep/find to locate relevant code
-2. Read key sections (not entire files)
-3. Identify types, interfaces, key functions
-4. Note dependencies between files
-
-Output format:
-
-## Files Retrieved
-List with exact line ranges:
-1. `path/to/file.ts` (lines 10-50) - Description of what's here
-2. `path/to/other.ts` (lines 100-150) - Description
-3. ...
-
-## Key Code
-Critical types, interfaces, or functions:
-
-```typescript
-interface Example {
-  // actual code from the files
-}
-```
-
-```typescript
-function keyFunction() {
-  // actual implementation
-}
-```
-
-## Architecture
-Brief explanation of how the pieces connect.
-
-## Start Here
-Which file to look at first and why.

package/examples/extensions/subagent/agents/worker.md

@@ -1,24 +0,0 @@
----
-name: worker
-description: General-purpose subagent with full capabilities, isolated context
-model: claude-sonnet-4-5
----
-
-You are a worker agent with full capabilities. You operate in an isolated context window to handle delegated tasks without polluting the main conversation.
-
-Work autonomously to complete the assigned task. Use all available tools as needed.
-
-Output format when finished:
-
-## Completed
-What was done.
-
-## Files Changed
-- `path/to/file.ts` - what changed
-
-## Notes (if any)
-Anything the main agent should know.
-
-If handing off to another agent (e.g. reviewer), include:
-- Exact file paths changed
-- Key functions/types touched (short list)

package/examples/extensions/subagent/agents.ts

@@ -1,126 +0,0 @@
-/**
- * Agent discovery and configuration
- */
-
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { CONFIG_DIR_NAME, getAgentDir, parseFrontmatter } from "@astralyn/pi";
-
-export type AgentScope = "user" | "project" | "both";
-
-export interface AgentConfig {
-	name: string;
-	description: string;
-	tools?: string[];
-	model?: string;
-	systemPrompt: string;
-	source: "user" | "project";
-	filePath: string;
-}
-
-export interface AgentDiscoveryResult {
-	agents: AgentConfig[];
-	projectAgentsDir: string | null;
-}
-
-function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig[] {
-	const agents: AgentConfig[] = [];
-
-	if (!fs.existsSync(dir)) {
-		return agents;
-	}
-
-	let entries: fs.Dirent[];
-	try {
-		entries = fs.readdirSync(dir, { withFileTypes: true });
-	} catch {
-		return agents;
-	}
-
-	for (const entry of entries) {
-		if (!entry.name.endsWith(".md")) continue;
-		if (!entry.isFile() && !entry.isSymbolicLink()) continue;
-
-		const filePath = path.join(dir, entry.name);
-		let content: string;
-		try {
-			content = fs.readFileSync(filePath, "utf-8");
-		} catch {
-			continue;
-		}
-
-		const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
-
-		if (!frontmatter.name || !frontmatter.description) {
-			continue;
-		}
-
-		const tools = frontmatter.tools
-			?.split(",")
-			.map((t: string) => t.trim())
-			.filter(Boolean);
-
-		agents.push({
-			name: frontmatter.name,
-			description: frontmatter.description,
-			tools: tools && tools.length > 0 ? tools : undefined,
-			model: frontmatter.model,
-			systemPrompt: body,
-			source,
-			filePath,
-		});
-	}
-
-	return agents;
-}
-
-function isDirectory(p: string): boolean {
-	try {
-		return fs.statSync(p).isDirectory();
-	} catch {
-		return false;
-	}
-}
-
-function findNearestProjectAgentsDir(cwd: string): string | null {
-	let currentDir = cwd;
-	while (true) {
-		const candidate = path.join(currentDir, CONFIG_DIR_NAME, "agents");
-		if (isDirectory(candidate)) return candidate;
-
-		const parentDir = path.dirname(currentDir);
-		if (parentDir === currentDir) return null;
-		currentDir = parentDir;
-	}
-}
-
-export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {
-	const userDir = path.join(getAgentDir(), "agents");
-	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
-
-	const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
-	const projectAgents = scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
-
-	const agentMap = new Map<string, AgentConfig>();
-
-	if (scope === "both") {
-		for (const agent of userAgents) agentMap.set(agent.name, agent);
-		for (const agent of projectAgents) agentMap.set(agent.name, agent);
-	} else if (scope === "user") {
-		for (const agent of userAgents) agentMap.set(agent.name, agent);
-	} else {
-		for (const agent of projectAgents) agentMap.set(agent.name, agent);
-	}
-
-	return { agents: Array.from(agentMap.values()), projectAgentsDir };
-}
-
-export function formatAgentList(agents: AgentConfig[], maxItems: number): { text: string; remaining: number } {
-	if (agents.length === 0) return { text: "none", remaining: 0 };
-	const listed = agents.slice(0, maxItems);
-	const remaining = agents.length - listed.length;
-	return {
-		text: listed.map((a) => `${a.name} (${a.source}): ${a.description}`).join("; "),
-		remaining,
-	};
-}