# GrokBoy

Minimal local **GrokBot-like** CLI agent. Phase **P6**: scenario playbooks + confirm-before-post. **P7 UX**: natural chat, max-round summary, blocked recovery. **P8**: auto-continue chunks like Grok Bot (progress beats, total ceiling).

## Status

| Phase | Status |
|-------|--------|
| P0 streaming chat | done |
| P1 shell / files + ReAct | done |
| P2 completion / loop guard / truncation | done |
| P3 browser (Playwright DOM) | done (optional) |
| P4 human handoff | done |
| P5 interactive agent REPL | done |
| P6 scenario playbooks + confirm | done |
| P7 agent UX polish | done (slice) |
| P8 auto-continue chunks | done |

No Docker desktop, no Codex/LazyBoy fork. Product notes: [`docs/PRODUCT.md`](docs/PRODUCT.md).

## Setup (macOS)

```bash
export GROKBOY_API_KEY=your_key   # or XAI_API_KEY
# optional:
# export GROKBOY_BASE_URL=https://api.x.ai/v1
# export GROKBOY_MODEL=grok-4.6
# export GROKBOY_CONTEXT_CHARS=100000
# export GROKBOY_MAX_ROUNDS=12          # rounds per chunk
# export GROKBOY_MAX_ROUNDS_TOTAL=48    # absolute ceiling across auto-continues
# export GROKBOY_PROGRESS=0             # silence 〔續跑〕 progress beats
# export GROKBOY_BROWSER_HEADED=1       # visible Chromium (recommended for handoff / agent)

cd ~/GrokBoy
cargo run -p grokboy -- chat
```

### Optional: Playwright browser tools

Browser tools are always registered but **fail closed** until you install the helper:

```bash
cd ~/GrokBoy/tools/playwright
npm install
npx playwright install chromium
```

Then the agent can use `browser_navigate`, `browser_snapshot`, `browser_click`, `browser_type`, `browser_eval`, and **`browser_handoff`** (DOM/selector/role — not screenshot-first).

### Human handoff (P4)

When the agent hits a login / OTP / captcha wall it calls `browser_handoff`:

1. Chromium opens **headed** (visible) — or relaunches headed if it was headless.
2. Terminal prints why it paused (ZH-TW + English) and what to do.
3. You complete the wall in the browser, then press **Enter** in that terminal (or type `abort`).
4. Agent resumes with a fresh **DOM snapshot**.

```bash
# Prefer headed for runs that may need handoff:
export GROKBOY_BROWSER_HEADED=1
cargo run -p grokboy -- run "打開需要登入的頁面並完成任務"
# or interactive:
cargo run -p grokboy -- agent
```

Tests / CI: `GROKBOY_HANDOFF_AUTO=1` auto-resumes (no interactive Enter).


### Scenario playbooks (P6)

Reusable acceptance pattern: **Phase A** research+draft (no publish) → auth `browser_handoff` + **`request_user_confirm`** → **Phase B** publish only after approve.

- Pattern: [`docs/scenarios/README.md`](docs/scenarios/README.md)
- Template: [`docs/SCENARIO-TEMPLATE.md`](docs/SCENARIO-TEMPLATE.md) · prompts in `prompts/templates/`
- Example only: Shopee Affiliate → Threads — [`docs/scenarios/examples/shopee-threads-affiliate.md`](docs/scenarios/examples/shopee-threads-affiliate.md)

```bash
export GROKBOY_BROWSER_HEADED=1
cargo run -p grokboy -- agent
# paste prompts/examples/shopee-threads-phase-a.txt  (or your filled template)
# review draft → paste phase-b or say「核准，請發佈…」
```

Tests: `GROKBOY_CONFIRM_AUTO=1` auto-approves; `abort` denies.

## Commands

- `grokboy chat` — interactive streaming chat (no tools)
- `grokboy run "<prompt>"` — one-shot agent with tools
- `grokboy run --session <id> "<prompt>"` — continue a saved session (one shot)
- `grokboy agent` — **interactive multi-turn** agent REPL with tools (auto session)
- `grokboy agent --session <id>` — resume an agent session
- `grokboy smoke` — offline checks (no API key / no interactive handoff)
- `grokboy help`

In `agent` REPL: `/exit` or `/quit` leave; `/session` show id; empty line ignored.

Tools: `shell`, `list_dir`, `read_file`, `write_file`, `report_done`, `report_blocked`,
`browser_navigate`, `browser_snapshot`, `browser_click`, `browser_type`, `browser_eval`,
`browser_handoff`, `request_user_confirm`.

Sessions are stored under `~/.grokboy/sessions/<id>.json` (may include `last_browser_url`).

The agent stops on `report_done` / `report_blocked`, blocks identical tool rounds (×3), and truncates old context when over budget.
Long tasks **auto-continue** across chunks (`GROKBOY_MAX_ROUNDS` per beat, up to `GROKBOY_MAX_ROUNDS_TOTAL`) with `〔續跑〕` progress on stderr — like Grok Bot — instead of hard-stopping for a user re-prompt after every chunk.

## Traditional Chinese

本機終端機 coding assistant。P6 支援可推廣的情境劇本（Phase A 草稿 → confirm → Phase B 發佈）與 `request_user_confirm`。P5 `grokboy agent`；P4 `browser_handoff`（登入牆）。範例：蝦皮→Threads，見 `docs/scenarios/`。

```bash
export GROKBOY_API_KEY=你的金鑰
export GROKBOY_BROWSER_HEADED=1
cd ~/GrokBoy
cargo run -p grokboy -- smoke
# 可選瀏覽器：
cd tools/playwright && npm install && npx playwright install chromium
cargo run -p grokboy -- agent
cargo run -p grokboy -- run "打開 example.com 並 snapshot"
cargo run -p grokboy -- chat
```

## Layout

```
crates/grokboy-core/   # config, model, tools, browser, agent, session
crates/grokboy/        # CLI binary
tools/playwright/      # optional Node Playwright helper (JSONL)
docs/PRODUCT.md
docs/ACCEPTANCE.md
docs/scenarios/          # playbook pattern + examples
prompts/templates/       # Phase A/B placeholders
prompts/examples/        # filled example prompts
```