# GrokBoy product notes

**North star:** a local **Grok Bot–like** agent — thin CLI core, tool-using ReAct loop, optional Playwright **DOM** browser (not screenshot-first). GrokBoy is the sole main line; LazyBoy is reference only (no fork).

## Done (P0–P3)

| Phase | What |
|-------|------|
| **P0** | Streaming chat CLI (`grokboy chat`), xAI/OpenAI-compatible API |
| **P1** | Tools + ReAct (`shell`, files), sessions under `~/.grokboy/sessions/` |
| **P2** | Completion contract (`report_done` / `report_blocked`), loop guard, context truncation |
| **P3** | Optional Playwright DOM tools: navigate / snapshot / click / type / eval (fail-closed) |

## P4 — Human handoff (this slice)

Auth walls (login, OTP, captcha) often cannot be automated safely. P4 adds **`browser_handoff`**:

1. Agent calls `browser_handoff` with a `reason` (optional `timeout_secs`).
2. Helper ensures Chromium is **headed** (visible); may relaunch from headless and restore URL.
3. Terminal prints bilingual (繁中 + English) instructions.
4. Loop **blocks** until you press **Enter** (continue) or type **`abort`**, or timeout → fail-closed blocked.
5. On resume, a **DOM snapshot** is returned so the model can continue.

### Env

- `GROKBOY_BROWSER_HEADED=1` — always launch Chromium headed (recommended when handoff is likely).
- `GROKBOY_HANDOFF_AUTO=1` — auto-resume (tests / CI); `abort` to auto-abort.

### Non-goals (this slice)

- Multi-agent orchestration
- Desktop accessibility / native UI automation
- External connectors / SaaS integrations
- Forking LazyBoy or Codex

### Acceptance (summary)

See `docs/ACCEPTANCE.md` section P4. Short list:

- `browser_handoff` registered and wired into the agent loop
- Headed Chromium for handoff; JSONL daemon keeps state within one run when already headed
- Bilingual terminal prompt; Enter / abort / timeout fail-closed
- Post-resume DOM snapshot as tool result
- Offline `cargo test` / `grokboy smoke` without API key or interactive stdin

## Roadmap hint (later)

P5+ may deepen persistence, richer session UX, or more tools — still thin core, DOM-first browser.