codeburn/docs/providers/grokbot.md
Resham Joshi 3684f1d5f0
Some checks are pending
CI / semgrep (push) Waiting to run
macOS Menubar CI / test (push) Waiting to run
Tests / test (22) (push) Waiting to run
Tests / test (22.13.0) (push) Waiting to run
Tests / test (24) (push) Waiting to run
Tests / test (26) (push) Waiting to run
Tests / test-platforms (macos-latest) (push) Waiting to run
Tests / test-platforms (windows-latest) (push) Waiting to run
Tests / desktop (push) Waiting to run
Grok Bot: sessions, estimated spend and the weekly allowance on all three surfaces (#1462)
Adds xAI's Grok Bot desktop app as a provider: per-bot sessions with estimated usage, and the weekly allowance read through the Cursor IDE login on the CLI, desktop Plans screen and menubar. No row unless the app is installed. Two independent review rounds on real data.
2026-09-16 21:17:48 +02:00

79 lines
8.7 KiB
Markdown

# Grok Bot
Grok Bot, xAI's Electron desktop agent app (bundle id `com.anysphere.sand`). Not Grok Build, xAI's coding CLI — that is the separate [`grok`](grok.md) provider.
Mapped against **app version 0.30.0**. The app self-updates, so the parser ignores unknown entry kinds and unknown fields rather than rejecting a file.
- **Source:** `src/providers/grokbot.ts`
- **Loading:** eager (`src/providers/index.ts`)
- **Test:** `tests/providers/grokbot.test.ts`
## Where it reads from
`$CODEBURN_GROKBOT_DIR`, else the app's Electron userData directory:
| Platform | Path |
| --- | --- |
| macOS | `~/Library/Application Support/Grok Bot/sand-client-persistence` |
| Windows | `%APPDATA%\Grok Bot\sand-client-persistence` |
| Linux | `~/.config/Grok Bot/sand-client-persistence` |
**Not** `~/.grokbot`. That directory is the app's `$SAND_DATA_ROOT` (marked by `.grokbot-data-root-v1`) and holds the host process, the local exec daemon, settings, secrets and content-addressed runtime binaries. Its `agents/<uuid>/store.db` tables are empty on 0.30 and `search-index.db` has no rows: the authoritative agent store lives on the remote box at `/home/box/sand-data/agents/<id>/store.db`, and nothing in `~/.grokbot` carries usage.
## Storage format
JSON. Each file in `sand-client-persistence` is one client slice, named `base32(sliceKey).blob` (RFC 4648, lowercase, unpadded) and containing `{"schemaVersion":N,"value":…}`. Two slices matter:
- `sand.client.slice.account.<accountSlot>.roster.last-roster` — `value.rows[]`, one row per bot, with `id`, `name` ("Reddit Bot", "HN Reviewer"), avatar, unread state and `path`.
- `sand.client.slice.account.<accountSlot>.transcript.replicas.<agentId>` — `value.entries[]`, the transcript.
Transcript entry kinds: `message` (`role` `user`/`assistant`, `content`, optional `fromAgent`/`toAgent` for bot-to-bot), `send-message` (the bot's own output, `message.type` `text`/`widget`/`attachment`/`user-form`/…, optional `wake`), `event` (`event.type: "automation-changed"` with `automationName` — the Routines feature), `user-attachment`. Timestamps are `timestampMs`, ms since the epoch, UTC.
## Sessions and projects
Grok Bot has no projects and no session ids: work is organised as named bots, one per `agentId`, each with a chat thread, an attached browser screen and scheduled **Routines**. One transcript replica is one CodeBurn session, `sessionId` is the `agentId`, and the bot's roster `name` is used as both `project` and `agentName` so the report groups by bot. A bot missing from the roster falls back to its `agentId`.
One call is one `requestId` — the app stamps a prompt and every message the bot emits in reply with the same id.
**Routine runs are not human turns.** A `send-message` carries `wake` (`background-revival`, `handoff-resume`, `agent`) when the bot woke on its own, and a `message` carrying `fromAgent` came from another bot rather than from the person. A request with no bare user message is emitted with an empty `userMessage`, so the task classifier never reads a scheduled run as something someone asked for.
## Token model
**Estimated, always.** The local mirror records no token counts, no cost and no model id — a deep scan of every entry field finds no `usage`, `*Tokens`, `cost` or `model` anywhere, and the same holds for every other slice, for `search-index.db` and for every file under `~/.grokbot`. Input is estimated from the text of the `message` entries in a request (the person's prompt, plus anything another bot sent in), output from the `send-message` content, both through the repo's shared `CHARS_PER_TOKEN`. Cache-read, cache-creation and reasoning tokens are all zero; there is nothing to read them from. Every call sets `costIsEstimated: true`, and the provider is deliberately left out of the provider-name list in `providerCallToCachedCall` (`src/parser.ts:2571`) that carries a tool's own metered cost through the cache, so the cost is recomputed from the estimated tokens.
**The replica is a window, not an archive.** The app keeps roughly the last 200 entries per bot locally. A `lifetime` total covers what is still mirrored, not the bot's whole history.
**No tool calls and no bash commands.** The bots drive a browser and a sandbox shell, but no tool-call or command record reaches this machine — `tools` and `bashCommands` are always empty.
## Pricing
`grokbot-auto` is aliased to `grok-4.6` in `src/models.ts`, xAI's published rate of $2.00 / M input, $6.00 / M output and $0.50 / M cached input. The app serves opaque Cursor `sand-*` model aliases (`sand-78zum5`, `sand-cua`, …) and records none of them locally, so there is no honest per-model attribution to make; pricing it at xAI's current flagship rate, with the cost flagged estimated, is the closest truthful reading.
## Deduplication
Per `grokbot:<agentId>:<requestId>`.
## Quota
`codeburn quota`, the desktop app's Plans screen (`app/electron/quota/grokbot.ts`, a port of the reader below; the row is omitted when the app is not installed) and the macOS menubar's Grok Bot row (`mac/.../GrokBotSubscriptionService.swift`) all report Grok Bot's weekly allowance — the same "Weekly usage NN%, resets in N days" the app's own account menu shows, read from the call the app itself makes:
- `POST https://api2.cursor.sh/aiserver.v1.DashboardService/GetSandUsageStatus`, Connect-RPC, empty JSON body, `Authorization: Bearer <cursor token>`. Response: `usagePercent` (0..100), `currentPeriodStart`, `nextResetTimestampUtc` (exactly seven days apart), `hasNonZeroIncludedLimit`, `usesPooledEnterpriseAllowance`, `hasAvailableUsage`, `upgradeRecommendation`, and `grokPlanLabel` on newer builds. Emitted as one window labelled `Weekly usage`.
- `GetCurrentPeriodUsage` on the same service returns `spendLimitUsage { individualUsed, individualLimit }` in cents, the "Change limit" surface. Not read: it is a spend cap, not a capacity window.
**No app, no row.** All three readers first check that the app is on the machine — `/Applications/Grok Bot.app`, `~/Applications/Grok Bot.app`, or the `~/.grokbot` data root — and leave the provider out entirely when it is absent. The reading would otherwise still succeed and report whichever account Cursor is signed into, under a Grok Bot label. An account that is signed in but has no per-account reading (a pooled enterprise allowance, or no included allowance) is reported as a terminal state carrying that sentence, not as "not connected".
**The credential is the Cursor IDE's, not Grok Bot's.** Grok Bot keeps its own copy of the Cursor session in `sand-secrets.json` as an Electron `safeStorage` blob (base64 of `v10` plus AES-128-CBC ciphertext, key in the macOS keychain), and CodeBurn does not decrypt an app's safe storage — the rule stated for "Codex Safe Storage" at `src/quota/codex.ts:109`. The Cursor IDE stores the same kind of token unencrypted in its VS Code state database under `cursorAuth/accessToken`, so `src/quota/grokbot.ts` reuses `src/quota/cursor.ts`'s read-only lookup of that row rather than duplicating it.
The consequence is a real precondition, not a detail: **this reading is Grok Bot's only when the Cursor app is signed into the account Grok Bot uses.** With Cursor signed out, the provider reports "not signed in", the same state `src/quota/cursor.ts` reports. With Cursor signed into a different account, the percentage is that other account's. Nothing local can verify the two match. `src/quota/cursor.ts` is not a substitute either: it reads `cursor.com/api/usage-summary` and reports that dashboard's monthly window, a different allowance on the same vendor's dashboard.
**Quota is the only usage number that exists.** The bots run on xAI's cloud VM; the prompts, the model and the token counts never leave it, so no per-request usage is obtainable by any method — not by reading disk, not by any endpoint. The weekly percentage is a capacity reading, not accounting, and it cannot be reconciled against the estimated token totals above.
## Live sessions
Not wired up yet. The signals are there: `sand-session-marker.json` (`pid`, `appVersion`, `startedAtMs`, `aliveAtMs`, `crashSeen`) in the userData directory, `~/.grokbot/local-exec-daemon.json` (`pid`, `inflightCount`), `~/.grokbot/host.lock`, and the roster row's `awaitingUserResponse` / `lastActivityAt`.
## Quirks
- **Two xAI products, two providers.** `grok` is the Grok Build CLI under `~/.grok`; `grokbot` is this desktop app. They share nothing but a vendor.
- **Bots message each other.** A `message` with `fromAgent` is another bot's output arriving here. It is counted as input, because the receiving bot had to read it, and it is not treated as a human turn.
- **`~/.grokbot/inference-router-transcript.json`** is written by a third-party reconstruction of app version 0.18, not by the shipped app. It is ignored.