55 lines
2.7 KiB
Markdown
55 lines
2.7 KiB
Markdown
# packages/pi/
|
|
|
|
Publishable npm package for the OpenPets Pi coding-agent integration.
|
|
|
|
## Responsibility
|
|
|
|
- Exposes `@open-pets/pi` as a Pi package with a Pi extension resource.
|
|
- Maps Pi session/tool activity to safe OpenPets reactions through `@open-pets/client`.
|
|
- Registers a user slash command namespace, `/openpets`, for status, test, react, and say commands.
|
|
- Keeps MVP behavior default-pet-only and non-blocking; no Pi model-callable tools are registered.
|
|
|
|
## Design/Patterns
|
|
|
|
- **Package structure**: Standard npm package with `main`/`types` pointing to `dist/index.js`, Pi extension declared in `pi.extensions` array.
|
|
- **Dual exports**: Main package exports (`index.ts`) and dedicated extension entry (`extension.ts`) for Pi loader consumption.
|
|
- **Peer dependency**: Declares optional peer dependency on `@earendil-works/pi-coding-agent` for type safety without hard coupling.
|
|
- **Fire-and-forget scheduling**: All automatic event handlers use non-blocking scheduling with swallowed IPC failures to prevent Pi execution disruption.
|
|
- **Privacy-first**: Prompt text, assistant text, tool output, command output, file paths, URLs, and secrets are never forwarded to OpenPets.
|
|
|
|
## Flow
|
|
|
|
```text
|
|
Pi extension loader
|
|
-> packages/pi/src/extension.ts
|
|
-> packages/pi/src/runtime.ts
|
|
-> @open-pets/client
|
|
-> OpenPets desktop local IPC
|
|
```
|
|
|
|
**Automatic event flow**:
|
|
1. Pi emits lifecycle events (`session_start`, `agent_start`, `turn_start`, etc.)
|
|
2. `extension.ts` receives event via `api.on()` and wraps in `PiEventEnvelope`
|
|
3. `runtime.ts` classifies event to determine appropriate reaction
|
|
4. Reaction dispatched to OpenPets client via scheduled non-blocking call
|
|
5. IPC failures logged (if debug enabled) but never thrown to Pi
|
|
|
|
**Command flow**:
|
|
1. User types `/openpets <command>` in Pi
|
|
2. `registerCommand()` handler invoked with args string
|
|
3. `parseOpenPetsCommand()` validates and structures command
|
|
4. `executeCommand()` performs synchronous OpenPets client calls
|
|
5. UI notifications sent via `ctx.ui.notify()`
|
|
|
|
## Integration
|
|
|
|
- **Upstream**: Consumes `@open-pets/agent-events` for speech validation and `@open-pets/client` for IPC.
|
|
- **Downstream**: Pi coding agent loads extension via `pi.extensions` manifest entry.
|
|
- **Desktop**: Communicates with OpenPets desktop app through local socket IPC (via `@open-pets/client`).
|
|
- **Commands**: `/openpets status`, `/openpets test`, `/openpets react <reaction>`, `/openpets say <message>`.
|
|
|
|
## Safety notes
|
|
|
|
- Automatic events use reactions and fixed message pools only.
|
|
- Prompt text, assistant text, tool output, command output, file paths, URLs, and secrets are not forwarded.
|
|
- OpenPets IPC failures are swallowed by automatic event handlers so Pi execution continues.
|