@paigy/harness 0.1.0

package/README.md

@@ -0,0 +1,214 @@
+# paigy-harness
+
+Runs Claude Code and Codex on your machine, mirrors every turn to your Paigy inbox, and
+— when you ask it to — **rings your phone when an agent is blocked** (#804).
+
+## Why this exists
+
+Hooks already cover turn capture — `.claude/settings.json`, `.codex/hooks.json`, and
+`paigy-listen` + `PAIGY_ON_WAKE` (#486) between them can observe and wake any harness
+without a desktop app. Two things need a process that actually owns the agent:
+
+- **Permission prompts reach you.** When Claude Code wants to run something destructive
+  or edit outside the workspace, today it blocks on a terminal nobody is watching. Here
+  it becomes an approve/deny on your phone, and the agent unblocks with your answer.
+- **Capture is structural, not advisory.** `contact` fires because a model chose to call
+  it. A turn boundary in a harness is a fact of the runtime.
+- **The conversation goes both ways.** Your words reach a *running* agent's stdin — so
+  you can steer it from a walk, not just approve what it already decided to do.
+
+## The round trip
+
+The point isn't notifications, it's a conversation with an agent that happens to be
+running on your laptop. Both directions close (`paigy/conversation.ts`):
+
+- **Answering.** The agent's turn ends on a question → it banners → your reply goes
+  straight back into stdin as the next turn. Without this the loop is one-directional
+  and dies at the first idle.
+- **Initiating.** You say something unprompted from your phone → it arrives as a
+  `request` on the thread → same stdin. You never have to wait to be asked.
+
+Both ride the same thread, so the phone shows one conversation. `endsWithQuestion` is
+what decides "the agent is waiting on you" versus "here's your history", and it is
+deliberately conservative: a false positive buzzes someone who was never asked anything.
+
+Answers are read out of whatever shape they arrive in (`spokenText`) — a tapped option,
+a spoken sentence, a whole call log — because the words are what the agent needs, not
+the envelope. A silence is never turned into a prompt; the agent must not end up talking
+to itself on your behalf.
+
+It is **not** a chat client. The terminal stays where you work; this window is config
+plus a log of what's being mirrored. A second place to read agent output would defeat
+the point — the second place is your phone.
+
+## Approvals: bypass by default, ask when told
+
+Buzz taught us the default (block/buzz auto-approves every `session/request_permission`
+with `allow_once`): an agent that stalls on every tool call is an agent nobody runs.
+So **`bypass` is the default mode** — the driver pins the adapter's permission mode to
+`bypassPermissions` and answers whatever still asks — but unlike Buzz, every
+auto-approval still lands on the rail as history. Bypass means "don't stall the
+agent", never "don't tell the user".
+
+`ask` mode is the original #804 behavior, one toggle away: blocked actions banner (or
+ring, when destructive) and your answer unblocks the process. Ask pins the adapter to
+`default` (manual prompts) explicitly — claude-agent-acp otherwise opens in `auto`, a
+classifier that answers permission prompts in the user's place, which is precisely the
+job this mode reserves for the user.
+
+## One rail, level per notification
+
+Mirrored turns and blocking asks ride the **same** notifications rail. What separates
+silent history from "answer me now" is `urgency`, not a second store:
+
+| Event | Level | Why |
+| --- | --- | --- |
+| a turn (agent or user) | `inbox` | lands, never buzzes; searchable, handoff-able history |
+| a blocked action | `banner` | claims attention; escalates on its own if unanswered |
+| a blocked **destructive** action | `call` | `rm -rf` doesn't get to wait for the escalation ladder |
+| a turn that **asked you something** | `banner` | a question filed silently is a conversation that dies |
+| a turn that failed | `push` | worth knowing soon, not worth a sound |
+| our own parse failure | — | not on the rail at all; it's our problem, not yours |
+
+`paigy/level.ts` decides; `apps/api/src/notify/levels.ts` still arbitrates against your
+session mode and account permissions and can only lower it.
+
+## The catalog and the doctor
+
+The other thing Buzz got right: connecting a harness should be a status line and a
+button, not a wiki page. `harness/catalog.ts` is a compiled-in table per runtime — the
+binaries to probe (PATH **plus** the dirs a GUI app can't see; Finder-launched apps
+don't get your shell PATH), an auth probe (`codex login status`), a login hint, and an
+install one-liner. The window renders it as a doctor: ✓ ready, ◐ needs login (with the
+command to run), ✗ missing (with an Install button — the command comes from the
+catalog, never the renderer). Starting a half-configured harness doesn't fail
+silently: the hint lands on your Paigy rail as a `push` (`nudgeSetup`).
+
+## One transport: ACP
+
+Both harnesses speak **ACP** — the Agent Client Protocol, JSON-RPC over stdio — through
+their adapters: `@agentclientprotocol/claude-agent-acp` and `…/codex-acp`. One driver
+(acp.ts), no parser museum; ACP gave Codex the permission channel `codex exec` never
+had, and it's the door to every other harness that speaks it (Goose, Cursor, Devin…)
+as a catalog entry. The stream-json Claude adapter this replaced lives in git history.
+
+## Layout
+
+```
+src/harness/   events.ts   the neutral HarnessEvent the driver produces
+               acp.ts      the ACP driver — both harnesses, any ACP agent tomorrow
+               catalog.ts  which harnesses exist, detection, auth probes, installs
+               session.ts  spawn, line-split, lifecycle — the only impure file here
+src/paigy/     level.ts        event → NotifyLevel
+               bridge.ts       mirror turns, ask permissions/questions, setup nudges
+               conversation.ts the round trip — your words into a running agent's stdin
+src/run.ts     the whole bridge, Electron-free — what main.ts and cli.ts both drive
+src/main.ts    Electron main; renderer/ is a doctor, a form and a log
+src/cli.ts     `paigy-harness` — the same bridge from a terminal or a service unit
+```
+
+Parsing lives in the drivers so the whole protocol surface is testable without
+spawning anything.
+
+## Pair this Mac (the beacon)
+
+Unpaired (or still borrowing a legacy `~/.paigy` slot), the window shows a QR — the
+device flow's verification URL. Scan it with the phone camera, approve on the phone,
+and the token lands in the app's own `Desktop` slot: the machine becomes its own
+identity ("Mauricio's Mac"), sessions and hatched agents mint underneath it, and the
+default slot goes back to belonging to whatever terminal agent paired it. Legacy
+setups keep working until scanned — the beacon is an upgrade, never a wall.
+
+## Allowed workspaces
+
+An allow-list of folders at `~/.paigy/workspaces.json` — device config, shared by the
+window and the headless host, so the phone's offer never depends on which entry point
+is running. A session may only start inside a granted folder (the desktop equivalent
+of a permission scope), curated through the window's native picker or
+`paigy-harness host --grant DIR`. This list is exactly what the phone offers when you
+launch or assign a session. The CLI's positional-run path deliberately does NOT
+enforce it: a path typed into your own shell is its own grant.
+
+## Launch from the phone
+
+While a host is running (window open, or `paigy-harness host`), its heartbeat
+advertises ready harnesses + granted workspaces. On the phone: **Agents → "+ New
+session"** picks from those options and gives the session the pairing flow's identity
+gestures — a name and a voice — because a session IS a minted pairing: its turns and
+everything you say back ride its own conversation. The **notes assign picker** offers
+the same as "New <harness> session · <workspace>" rows, naming the session after the
+note and delivering the brief as its opening request.
+
+## Hatch — pair one device, mint many agents
+
+`paigy-harness hatch "Name"` mints a pre-paired sibling identity under your account —
+your existing pairing is the ceremony; no code, no phone round-trip. It lands in its
+own `~/.paigy` slot:
+
+```sh
+paigy-harness hatch "Voice bug hunter"
+PAIGY_AGENT="Voice bug hunter" claude                 # any tool speaks as it
+paigy-harness --identity "Voice bug hunter" --harness codex "fix the flaky test"
+```
+
+Hatched agents appear on the phone's Agents screen like any pairing — renameable,
+re-voiceable, revocable.
+
+## Install anywhere (the curl path)
+
+```sh
+curl -fsSL https://paigy.ai/install.sh | sh
+```
+
+Installs the npm CLI (one self-contained file — the workspace libs are bundled),
+runs `paigy-harness pair` (device flow with a terminal QR, landing in the Desktop
+slot), and prints the host/service next steps. `paigy-harness service` installs a
+macOS launchd agent so hosting survives reboots — the host loop IS the service,
+launchd just keeps it alive (the old "no daemon" note was about the WAKE channel,
+which still belongs to paigy-listen).
+
+## Run it
+
+```sh
+pnpm --filter @paigy/harness dev          # the window (status + host; sessions start from the phone)
+pnpm --filter @paigy/harness build
+node apps/desktop/dist/cli.js --doctor    # or headless: paigy-harness
+node apps/desktop/dist/cli.js --harness codex --cwd ~/repo "fix the flaky test"
+node apps/desktop/dist/cli.js host --grant ~/projects   # standby, launchable from the phone
+```
+
+The window deliberately has NO run form — launching moved to the phone (companion.md).
+It shows pairing, the doctor, the workspace allow-list, a Stop button, and the log.
+
+Headless flags: `--harness claude|codex`, `--mode bypass|ask`, `--cwd DIR`,
+`--identity NAME`, `--grace SECONDS`, `--doctor`; subcommands `host [--grant DIR]…`
+and `hatch NAME`. In ask mode the CLI is TERMINAL-FIRST: a blocked action or open
+question prints in the terminal and waits `--grace` (default 90s); a person at the
+keyboard answers in place, an unattended terminal escalates to your phone (0 = phone
+immediately; non-TTY runs always go straight to the phone).
+The CLI is the proof the harness doesn't need the app: `run.ts`/`host.ts` never
+import Electron — a machine with only the CLI is exactly as launchable as one with
+the window.
+
+Pairing is one-time and lives in `~/.paigy` — the app reads it, never mints it. If
+you've never paired: `npx -y -p @paigy/mcp paigy-mcp-onboard`.
+
+## Known gaps (#804)
+
+- **Protocol churn is the standing risk.** Neither `stream-json` nor ACP adapter
+  behavior is a stability contract. Every driver fails soft by design: an unrecognized
+  frame is skipped, never fatal. If mirroring goes quiet after a CLI update, re-verify
+  the frame names in the driver doc comments first.
+- **Auth probes are vendor commands** (`claude auth status`, `codex login status`) and
+  can drift with CLI releases; a probe failure reads as "needs login", so drift shows
+  up as a nagging hint, not a broken start.
+- **No session resume, no packaging.** Signing, notarization and auto-update are
+  unstarted (they block on Apple credentials, not code).
+- **Concurrent sessions** (2026-08-03): every claimed spec runs under its OWN minted
+  token — per-run identity is threaded through every network touch (`run.ts` binds
+  submit/check/ack once per session), so parallel sessions never share a
+  conversation. "Stop sessions" stops them all; per-session stop is UI away.
+- **Deliberately no auto-start daemon.** A promptless harness has no thread to pump,
+  and `paigy-listen` + `PAIGY_ON_WAKE` (#486) already own the standing wake channel —
+  a launchd `paigy-harness` would be a second daemon racing the first. The composition
+  is: the listener wakes on Paigy work, and what it runs can be `paigy-harness`.