# pi: backend notes
Working notes while implementing `pi:` per `design.md`. External `pi` only (no bundling).
## Ideas
- Keep Pi on its own wire (`BridgeWire::PiRpc`) instead of extending `BridgeRequest`, so Cursor/Prime Node bridges stay unchanged.
- Prefer `--no-session --no-extensions` for malvin runs to avoid writing into the user’s Pi session store and to reduce `extension_ui_request` risk.
- Reuse Prime-style usage normalization (`input`/`output`/`cacheRead`/`cacheWrite` → ACP keys); live Pi events use the same field names.
- Cost config can use existing two-level tables: `[agent.pi."<provider>/<model>"]` → key `pi:<provider>/<model>`.
## Suggestions
- Document `MALVIN_PI` next to install docs; PATH discovery is enough for most hosts.
- Soft-fail `malvin models` when `pi` is missing (same pattern as Cursor/Prime).
- Fail fast on `--no-force` for `pi:` (same class of error as Cursor/Prime).
- Minimum `pi` version pinned in code: `PI_MIN_VERSION = 0.1.23` (parsed from `pi --version`).
## Questions
1. Claim (runtime evidence, `pi 0.1.23`): docs list top-level `text_delta` / `tool_execution_*`, but live RPC emits nested `message_update.assistantMessageEvent` (`text_delta`, `toolcall_start`, …) plus `agent_end`. Adapter maps both shapes.
2. Claim (runtime evidence): built-in tools (`ls`) auto-run under `pi --rpc --no-extensions` without `extension_ui_request`. Force path is viable for v1.
3. Open: should session files live under the malvin run dir via `--session-dir` instead of `--no-session` for resume/debug? v1 uses `--no-session`.
4. Open: license rider for advertising `pi:` widely — human legal review before making it a default.
5. Provider/model split: first `/` after `pi:` (confirmed against `--provider` / `--model` and nested OpenRouter ids).
## Implementation log
- Added `ModelBackend::Pi` / `BridgeKind::Pi` / `pi:` parse (`pi:<provider>/<model>`, first-slash split).
- Added `src/pi_sdk/` (discover, auth, protocol, event map, spawn, session IO, models list).
- Wired factory, auth, spawn, prompt labels, `malvin models`, docs, README. (VISION.md names `pi:` for log/stdout parity with `cursor:`; behavioral parity is via BridgeEvent → log_adapter.)
- No Cargo dependency on pi crates; discovery via `MALVIN_PI` or `PATH`.
- Quality gates: ruff, kiss, clippy `-D warnings`, pytest, `admin/malvin_rust_test_gate.sh` all green.
- Mock RPC child: `src/pi_sdk/mock_pi.sh` for offline unit tests.
- Tool mapping: only `tool_execution_*` → ToolCall (ignore `message_update.toolcall_*` to avoid duplicates).
- `MALVIN_PI` must be an executable file (execute bit on Unix).