# CLAUDE.md — working on grok-glance

grok-glance is the web control plane for grok's `/rc` remote control. Read
[ARCHITECTURE.md](ARCHITECTURE.md) first — it explains *why* the pieces are shaped the way
they are. This file is the operational half: how to build it, how to test it, and the
handful of things that will waste an afternoon if you learn them the hard way.

The Rust half lives in the sibling `newgrok/` tree as patches `0003`/`0004`. **The two are
one feature.** A change to the wire format is a change to both.

---

## Layout

```
cmd/glance/main.go     serve | apikey add·list·rm | bootstrap | version
cmd/fakeagent/main.go  a fake grok, for UI work without rebuilding Rust
internal/
  acp/       JSON-RPC framing + the ACP subset glance needs   ~280 lines
  hub/       agents, browsers, ring buffer, interaction table  the live system
  auth/      TOTP, bootstrap gate, signed cookies
  state/     ~/.grok/glance/state.json (0600)
  httpapi/   chi router, both WS upgrades, embedded SPA
web/src/
  App.tsx           status gate: Setup / Login / Console
  pages/            Setup, Login, Sessions, Session
  components/       Transcript, ToolCall, PermissionDialog, PromptBox, TurnStatus
  lib/              api.ts (REST), ws.ts (GlanceSocket), acp.ts (frames → transcript)
```

If you are looking for where a decision lives:

| Question | File |
|---|---|
| What does the browser send/receive? | `internal/hub/browser.go` |
| What happens when two people click Allow? | `internal/hub/agent.go` → `Answer`, `retract` |
| Which methods does glance refuse? | `internal/hub/agent.go` → `handleFrame` |
| Is this frame part of the transcript? | `internal/acp/jsonrpc.go` → `IsTranscript` |
| Why is `/setup` a 404? | `internal/auth/auth.go` → `BootstrapToken` |
| How does a frame become a bubble? | `web/src/lib/acp.ts` → `applyFrame` |

---

## Build and run

```sh
make build        # frontend, then binary → bin/glance
make server       # binary only, keeping the last frontend build (fast server loop)
make web          # frontend only
make check        # go vet + go test + tsc --noEmit
make dev          # Go server + Vite with hot reload → http://localhost:5173
```

`//go:embed all:dist` resolves at compile time, so **`go build` ships whatever `make web`
last produced**. If a UI change does not appear in `bin/glance`, that is why.

Use `make dev` for frontend work: Vite proxies `/api` to the Go server, which is what keeps
the `__Host-glance` cookie working — it is `SameSite=Strict` and would never survive a
cross-origin request. Hitting the Go port directly on 7717 with the Vite UI will look like
a mysterious auth failure.

### First run

```sh
make build
bin/glance serve --addr 127.0.0.1:7717 --insecure-cookie
#   → prints a bootstrap URL; open it, scan the QR, enter one code
bin/glance apikey add dev
#   → prints glance_sk_… once, plus a [remote_control] block for ~/.grok/config.toml
```

`--insecure-cookie` drops the `Secure` attribute so a plain-HTTP localhost session works.
It is refused on a non-loopback address, deliberately. In production put glance behind a
TLS-terminating proxy and leave the flag off.

Lost the authenticator? Delete `~/.grok/glance/state.json` and start over. That is the
whole recovery story, on purpose — see ARCHITECTURE.md. **`~/.grok/glance/` also contains
`secret.key` and `hook.secret` that belong to something else entirely. Do not touch them.**

---

## Testing without rebuilding grok

`cmd/fakeagent` dials the agent socket exactly as the real bridge does and plays a scripted
turn: streamed text, a thought, a plan, a tool call, and a **real**
`session/request_permission` that waits for a real answer.

```sh
bin/glance serve --insecure-cookie &
make fakeagent KEY=glance_sk_…            # or: go run ./cmd/fakeagent --key …
```

Then in the browser: prompt it, watch it stream, answer the permission. Useful flags:

- `--terminal-after 3s` — the "terminal" answers the permission first, so you can watch the
  browser's card retract by itself. This is the path a browser alone cannot exercise.
- `--speed 1s` — slow the stream down to catch layout problems mid-turn.
- Send the prompt and hit **Stop**: the fake agent honours `session/cancel` and finishes the
  turn with `stopReason: cancelled`.

Run several at once with different `--title` to test the session list.

It emits `turn_completed` on the **xAI rail** (`x.ai/session_notification`) on purpose: if
the turn stops showing as finished in the UI, rail mirroring has regressed. That is the
most likely thing to break silently after an upstream sync.

What fakeagent does *not* prove is that the real bridge speaks this dialect. Only the
end-to-end checklist does.

