pi-soly 1.9.3 → 1.11.0

package/init.ts

@@ -0,0 +1,302 @@
+// =============================================================================
+// init.ts — Scaffold a new soly project
+// =============================================================================
+//
+// Creates the initial `.agents/` directory structure for a new project, with
+// optional project-type templates. Idempotent — existing files are kept.
+//
+// Layout created:
+//   .agents/
+//   ├── ROADMAP.md         (single phase "01-bootstrap" + checklist)
+//   ├── STATE.md           (empty template with frontmatter)
+//   ├── docs/
+//   │   └── vision.md      (placeholder for intent doc)
+//   ├── rules/
+//   │   └── code-style.md  (TypeScript-friendly defaults)
+//   ├── phases/
+//   │   └── .gitkeep
+//   ├── iterations/
+//   │   └── .gitkeep
+//   └── HANDOFF.json       ({ "version": 1, "snapshot": null })
+//   agents.md              (AGENTS.md standard, top-level)
+//
+// Templates:
+//   "minimal"  — just the structure, no rules/docs
+//   "web-app"  — adds routing/, auth/, api/ example rules
+//   "library"  — adds publishing/, testing/, breaking-changes/ example rules
+//   "cli"      — adds command/, flags/, shell-compat/ example rules
+//
+// Usage:
+//   /soly-init                  # interactive: pick template
+//   /soly-init minimal          # no prompts
+//   /soly-init web-app --yes
+// =============================================================================
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { SOLY_DIRNAME } from "./core.js";
+
+export type InitTemplate = "minimal" | "web-app" | "library" | "cli";
+
+/** UI primitives. */
+export interface InitUI {
+	notify: (text: string, level?: "info" | "warning" | "error") => void;
+	select: (label: string, options: string[]) => Promise<string | undefined>;
+	confirm: (title: string, message: string) => Promise<boolean>;
+	input: (label: string, placeholder?: string) => Promise<string | undefined>;
+}
+
+export interface InitOptions {
+	/** Skip template picker + confirm dialog. */
+	autoYes?: boolean;
+	/** Force template (otherwise: picker or default 'minimal'). */
+	template?: InitTemplate;
+	/** Project name (for STATE.md). Defaults to cwd basename. */
+	projectName?: string;
+}
+
+const ROADMAP_MINIMAL = `# Roadmap
+
+| # | Phase | Status | Notes |
+|---|-------|--------|-------|
+| 01 | bootstrap | pending | Initial setup |
+
+Open \`/plan 1\` to start the first phase.
+`;
+
+const STATE_MINIMAL = `---
+milestone: 0.1.0
+current_position: ready
+last_updated: ${new Date().toISOString().slice(0, 10)}
+---
+
+# Project state
+
+Use \`/soly\` to see current state. Use \`/plan N\` to plan phase N.
+
+## Decisions
+
+| Date | Decision | Why |
+|------|----------|-----|
+| ${new Date().toISOString().slice(0, 10)} | Initial scaffold | Created by \`soly init\` |
+`;
+
+const VISION_DOC = `# Vision
+
+What does this project do? Who is it for? Why does it exist?
+
+Replace this paragraph with 1-2 sentences describing the project's purpose.
+
+## Goals
+
+- Goal 1
+- Goal 2
+
+## Non-goals
+
+- Non-goal 1
+- Non-goal 2
+`;
+
+const CODE_STYLE_RULE = `# Code style
+
+- Prefer \`type\` over \`interface\` for object shapes
+- Use \`strict\` mode
+- Never use \`any\` — use \`unknown\` and narrow
+- Functions under 50 lines; extract helpers beyond
+`;
+
+const HANDOFF_INITIAL = JSON.stringify({ version: 1, snapshot: null }, null, 2) + "\n";
+
+/** Template-specific extra rules. Each is a (filename, content) pair. */
+const TEMPLATE_EXTRAS: Record<InitTemplate, Array<{ file: string; content: string }>> = {
+	minimal: [],
+	"web-app": [
+		{
+			file: "rules/routing.md",
+			content: `# Routing
+
+- Each route is a file under \`src/routes/<path>.ts\`
+- Loader and action in same file
+- Typed params via \`Route.LoaderArgs\`
+`,
+		},
+		{
+			file: "rules/auth.md",
+			content: `# Auth
+
+- Sessions in HTTP-only cookies
+- CSRF tokens on all mutations
+- Never trust client-supplied user IDs
+`,
+		},
+	],
+	library: [
+		{
+			file: "rules/publishing.md",
+			content: `# Publishing
+
+- Semver strictly: breaking changes bump major
+- CHANGELOG.md updated with every release
+- Public API = what's in the README + index.ts
+`,
+		},
+		{
+			file: "rules/testing.md",
+			content: `# Testing
+
+- One assertion per test (ideally)
+- Tests live next to source as \`*.test.ts\`
+- Run \`bun test\` before every commit
+`,
+		},
+	],
+	cli: [
+		{
+			file: "rules/commands.md",
+			content: `# Commands
+
+- Each command is a file under \`src/commands/<name>.ts\`
+- Export \`name\`, \`description\`, \`run(args: string[]): Promise<void>\`
+- All errors exit non-zero with a message on stderr
+`,
+		},
+		{
+			file: "rules/flags.md",
+			content: `# Flags
+
+- \`--flag value\` style, not GNU \`-f value\`
+- Short aliases only for the 3-4 most common flags
+- \`--help\` always supported, auto-generated from command metadata
+`,
+		},
+	],
+};
+
+const AGENTS_MD_TOP = `# Agent conventions
+
+This project uses [soly](https://github.com/lowern1ght/pi-soly) for project management.
+
+## Quick reference
+
+- \`/plan N\` — plan phase N
+- \`/execute N.MM\` — execute plan MM in phase N
+- \`/inspect\` — see current state
+- \`/pause\` — save handoff for later
+- \`/resume\` — restore from handoff
+
+## State
+
+- \`.agents/ROADMAP.md\` — phase table
+- \`.agents/STATE.md\` — current position + decisions
+- \`.agents/docs/\` — intent docs (vision, architecture, ...)
+- \`.agents/rules/\` — project rules (style, testing, ...)
+- \`.agents/phases/<NN>-<slug>/\` — one dir per phase
+- \`.agents/HANDOFF.json\` — pause snapshot
+`;
+
+/** Run the init flow. Returns true if project was created. */
+export async function initSolyProject(
+	cwd: string,
+	ui: InitUI,
+	options: InitOptions = {},
+): Promise<{ created: boolean; template: InitTemplate | null; projectName: string }> {
+	const projectName = options.projectName ?? path.basename(cwd);
+	const safeProjectName = projectName || "project";
+	const agentsDir = path.join(cwd, SOLY_DIRNAME);
+
+	// Preconditions
+	if (fs.existsSync(agentsDir) || fs.existsSync(path.join(cwd, ".soly"))) {
+		ui.notify(
+			`soly-init: project already initialized (found ${SOLY_DIRNAME}/ or .soly/). ` +
+				`Aborting to avoid overwriting.`,
+			"error",
+		);
+		return { created: false, template: null, projectName };
+	}
+
+	// Pick template
+	let template: InitTemplate | null = options.template ?? null;
+	if (!template && !options.autoYes) {
+		const pick = await ui.select(
+			"template:",
+			["minimal", "web-app", "library", "cli"],
+		);
+		if (!pick) {
+			ui.notify("soly-init: cancelled", "info");
+			return { created: false, template: null, projectName };
+		}
+		template = pick as InitTemplate;
+	}
+	if (!template) template = "minimal";
+
+	// Confirm (unless --yes)
+	if (!options.autoYes) {
+		const ok = await ui.confirm(
+			`soly init (${template})`,
+			`Create .agents/ structure in:\n  ${cwd}\n\nProject name: ${projectName}`,
+		);
+		if (!ok) {
+			ui.notify("soly-init: cancelled", "info");
+			return { created: false, template: null, projectName };
+		}
+	}
+
+	// Build
+	fs.mkdirSync(path.join(agentsDir, "docs"), { recursive: true });
+	fs.mkdirSync(path.join(agentsDir, "rules"), { recursive: true });
+	fs.mkdirSync(path.join(agentsDir, "phases"), { recursive: true });
+	fs.mkdirSync(path.join(agentsDir, "iterations"), { recursive: true });
+
+	writeIfMissing(path.join(agentsDir, "ROADMAP.md"), ROADMAP_MINIMAL);
+	writeIfMissing(path.join(agentsDir, "STATE.md"), STATE_MINIMAL);
+	writeIfMissing(path.join(agentsDir, "docs", "vision.md"), VISION_DOC);
+	writeIfMissing(path.join(agentsDir, "rules", "code-style.md"), CODE_STYLE_RULE);
+	writeIfMissing(path.join(agentsDir, "HANDOFF.json"), HANDOFF_INITIAL);
+	fs.writeFileSync(path.join(agentsDir, "phases", ".gitkeep"), "");
+	fs.writeFileSync(path.join(agentsDir, "iterations", ".gitkeep"), "");
+
+	// Top-level AGENTS.md
+	writeIfMissing(path.join(cwd, "AGENTS.md"), AGENTS_MD_TOP);
+
+	// Template extras
+	for (const extra of TEMPLATE_EXTRAS[template]) {
+		writeIfMissing(path.join(agentsDir, extra.file), extra.content);
+	}
+
+	// Optional project name in STATE.md
+	if (safeProjectName !== "project") {
+		try {
+			const statePath = path.join(agentsDir, "STATE.md");
+			const cur = fs.readFileSync(statePath, "utf-8");
+			const updated = cur.replace(/^# Project state$/m, `# Project state — ${projectName}`);
+			fs.writeFileSync(statePath, updated, "utf-8");
+		} catch { /* best-effort */ }
+	}
+
+	// Report
+	const created: string[] = [
+		".agents/ROADMAP.md",
+		".agents/STATE.md",
+		".agents/HANDOFF.json",
+		".agents/docs/vision.md",
+		".agents/rules/code-style.md",
+		".agents/phases/.gitkeep",
+		".agents/iterations/.gitkeep",
+		"AGENTS.md",
+	];
+	for (const extra of TEMPLATE_EXTRAS[template]) {
+		created.push(`.agents/${extra.file}`);
+	}
+	ui.notify(
+		`soly-init: done (${template}). Created:\n  - ${created.join("\n  - ")}\n\n` +
+			`Next:\n  1. Edit \`.agents/docs/vision.md\`\n  2. \`/plan 1\` to start the first phase`,
+		"info",
+	);
+	return { created: true, template, projectName: safeProjectName };
+}
+
+function writeIfMissing(file: string, content: string): void {
+	if (fs.existsSync(file)) return;
+	fs.writeFileSync(file, content, "utf-8");
+}

package/mcp/CHANGELOG.md

@@ -0,0 +1,384 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [2.10.0] - 2026-06-13
+
+### Added
+- Added manual remote/headless OAuth proxy actions for copying authorization URLs and completing pasted redirect URLs or codes. Thanks @Gabrielgvl for PR #120.
+
+### Fixed
+- Honored user `tui.select.*` keybindings in MCP management, setup, and auth panels. Thanks @owenniles for PR #138.
+- Included configured OAuth scopes in authorization-code flows while preserving token endpoint authentication method selection. Thanks @carlosdagos for PR #140.
+- Fixed MCP elicitation on stock Pi, including form dialogs with validation and review, consent-based URL handling, URL-required errors, completion notifications, and TUI-only browser navigation. Thanks @dmmulroy for PR #139.
+- Expanded MCP schema formatting for nested `anyOf`/`oneOf` variants, `const` discriminators, nested object properties, and array items.
+
+## [2.9.0] - 2026-06-04
+
+### Added
+- Added MCP elicitation support with Pi form prompts and browser-opening URL requests.
+
+### Fixed
+- Rejected non-http/https MCP URL elicitations before prompting or opening a browser.
+- Preserved empty string form values for MCP string elicitations unless schema constraints reject them.
+
+## [2.8.0] - 2026-05-25
+
+### Added
+- Added per-server OAuth `redirectUri`, `clientName`, and `clientUri` overrides for pre-registered callbacks and dynamic client metadata.
+
+### Fixed
+- Avoided OAuth callback port exhaustion by starting the callback server lazily and using OS-assigned ports for dynamic OAuth flows.
+- Re-register dynamic OAuth clients before browser auth when cached redirect URI metadata is missing or no longer matches the active callback URI.
+
+## [2.7.0] - 2026-05-22
+
+### Added
+- Added TUI call rendering for MCP proxy and direct tool inputs. Thanks @dmmulroy for PR #102.
+
+### Fixed
+- Hardened OAuth credential storage paths against server-name path traversal without rejecting valid configured server names.
+- Rejected unsafe regex-mode MCP search patterns before executing them.
+
+## [2.6.1] - 2026-05-13
+
+### Added
+- Added `/mcp logout <server>` to clear stored OAuth credentials and disconnect the server. Thanks @mattzcarey for PR #96.
+
+### Fixed
+- Cancel pending OAuth callbacks when logging out of an MCP server.
+
+## [2.6.0] - 2026-05-10
+
+### Added
+- Added a no-argument `/mcp-auth` OAuth picker and in-panel auth shortcut for OAuth-capable MCP servers.
+- Added compact collapsed rendering for MCP proxy and direct-tool result rows while keeping full tool results available when expanded.
+
+### Changed
+- Migrated Pi runtime dependencies and imports from deprecated `@mariozechner/*` packages to `@earendil-works/*` packages.
+
+### Fixed
+- Re-register dynamic OAuth clients during fresh auth when cached DCR client info exists without tokens, avoiding dead authorization URLs after server-side client invalidation.
+- Kept OAuth tokens, dynamic client info, PKCE verifiers, and OAuth state bound to the server URL so stale credentials cannot be reused after a server URL changes.
+- Kept the `/mcp-auth` OAuth picker search focused on OAuth server rows and prevented hidden panel shortcuts from unexpectedly launching auth.
+- Kept long MCP error results expanded in compact tool result rendering.
+
+## [2.5.4] - 2026-05-04
+
+### Changed
+- Ignored npm lockfiles and removed checked-in `package-lock.json` files.
+
+### Fixed
+- Resolved `${VAR}` and `$env:VAR` placeholders in HTTP bearer tokens.
+- Honored MCP sampling `modelPreferences.hints` before falling back to the current/default model.
+
+## [2.5.3] - 2026-05-01
+
+### Added
+- Added environment variable and `~` expansion for stdio server `cwd` values.
+
+## [2.5.2] - 2026-04-29
+
+### Fixed
+- Respected `PI_CODING_AGENT_DIR` for Pi-owned MCP config and state files, including metadata cache, npx cache, onboarding state, OAuth credentials, and `pi-mcp-adapter init` writes.
+
+## [2.5.1] - 2026-04-24
+
+### Fixed
+- Changed OAuth browser callbacks to `http://localhost:<port>/callback` for pre-registered clients such as Slack MCP. Thanks @shenal for PR #53.
+
+## [2.5.0] - 2026-04-24
+
+### Added
+- Added MCP `sampling/createMessage` support with conservative human approval by default and opt-in `settings.samplingAutoApprove` for non-interactive flows.
+- Added configured Vitest coverage for OAuth provider authorization fallback behavior.
+- Added `test:oauth-provider` for running the root OAuth provider node test with the required TypeScript loader.
+
+### Fixed
+- Applied `settings.authRequiredMessage` to proxy and direct-tool auth-required paths, including non-UI `autoAuth` failures.
+- Fixed `/mcp-auth <server>` reporting success for expired stored OAuth tokens without forcing the SDK refresh/re-auth flow.
+- Kept `mcp` search focused on MCP tools and added a direct-call hint when native Pi tools are accidentally routed through the proxy.
+
+## [2.4.2] - 2026-04-22
+
+### Fixed
+- Migrated extension tool schemas from `@sinclair/typebox` to `typebox` 1.x so packaged installs follow Pi's current extension runtime contract.
+
+### Changed
+- Replaced the legacy `@sinclair/typebox` runtime dependency with `typebox`.
+
+## [2.4.1] - 2026-04-22
+
+### Added
+- Added standard-MCP-first config discovery: `~/.config/mcp/mcp.json` and project `.mcp.json` now load automatically, with Pi-owned files preserved as override layers.
+- Added `pi-mcp-adapter init` as a native post-install helper that detects host-specific MCP configs and scaffolds Pi compatibility imports without using the old raw GitHub downloader flow.
+- Added first-run onboarding inside the extension: `/mcp` now shows shared-config hints or actionable empty states, and `/mcp setup` opens a guided setup flow for compatibility imports, minimal `.mcp.json` scaffolding, detected config paths, RepoPrompt quick-add, and exact before/after write previews.
+- Added automatic Pi-core reload after setup or direct-tool config changes, using the same flow as `/reload` so freshly configured direct tools can appear without a manual restart.
+- Added a dedicated Pi-owned onboarding state file so shared-config hints behave as one-time guidance instead of repeating every session.
+
+### Changed
+- Updated config precedence to prefer shared MCP files first, then Pi overrides, with `.pi/mcp.json` acting as the final Pi-specific project override.
+- Updated Claude Code compatibility probing to prefer modern Claude MCP config locations before legacy paths.
+- Updated project scaffolding so generated `.mcp.json` files are safe minimal shells instead of fake placeholder servers that fail on first reload.
+- Updated the setup panel and README for clearer first-run guidance, improved spacing, and a more digestible shared-MCP-first setup story.
+
+## [2.4.0] - 2026-04-13
+
+### Added
+- `settings.disableProxyTool` to hide the `mcp` proxy tool once configured direct tools are fully available from cache. Thanks @tanavamsikrishna for PR #41.
+- Per-server `excludeTools` to hide specific MCP tools/resources by original or prefixed name across direct tools, proxy discovery, and the `/mcp` panel. Thanks @ahmadaccino for issue #36.
+- `settings.autoAuth` to optionally trigger OAuth automatically from proxy/direct tool usage, then rerun the original blocked connect/tool operation once after authentication succeeds. Thanks @unimonkiez for issue #34.
+
+### Fixed
+- Regenerated `package-lock.json` so the root lockfile metadata matches `package.json` again, including the declared `open`, `@types/bun`, `@types/open`, and `tsx` entries.
+- Kept the `mcp` proxy tool available as a first-session fallback when configured direct tools are still missing cache metadata, avoiding no-tool startup gaps.
+
+## [2.3.5] - 2026-04-13
+
+### Fixed
+- Session lifecycle now always tears down OAuth callback state on restart and shutdown, preventing callback-server leaks across session transitions.
+- OAuth callback server now calls `unref()` after successful bind so it no longer keeps sub-agent processes alive by itself.
+- Strict OAuth port mode now rebinds to the configured callback port when safe, while refusing to switch ports when authorizations are still pending.
+- Added focused lifecycle/callback-server regression coverage for teardown, `unref()`, strict rebinding, and pending-auth guardrails.
+- Thanks @blai for the investigation and PR #43 that surfaced the sub-agent hang/root lifecycle issues.
+
+## [2.3.4] - 2026-04-12
+
+### Fixed
+- OAuth callback handling now allows dynamic-registration flows to fall back to a free local port when the preferred callback port is busy, while keeping pre-registered clients on their exact configured redirect port.
+- Documented the new callback-port behavior and added focused auth-flow regression coverage.
+
+## [2.3.3] - 2026-04-12
+
+### Fixed
+- Remove the blank footer status line when no MCP servers are configured by clearing the MCP status entry instead of setting it to an empty string. Thanks @HazAT for PR #27.
+
+## [2.3.2] - 2026-04-11
+
+### Added
+- Optional `oauth.grantType: "client_credentials"` for non-interactive machine-to-machine OAuth on HTTP MCP servers.
+
+### Fixed
+- `/mcp-auth <server>` now handles `client_credentials` without browser/callback flow.
+- MCP panel status no longer marks `client_credentials` servers as auth-blocked solely because no stored user tokens exist yet.
+- OAuth auth flow now closes temporary transports consistently on success, refresh, and auth removal paths.
+- Init paths now preserve debug-level context for previously silent direct-tool bootstrap and lazy-connect failures.
+
+## [2.3.1] - 2026-04-11
+
+### Fixed
+- Removed `/mcp-auth-callback`. OAuth auth now hard-cuts to `/mcp-auth <server>` only.
+
+## [2.3.0] - 2026-04-11
+
+### Added
+- OAuth callback server initialization on session start and a deprecated `/mcp-auth-callback` command that now points users to `/mcp-auth <server>`.
+
+### Fixed
+- OAuth `needs-auth` handling across `/mcp` status/panel, `mcp({ connect })`, `mcp({ tool })`, reconnect flow, lazy/direct tool execution, and startup bootstrap.
+- OAuth callback cleanup now cancels by stored OAuth state and closes pending transports on failure/cancel paths.
+- Callback server now fails fast when the OAuth callback port is occupied by another process.
+- Package manifest test now ignores root `*.test.ts` files.
+
+## [2.2.2] - 2026-04-03
+
+### Fixed
+- Session lifecycle teardown now handles repeated `session_start` transitions safely and prevents stale async init results from replacing newer state.
+- Shutdown now still runs `gracefulShutdown()` even if metadata cache flushing throws, avoiding leaked MCP processes.
+- Proxy/direct tool init error paths now preserve and surface underlying error messages instead of returning generic failures.
+- Invalid `mcp` tool `args` now fail by throwing with parse/type context instead of returning non-failing tool payloads.
+- Added focused lifecycle regressions tests for stale init cleanup and init-error visibility.
+
+## [2.2.1] - 2026-03-23
+
+### Fixed
+- Added `promptSnippet` to MCP proxy tool and direct MCP tools so they appear in the system prompt's Available tools section (required since pi 0.59.0)
+
+## [2.2.0] - 2026-03-16
+
+### Added
+- **MCP UI Integration** - Support for the [MCP UI](https://github.com/MCP-UI-Org/mcp-ui) standard. Tools with `_meta.ui.resourceUri` open interactive UIs:
+  - Bidirectional AppBridge communication (tool calls, messages, context updates)
+  - Works with both stdio and HTTP MCP servers
+  - User consent management for tool calls from UI (configurable: never/once-per-server/always)
+  - Keyboard shortcuts: Cmd/Ctrl+Enter to complete, Escape to cancel
+  - UI prompts/intents trigger agent turns via `pi.sendMessage({ triggerTurn: true })`
+  - `mcp({ action: "ui-messages" })` retrieves accumulated messages from UI sessions
+
+- **Session reuse** - When the agent calls the same tool while its UI is already open, results push to the existing window instead of replacing it. Per-call stream IDs with independent sequences. Error results scoped to the individual call.
+
+- **Glimpse integration** - MCP UI opens in a native macOS WKWebView window instead of a browser tab when [Glimpse](https://github.com/hazat/glimpse) is installed (`pi install npm:glimpseui`). Falls back to browser on non-macOS or when unavailable. Override with `MCP_UI_VIEWER=browser` or `MCP_UI_VIEWER=glimpse`.
+
+- **Logger module** (`logger.ts`) - Centralized logging with levels (debug/info/warn/error), contextual child loggers, and `MCP_UI_DEBUG=1` env var.
+
+- **Error types** (`errors.ts`) - Structured errors with recovery hints: `ResourceFetchError`, `ResourceParseError`, `BridgeConnectionError`, `ConsentError`, `SessionError`, `ServerError`, and `wrapError()` helper.
+
+- **Test suite** - 178 tests covering consent manager, UI resource handler, host HTML template, logger, and error types.
+
+- **Interactive visualizer example** (`examples/interactive-visualizer`) - Minimal MCP server demonstrating charts (bar/line/pie/doughnut via Chart.js), bidirectional messaging, and streaming.
+
+### Fixed
+- Host-iframe timing: bridge now connects before loading iframe, fixing `ui/initialize` timeout on first load
+- All internal `log.info` calls demoted to `log.debug` to eliminate stdout noise during normal use
+
+### Technical Notes
+- Uses local minified AppBridge bundle (408KB) to avoid CDN Zod bundling issues
+- Serves app HTML from `/ui-app` endpoint instead of blob URLs to avoid iframe issues
+- SSE for real-time tool result streaming to browser
+
+## [2.1.2] - 2026-02-03
+
+### Changed
+- Added demo video and `pi.video` field to package.json for pi package browser.
+
+## [2.1.0] - 2026-02-02
+
+### Added
+- **Direct tool registration** - Promote specific MCP tools to first-class Pi tools via `directTools` config (per-server or global). Direct tools appear in the agent's tool list alongside builtins, so the LLM uses them without needing to search through the proxy first. Registers from cached metadata at startup — no server connections needed.
+- **`/mcp` interactive panel** - New TUI overlay replacing the text-based status dump. Shows server connection status, tool lists with direct/proxy toggles, token cost estimates, inline reconnect, and auth notices. Changes written to config on save.
+- **Auto-enriched proxy description** - The `mcp` proxy tool description now includes server names and tool counts from the metadata cache, so the LLM knows what's available without a search call (~30 extra tokens).
+- **`MCP_DIRECT_TOOLS` env var** - Subagent processes receive their direct tool configuration via environment variable, keeping subagents lean by default.
+- **First-run bootstrap** - Servers with `directTools` configured but no cache entry are connected during `session_start` to populate the cache. Direct tools become available after restart.
+- Config provenance tracking for correct write-back to user/project/import sources
+- Builtin name collision guard (skips direct tools that would shadow `read`, `write`, etc.)
+- Cross-server name deduplication for `prefix: "none"` and `prefix: "short"` modes
+
+## [2.0.1] - 2026-02-01
+
+### Fixed
+- Adapt execute signature to pi v0.51.0: add signal, onUpdate, ctx parameters
+
+## [2.0.0] - 2026-01-29
+
+### Changed
+- **BREAKING: Lazy startup by default** - All servers now default to `lifecycle: "lazy"` and only connect when a tool call needs them. Previously all servers connected eagerly on session start. Set `lifecycle: "keep-alive"` or `lifecycle: "eager"` to restore the old behavior per-server.
+- **Idle timeout** - Connected servers are automatically disconnected after 10 minutes of inactivity (configurable via `settings.idleTimeout` or per-server `idleTimeout`). Cached metadata keeps search/list working after disconnect. Set `idleTimeout: 0` to disable.
+- `/mcp reconnect` accepts an optional server name to connect or reconnect a single server
+
+### Added
+- **Metadata cache** - Tool and resource metadata persisted to `~/.pi/agent/mcp-cache.json`. Enables search/list/describe without live connections. Per-server config hashing with 7-day staleness. Multi-session safe via read-merge-write with per-process tmp files.
+- **npx binary resolution** - Resolves npx package binaries to direct paths, eliminating the ~143 MB npm parent process per server. Persistent cache at `~/.pi/agent/mcp-npx-cache.json` with 24h TTL.
+- **`mcp({ connect: "server-name" })` mode** - Explicitly trigger connection and metadata refresh for a named server
+- **Failure backoff** - Servers that fail to connect are skipped for 60 seconds to avoid repeated connection storms
+- **In-flight tracking** - Active tool calls prevent idle timeout from shutting down a server mid-request
+- **Prefix-match fallback** - Tool calls with unrecognized names try to match a server prefix and lazy-connect the matching server
+- Lifecycle options: `lazy` (default), `eager` (connect at startup, no auto-reconnect), `keep-alive` (unchanged)
+- Per-server `idleTimeout` override and global `settings.idleTimeout`
+- First-run bootstrap: connects all servers on first session to populate the cache
+
+### Fixed
+- Connection close race condition: concurrent close + connect no longer orphans server processes
+- **Fuzzy tool name matching** - Hyphens and underscores are treated as equivalent during tool lookup. MCP tools like `resolve-library-id` are now found when called as `resolve_library_id`, which LLMs naturally guess since the prefix separator is `_`.
+- **Better "tool not found" errors** - When a server is identified (via prefix match or override) but the tool isn't found, the error now lists that server's available tools so the LLM can self-correct immediately instead of needing a separate list call
+
+## [1.6.0] - 2026-01-29
+
+### Added
+- **Unified pi tool search** - `mcp({ search: "..." })` now searches both MCP tools and Pi tools (from installed extensions)
+- Pi tools appear first in results with `[pi tool]` prefix
+- Details object includes `server: "pi"` for pi tools
+- Banner image for README
+
+## [1.5.1] - 2026-01-26
+
+### Changed
+- Added `pi-package` keyword for npm discoverability (pi v0.50.0 package system)
+
+## [1.5.0] - 2026-01-22
+
+### Changed
+- **BREAKING: `args` parameter is now a JSON string** - The `args` parameter which previously accepted an object now accepts a JSON string. This change was required for compatibility with Claude's Vertex AI API (`google-antigravity` provider) which rejects `patternProperties` in JSON schemas (generated by `Type.Record()`).
+
+### Added
+- **Type validation for args** - Parsed args are now validated to ensure they're a JSON object (not null, array, or primitive). Clear error messages for invalid input.
+- **`isError: true` on error responses** - JSON parse errors and type validation errors now properly set `isError: true` to indicate failure to the LLM.
+
+### Migration
+```typescript
+// Before (1.4.x)
+mcp({ tool: "my_tool", args: { key: "value" } })
+
+// After (1.5.0)
+mcp({ tool: "my_tool", args: '{"key": "value"}' })
+```
+
+## [1.4.1] - 2026-01-19
+
+### Changed
+
+- Status bar shows server count instead of tool count ("MCP: 5 servers")
+
+## [1.4.0] - 2026-01-19
+
+### Changed
+
+- **Non-blocking startup** - Pi starts immediately, MCP servers connect in background. First MCP call waits only if init isn't done yet.
+
+### Fixed
+
+- Tool metadata now includes `inputSchema` after `/mcp reconnect` (was missing, breaking describe and error hints)
+
+## [1.3.0] - 2026-01-19
+
+### Changed
+
+- **Parallel server connections** - All MCP servers now connect in parallel on startup instead of sequentially, significantly faster with many servers
+
+## [1.2.2] - 2026-01-19
+
+### Fixed
+
+- Installer now downloads from `main` branch (renamed from `master`)
+
+## [1.2.1] - 2026-01-19
+
+### Added
+
+- **npx installer** - Run `npx pi-mcp-adapter` to install (downloads files, installs deps, configures settings.json)
+
+## [1.1.0] - 2026-01-19
+
+### Changed
+
+- **Search includes schemas by default** - Search results now include parameter schemas, reducing tool calls needed (search + call instead of search + describe + call)
+- **Space-separated search terms match as OR** - `"navigate screenshot"` finds tools matching either word (like most search engines)
+- **Suppress server stderr by default** - MCP server logs no longer clutter terminal on startup
+- Use `includeSchemas: false` for compact output without schemas
+- Use `debug: true` per-server to show stderr when troubleshooting
+
+## [1.0.0] - 2026-01-19
+
+### Added
+
+- **Single unified `mcp` tool** with token-efficient architecture (~200 tokens vs ~15,000 for individual tools)
+- **Five operation modes:**
+  - `mcp({})` - Show server status
+  - `mcp({ server: "name" })` - List tools from a server
+  - `mcp({ search: "query" })` - Search tools by name/description
+  - `mcp({ describe: "tool_name" })` - Show tool details and parameter schema
+  - `mcp({ tool: "name", args: {...} })` - Call a tool
+- **Stdio transport** for local MCP servers (command + args)
+- **HTTP transport** with automatic fallback (StreamableHTTP → SSE)
+- **Config imports** from Cursor, Claude Code, Claude Desktop, VS Code, Windsurf, Codex
+- **Resource tools** - MCP resources exposed as callable tools
+- **OAuth support** - Token file-based authentication
+- **Bearer token auth** - Static or environment variable tokens
+- **Keep-alive connections** with automatic health checks and reconnection
+- **Schema on-demand** - Parameter schemas shown in `describe` mode and error responses
+- **Commands:**
+  - `/mcp` or `/mcp status` - Show server status
+  - `/mcp tools` - List all tools
+  - `/mcp reconnect` - Force reconnect all servers
+  - `/mcp-auth <server>` - Show OAuth setup instructions
+
+### Architecture
+
+- Tools stored in metadata map, not registered individually with Pi
+- MCP server validates arguments (no client-side schema conversion)
+- Reconnect callback updates metadata after auto-reconnect
+- Human-readable schema formatting for LLM consumption