# Clawdis Agent RPC (proposal)

## Motivation
- Voice wake forwarding and mac CLI currently shell out to `pnpm clawdis agent --json`, spawning a Node process per send.
- pi-mono’s coding-agent keeps a hot process in RPC mode: read JSON on stdin, emit JSON on stdout.
- We want the same pattern so cross-host voice → WhatsApp uses a long-lived Node worker, better latency, and structured errors.

## Goal
Run the Node CLI in `--mode rpc` on the host that has the active WhatsApp session. Communicate over stdin/stdout with newline-delimited JSON messages.

## Proposed protocol
### Commands (stdin)
- `{"type":"send", "text":"hi", "session":"main", "thinking":"low"}`
- `{"type":"abort"}` – cancel current generation (if supported)
- `{"type":"status"}` – health ping
- (Optional) `{"type":"compact"}` – trigger session compaction

### Events (stdout)
- `{"type":"message_start", "role":"assistant"}`
- `{"type":"message_end", "text":"..."}`
- `{"type":"error", "error":"message"}`
- `{"type":"status", "ok":true, "details":"..."}`
- Preserve existing `--json` payload shape where possible so consumers can reuse parsers.

## Runtime design (Node CLI)
- Add `--mode rpc` to the Node CLI (similar to pi-mono’s coding-agent).
- Initialize agent/session once, keep it alive.
- Use readline on stdin; for each JSON line, dispatch:
  - `send` → call agent, stream message events to stdout as they occur.
  - `abort` → cancel current request.
  - `status` → emit `{type:"status", ok:true}`.
- Never exit unless stdin closes; log fatal errors to stderr and emit `{type:"error"}` before exit.

## Mac-side integration
- Create an `RpcAgentProcess` helper:
  - Spawn `pnpm clawdis --mode rpc` in repo root (`/Users/steipete/Projects/clawdis`).
  - Keep stdin/stdout pipes; restart on exit.
  - Method `send(text, session, thinking)` → write JSON line, wait for `message_end` or `error`, return result.
- XPC handler `agent`:
  - Prefer RpcAgentProcess; if unavailable, fall back to one-shot `pnpm clawdis agent --json` (existing behavior).
  - Return errors to callers (voice wake, CLI) so failures are visible in logs/UI.

## Voice wake path
- Voice wake forward still SSHes to the WhatsApp host; the host’s XPC `agent` uses RpcAgentProcess to deliver the message without extra process spawn.
- If RPC is down, it falls back to one-shot and logs the failure.

## Error handling & observability
- All non-OK responses emit an `error` event with the message/exit code.
- Mac logs on `VoiceWakeForwarder` already surface SSH/CLI failures; extend to tag RPC restarts.
- Consider a `clawdis-mac status --rpc` flag to report whether the RPC worker is live.

## Next steps
1) Implement `--mode rpc` in Node CLI (mirror pi-mono’s coding-agent main.ts rpc path).
2) Add `RpcAgentProcess` in the mac app; switch XPC `agent` to use it.
3) Wire `clawdis-mac agent` to prefer RPC, fall back to one-shot.
4) Optional: add a tiny RPC health metric to status JSON.