---

## Where the ACP types come from

There is no Go SDK for ACP. `internal/acp` is hand-written against
[`agentclientprotocol/agent-client-protocol`](https://github.com/agentclientprotocol/agent-client-protocol)
(`schema/v1/schema.json`), and it is thin on purpose — glance correlates ids, recognises a
dozen methods, and passes payloads through to the browser as `json.RawMessage`.

**Do not "finish" it by modelling every update variant.** The stable `session/update` rail
is a small closed set; the xAI rail has ~60 grok-internal variants that drift with every
upstream sync. Typed structs for those would be a large amount of code whose only effect is
to turn an upstream rename into a parse error that kills a live connection. The contract is:

- **The stable rail carries correctness.** Turn state comes from `update.sessionUpdate`,
  read by `classifyUpdate` in `internal/hub/agent.go` — one field, both rails.
- **The xAI rail is presentation.** Unrecognised variants are stored, forwarded, and
  skipped by the renderer. Never an error.
- **`_meta` is forwarded byte-for-byte.** `eventId`, `promptId`, `chunkId` and `isReplay`
  are how a viewer dedups and orders; rewriting the envelope would break replay.

To regenerate anything, clone the spec repo and read `schema/v1/schema.json`. There is no
codegen step and adding one would be a mistake at this size.

### Response shapes are pinned to grok's Rust types, not to the spec

The three interaction replies are built in `web/src/components/PermissionDialog.tsx`, and
their exact shapes were read off grok's source, not guessed:

| Interaction | Reply |
|---|---|
| `session/request_permission` | `{"outcome":{"outcome":"selected","optionId":"…"}}`, or `{"outcome":{"outcome":"cancelled"}}` |
| `x.ai/exit_plan_mode` | `{"outcome":"approved"}`, `{"outcome":"cancelled","feedback":"…"}`, `{"outcome":"abandoned"}` |
| `x.ai/ask_user_question` | `{"outcome":"accepted","answers":{"<question text>":["<label>"]}}`, plus optional `annotations` |

`ask_user_question` is the fiddly one, and `buildAccepted` reproduces
`xai-grok-pager/src/views/question_view.rs` rule for rule: values are **arrays** of labels;
the map is keyed by question **text** in the original order; unanswered questions are
**omitted** rather than sent empty; a freeform-only answer is the literal `["Other"]` with
the typed text in `annotations[q].notes`; `preview` rides along only for single-select.

Getting these wrong does not fail loudly. It produces an agent that acts on an answer to a
question nobody asked. If you change one, change it in `newgrok/` too and re-run the
end-to-end checklist.

---

## Conventions

**Go.** Standard library plus chi, coder/websocket, pquerna/otp — that is the whole
dependency list and it should stay that way. `slog` for logging, never `fmt.Println`.
Comments explain *why*; the code already says what. Errors reaching a browser go through
`Event{Type: EventError}` so the UI can show them rather than the socket dying quietly.

**One writer per socket.** `coder/websocket` allows a single concurrent writer, so every
connection has exactly one writer goroutine draining a bounded queue. If you need to send
from a new place, push to `outbound`/`send`; do not call `conn.Write` directly.

**Backpressure is a disconnect.** A full queue drops the connection and the client
reconnects into a fresh snapshot. Do not "fix" this by growing the buffer — the snapshot is
cheaper than the backlog it would replay.

**Nothing blocks the reader goroutine.** Anything slow (a prompt, a cancel) runs detached
under `context.WithoutCancel`. A prompt can take minutes; waiting inline would freeze the
Stop button that is meant to end it.

**Frontend.** HeroUI 3 sits on react-aria-components: buttons take `onPress`, not
`onClick`, and there is no provider component to wrap. Tailwind 4 is CSS-first — there is
**no `tailwind.config.js`**; theme tokens and `@source "./"` live in `web/src/index.css`.
Use the semantic token classes already in use rather than arbitrary `bg-[var(--x)]` values.

**Never render agent output as markup.** Plans, tool output and model text are printed as
text. The CSP is `default-src 'self'` with no `unsafe-inline` for scripts; keep it that way.

**`useTheme` is called exactly once,** at the root in `App.tsx`. Each call owns its own
state, so a second call silently desyncs the toggle.

---

## Tests

```sh
go test ./...              # all five internal packages
go test -race ./internal/hub -run TestOnlyTheFirst -count=3
```

`internal/hub/hub_test.go` drives the hub over **real WebSocket connections** with a fake
grok and fake browsers, because the behaviour under test is the interleaving of three
goroutines and a mocked transport would test the mock. If you add a command or an event,
add it there.

Two things to know before you write a hub test:

- `interaction_resolved` is **broadcast to every browser**. A test with two browsers must
  consume the broadcast on the second one before asserting anything about its own reply, or
  it will read the first browser's resolution and report a confusing failure.
- Agent-list churn arrives whenever a connection comes or goes. `fakeBrowser.expect` skips
  it; assert on the event kind you care about, not on message order.

`internal/httpapi/server_test.go` covers the auth boundary: the bootstrap 404, enrollment,
rate limiting, cookie forgery, both upgrades, and the SPA fallback's refusal to swallow
`/api/*`.

---

## End-to-end checklist

Unit tests cannot cover the race against a real terminal. Run this against a real grok with
`/rc` on before shipping any change to the bridge, the interaction path, or the wire format.

1. `glance serve` → bootstrap → enroll TOTP → `glance apikey add laptop`.
2. Put the printed `[remote_control]` block in `~/.grok/config.toml`.
3. Start grok, type `/rc` → a system block confirms connected, **and the TUI stays fully
   usable**. This is the whole premise of the feature.
4. Send a prompt from the browser → it appears in the terminal and streams to both.
5. Trigger a tool needing approval → approve in the **browser** → the terminal's modal
   closes by itself.
6. Same again, approving in the **terminal** → the browser's card closes by itself.
7. Repeat 5–6 for `x.ai/ask_user_question` and `x.ai/exit_plan_mode`. All three race through
   the same path, but only permissions get exercised by accident.
8. Start a long turn, press **Stop** in the browser → the turn aborts, and the session log
   attributes it to `client:glance`, not to Esc.
9. Confirm tool-call deltas and `turn_completed` reach the browser — proof the xAI rail is
   mirrored and not just `session/update`.
10. **Kill glance mid-turn.** The TUI must keep working; the bridge reconnects with backoff
    and replays. Remote control must never be able to take the local session down with it.

Step 10 is the one that matters most.

---

## Working on the Rust half

In `newgrok/`, and read its `CLAUDE.md` first. The short version:

- `patches/` is the source of truth and is tracked; `work/` is disposable build output.
  **Edit in `work/`, commit there, then `make rebuild` to export patches.** Never edit a
  `.patch` by hand.
- **`make apply` does `git reset --hard` + `git clean -fdx` in `work/`.** Running it with
  uncommitted work destroys that work with no warning.
- The root `Cargo.toml` is generated. Treat it as read-only; per-crate manifests take
  `workspace = true` deps.
- Cargo on this box is I/O-heavy enough to disturb the machine. Build throttled and in the
  foreground:
  ```sh
  nice -n 19 env CARGO_CMD=test PKG=xai-grok-pager ./scripts/build.sh --lib -j 2
  ```
  `cargo` is only on `PATH` via `scripts/lib.sh`, so go through `scripts/build.sh`. Use
  module-qualified test filters (`rc::`, `slash::commands::rc`) — a bare `rc` matches
  hundreds of unrelated tests.
- `doctor_cmd::tests::fake_standalone_facts_compose_through_shared_view` fails on a clean
  upstream tree. It is not yours.
- Adding a pager slash command requires listing it in `xai-grok-shell`'s
  `PAGER_COMMAND_KEYS`, or `pager_builtin_triggers_are_reserved_in_shell` fails.

The RC code is `xai-grok-pager/src/rc/` (`mod`, `protocol`, `ring`, `tee`, `transport`) plus
`slash/commands/rc.rs` and `app/dispatch/rc.rs`. `tee.rs` is the interesting one: it is a
single interception point on the pager's ACP channel, and keeping it that way is what keeps
upstream conflicts survivable.

---

## Things that will bite you

- **`vite build` empties `web/dist/`,** taking `.gitkeep` with it — and `web/embed.go` needs
  a file there or `go build` fails on a clean clone with an unhelpful embed error. The
  `web` and `clean` targets restore it; a bare `npm run build` does not.
- **`__Host-` is a browser-enforced contract**: Secure, `Path=/`, no `Domain`. Change any of
  those and the browser silently discards the cookie, which looks exactly like a broken
  login.
- **A used TOTP step is burned.** Logging in twice inside one 30-second window fails the
  second time. That is the replay defence, not a bug.
- **The rate limiter is global, not per-user** — there are no users. Eight failures in five
  minutes locks out *everyone*, including a correct code. Tests must account for it.
- **Reconnecting with the same API key replaces the previous connection.** Two grok
  instances sharing one key will fight over the slot; give each its own.
- **A `false` return from `Answer`/`Decline` is not an error.** It is the ordinary outcome
  of losing the race, and it must produce `by:"elsewhere"`, not a 500.