# @kentcdodds/grok-bot

## Intent

Register named Grok Bots by their Cursor webhook URL, then wake one by id or
name. Kody workers POST a prompt directly to that bot's `api2.cursor.sh`
webhook. There is no hop through a dispatcher bot. Sender keys never enter
chat, package storage, or execute params — save them on kody.codes.

Discord channels under the personal **Grok Bot** category are the phone front
door: a Kent-authored message in `#cole` wakes Cole, `#kody` wakes Kody, and
so on. The bot replies in that same Discord channel once its webhook and
sender key are registered.

Plus aliases on the Kody inbox are the email front door:
`kentcdodds+cole@inbox.kody.codes` wakes Cole, `kentcdodds+patch@inbox.kody.codes`
wakes Patch. Kent will often forward a thread and ask the bot to investigate,
reply, or draft a reply. The wake prompt includes this Kody message, a thread
message count, and guidance for the bot to pull more of the thread and reply
or draft when appropriate.

## What it does

- Keeps a roster of named bots (id, name/aliases, webhook host, Discord
  channel, plus-alias address) in this package's storage — never sender keys.
- Wakes a bot by POSTing `{ id, name, prompt }` (plus Discord/email context
  when present) to that bot's own Cursor webhook.
- Routes Kent's Discord messages in the Grok Bot category to the mapped bot.
- Routes mail to `kentcdodds+{bot}@inbox.kody.codes` (also `inbox.heykody.app`
  / `inbox.heykody.dev`) to the mapped bot when the thread is Kent-opened.

## Prerequisites / setup

1. Create a Grok Bot webhook routine in Cursor (HTTPS on `api2.cursor.sh`).
2. Register the bot with its UUID, human name, and webhook URL (agents: see
   `AGENTS.md`).
3. Open the returned save URL on kody.codes and paste the **sender key** there.
   Do not paste keys in chat. Secret name pattern: `grokBotWake.<botId>`.
4. If asked, approve host `api2.cursor.sh` on that secret before the first wake.
5. Optional: sync Discord so each bot has a channel under the Grok Bot
   category; plus-alias addresses appear on the roster after register.

## Done when

- Roster lists the bot with a channel and plus-alias address.
- Sender key exists for `grokBotWake.<botId>` and `api2.cursor.sh` is approved.
- A Kent message in that Discord channel, or mail to the plus-alias, wakes the
  bot and it can reply in-channel / stay on the email thread.
- A late webhook ACK does not double-wake (one try, no retry).

Agent import paths, dry-run smoke tests, self-register prompt text, and
cross-package wake wiring live in [`AGENTS.md`](./AGENTS.md). Other packages
depend on `@kentcdodds/grok-bot` and prefer `import wake from
'kody:@kentcdodds/grok-bot/wake'` — stamp-aligned secret authority keeps
sender keys locked to this package. Webhook entry remains `./handle-wake`.

## Debug

Agents can compare registered webhook *shape* without leaking secrets via
`kody:@kentcdodds/grok-bot/roster-fingerprints` (host, path prefix, hashed last
segment length/hash, duplicates). See [`AGENTS.md`](./AGENTS.md).