Add PI support

[SamuelLHuber]

This PR adds https://pi.dev/ support to Smithers

Here is the spec used for development with codex-5.3 and codex-5.2 as well as manual verification using Smithers myself with Pi + scripts/test-pi-integration.sh (you'll need to have the pi binary installed and pi-mono repo checkedout locally)

---

## Summary
- Add PiAgent RPC extension UI test coverage.
- Align PI integration docs with workflow-only scope (PiAgent + pi-plugin).

## Testing
- bash scripts/test-pi-integration.sh
- PI_TEST_RESUME=1 bash scripts/test-pi-integration.sh

## PI Integration Spec for Smithers

Status: Draft
Last updated: 2026-02-12

### 1. Purpose

This document defines PI integration for **smithers-orchestrator v0.4.0**. Smithers is a workflow orchestration library + CLI + server; it does **not** ship a chat UI. Therefore, this spec only covers the integration surfaces that exist in this repo:

1. Smithers CLI-backed workflow agent (`PiAgent`).
2. Smithers server client (`pi-plugin`).

Chat-provider UI integration is explicitly out of scope for this repo.

### 2. Context

Smithers and PI solve adjacent problems:

- Smithers is the deterministic orchestration layer: declarative workflow graph, approvals, retries, persistence, server API.
- PI is the adaptive coding-agent layer: provider routing, extension system, skills, prompt templates, package ecosystem, RPC/JSON event streams.

The integration goal is to combine deterministic workflow control with PI’s extensibility in workflow tasks.

### 3. Current State (v0.4.0)

#### 3.1 smithers-orchestrator (this repo)

- **PI CLI agent is not present** in v0.4.0 (but is the intended addition).
- **PI server client exists** as `pi-plugin` (HTTP client for Smithers server APIs).
- **No chat UI** or provider registry exists in this repo.

### 4. Desired State (target for PI support in v0.4.0)

#### 4.1 CLI backend (in this repo)

- Export `PiAgent` from `src/agents/cli.ts` as a CLI-backed AI SDK `Agent` wrapper.
- Support the PI CLI surface that maps cleanly to `pi --help`:
  - `--mode`, `--provider`, `--model`, `--api-key`
  - session controls (`--print`, `--continue`, `--resume`, `--session`, `--session-dir`, `--no-session`)
  - model scoping (`--models`, `--list-models`)
  - tools, extensions, skills, prompt templates, themes
  - `--thinking`, `--export`, `--verbose`
  - file arguments (`@path`) in text/json modes
- Support **JSON mode** for structured output and **RPC mode** for extension UI bridging.

#### 4.2 Server client (already in this repo)

- `pi-plugin` remains unchanged; it is the TypeScript client for Smithers server APIs.

### 5. Explicit Assumptions

1. `pi` binary must be installed and discoverable in `PATH` on machines running workflows with `PiAgent`.
2. For `PiAgent`, `mode: "text"` is the safest default for stable output extraction in workflow tasks.
3. PI providers and model availability are governed by PI’s own model/provider system; Smithers does not validate model IDs.
4. PI-specific environment vars required by non-default providers remain PI concerns.
5. RPC mode uses JSON commands over stdin/stdout; file arguments are not supported in RPC mode.

### 6. Non-Goals (current phase)

1. Replacing Smithers workflow engine with PI session manager.
2. Re-implementing PI interactive TUI in Smithers.
3. Chat-provider integration or UI settings (Smithers has no UI in this repo).
4. Automatic conversion of PI extension commands into Smithers workflows.

### 7. Architecture

#### 7.1 CLI agent path (in this repo)

1. Workflow author sets `<Task ... agent={new PiAgent(...)}`.
2. `PiAgent` builds the PI CLI command with configured flags.
3. Smithers executes the PI subprocess and captures output into an AI SDK `GenerateTextResult`.
4. Workflow continues with deterministic Smithers orchestration semantics.

#### 7.2 RPC mode path (optional, in this repo)

1. `PiAgent` runs `pi --mode rpc ...`.
2. Smithers sends a `{"type":"prompt"}` command over stdin.
3. PI emits JSON events; Smithers extracts `text_delta` updates and the final assistant message.
4. Extension UI requests (`extension_ui_request`) can be handled via a callback and replied to with `extension_ui_response`.

### 8. Verification Strategy

#### 8.1 In this repo (smithers-orchestrator)

- CLI-agent tests validating `PiAgent` command arg construction and output extraction.
- RPC-mode tests for prompt transport and extension UI request handling.
- Manual integration validation via `scripts/test-pi-integration.sh`.

### 9. Risks and Mitigations

1. Binary/path mismatch across environments.
   - Mitigation: clear errors on missing binary, explicit docs.
2. Model/provider mismatch errors.
   - Mitigation: document PI provider expectations; surface PI errors verbatim.
3. Parsing drift if PI JSON event schema changes.
   - Mitigation: fixture-based tests and version pinning where possible.

### 10. Roadmap

Phase 1 (in this repo):
- [x] `PiAgent` CLI backend (full CLI flag surface).
- [x] Docs in `docs/integrations/cli-agents.mdx` and PI-specific guides.
- [x] CLI/RPC tests (including extension UI request handling).

### 11. Documentation Inventory Added

1. `docs/integrations/pi-integration.mdx`
2. `docs/integrations/pi-support-matrix.mdx`
3. `docs/integrations/pi-human-verification-checklist.mdx`

### 12. Ownership and Change Control

Any PI behavior changes must update:

1. support matrix
2. human verification checklist

This prevents silent drift between implementation and team expectations.

[SamuelLHuber]

realizing that starting pre v0.4.0 wasn't such a great idea :D brb

[Copilot]

Pull request overview

This PR adds comprehensive PI (https://pi.dev/) integration to Smithers as a workflow CLI backend. The implementation follows the existing CLI agent patterns established by ClaudeCodeAgent, CodexAgent, and GeminiAgent, while adding PI-specific features like RPC mode with extension UI callbacks.

Changes:

• Adds PiAgent class that wraps the PI CLI with support for text, json, and RPC modes
• Implements RPC mode with bidirectional JSON event streaming and extension UI request handling
• Adds comprehensive unit tests with fake PI process mocks
• Adds integration test script for manual verification with real PI installation
• Updates documentation with PI-specific guides and support matrix

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
src/agents/cli.ts	Adds PiAgent class, PiExtensionUiRequest/Response types, and runRpcCommand function for RPC mode support
tests/pi-support.test.ts	Comprehensive unit tests covering CLI argument building, RPC mode, extension UI callbacks, and error handling
scripts/test-pi-integration.sh	Manual integration test script that validates PI agent with real PI CLI and moonshot/kimi provider
docs/integrations/cli-agents.mdx	Updates CLI agents documentation to include PiAgent with full option reference
docs/integrations/pi-integration.mdx	New guide explaining PI + Smithers integration patterns and use cases
docs/integrations/pi-support-matrix.mdx	Documents supported PI features and known limitations
docs/integrations/pi-human-verification-checklist.mdx	Manual testing checklist for PI integration validation
docs/docs.json	Adds new PI documentation pages to the docs navigation

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.