Merge commit '67b361f0e99135c578d5764c915b413f457dd67a' as 'third_party/pi'

2026-09-14 10:40:08 -04:00
parent 5ebc7018c3 67b361f0e9
commit 564724ce41
1669 changed files with 397627 additions and 0 deletions
--- a/third_party/pi/packages/coding-agent/docs/development.md
+++ b/third_party/pi/packages/coding-agent/docs/development.md
@@ -0,0 +1,90 @@
+# Development
+
+See [AGENTS.md](https://github.com/earendil-works/pi-mono/blob/main/AGENTS.md) for additional guidelines.
+
+## Setup
+
+```bash
+git clone https://github.com/earendil-works/pi-mono
+cd pi-mono
+npm install
+npm run build
+```
+
+Run from source:
+
+```bash
+/path/to/pi-mono/pi-test.sh
+```
+
+The script can be run from any directory. Pi keeps the caller's current working directory.
+
+### Experimental remote harness
+
+The remote harness server/client integration is development-only. Run it from the repository with:
+
+```bash
+PI_EXPERIMENTAL=1 ./pi-test.sh server
+PI_EXPERIMENTAL=1 ./pi-test.sh client
+```
+
+`PI_SERVER_DIR` overrides the server profile and socket directory (default: `~/.pi/server`). `PI_SERVER_ID` selects the logical server ID when `--server-id` is omitted.
+
+The `client` and `experimental/plugin` package subpaths resolve only under the `source` condition in a checkout. Their implementations and the server/client commands are excluded from npm packages and standalone binaries. `pi-client`, `pi-protocol`, and `pi-server` are development dependencies of coding-agent, not runtime dependencies. The local SDK and stdio RPC API are unchanged.
+
+## Forking / Rebranding
+
+Configure via `package.json`:
+
+```json
+{
+  "piConfig": {
+    "name": "pi",
+    "configDir": ".pi"
+  }
+}
+```
+
+Change `name`, `configDir`, and `bin` field for your fork. Affects CLI banner, config paths, and environment variable names.
+
+## Path Resolution
+
+Three execution modes: npm install, standalone binary, tsx from source.
+
+**Always use `src/config.ts`** for package assets:
+
+```typescript
+import { getPackageDir, getThemeDir } from "./config.js";
+```
+
+Never use `__dirname` directly for package assets.
+
+## Debug Command
+
+`/debug` (hidden) writes to `~/.pi/agent/pi-debug.log`:
+- Rendered TUI lines with ANSI codes
+- Last messages sent to the LLM
+
+## Testing
+
+```bash
+./test.sh                         # Run non-LLM tests (no API keys needed)
+npm test                          # Run all tests
+npm test -- test/specific.test.ts # Run specific test
+```
+
+### Published package smoke test
+
+After building, run `npm run check:package-install`. It packs the public packages and installs only coding-agent as a direct dependency in a temporary directory outside the repository. Local tarball overrides select declared transitive dependencies without installing development-only packages. The check verifies SDK imports and CLI startup without credentials or model requests.
+
+`npm run check` also checks runtime dependency declarations and rejects excluded development sources pulled into a package's build through imports.
+
+## Project Structure
+
+```
+packages/
+  ai/           # LLM provider abstraction
+  agent/        # Agent loop and message types  
+  tui/          # Terminal UI components
+  coding-agent/ # CLI and interactive mode
+```