# packages/pi/

Publishable npm package for the FamiliarOS Pi coding-agent integration.

## Responsibility

- Exposes `@familiaros/pi` as a Pi package with a Pi extension resource.
- Maps Pi session/tool activity to safe FamiliarOS reactions through `@familiaros/client`.
- Registers a user slash command namespace, `/familiaros`, for status, test, react, and say commands.
- Keeps MVP behavior default-familiar-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 FamiliarOS.

## Flow

```text
Pi extension loader
  -> packages/pi/src/extension.ts
  -> packages/pi/src/runtime.ts
  -> @familiaros/client
  -> FamiliarOS 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 FamiliarOS client via scheduled non-blocking call
5. IPC failures logged (if debug enabled) but never thrown to Pi

**Command flow**:
1. User types `/familiaros <command>` in Pi
2. `registerCommand()` handler invoked with args string
3. `parseFamiliarOSCommand()` validates and structures command
4. `executeCommand()` performs synchronous FamiliarOS client calls
5. UI notifications sent via `ctx.ui.notify()`

## Integration

- **Upstream**: Consumes `@familiaros/agent-events` for speech validation and `@familiaros/client` for IPC.
- **Downstream**: Pi coding agent loads extension via `pi.extensions` manifest entry.
- **Desktop**: Communicates with FamiliarOS desktop app through local socket IPC (via `@familiaros/client`).
- **Commands**: `/familiaros status`, `/familiaros test`, `/familiaros react <reaction>`, `/familiaros 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.
- FamiliarOS IPC failures are swallowed by automatic event handlers so Pi execution continues.