feat(grok): copy Cloud's Grok Bot routine handling (Phase 1, flag off by default)

AG
2d ago
+1437-63

Phase 1 of docs/specs/grok-bot-dynamic-prompt.md (#233). This is a copy, not a migration: Agent Relay Cloud is unchanged and keeps serving every bot connected to it. Everything is behind SELFHOST_GROK_ROUTINES_CLOUD_COPY, default off.

Copied as is from Agent Relay Cloud

  • The Grok routine module: grokRoutinePrompt, SHOW_UI_GUIDANCE, grokRoutineHeaders, parseGrokRoutineUrl/Key/Details/AgentName and perBotConnectionRequired. The code and prompt text are identical; only the import path, an error base class and two comments differ.
  • sender-check.ts and the reply policy (eventSteps, repliesAutomatically, CHANNEL_ASK_TO_REPLY, replyCall).
  • connect_grok_bot_routine (webhook and polling; name/from/mode; Cloud's next_steps) and disconnect_grok_bot_routine (mode/webhook_url).
  • The output of get_event / get_recent_events, including the app block with Sender check: trustedSender … and Reply setting: replyMode ….

What the copied prompt directly needs

  • Migration 0082.
    • Routine columns: cloud_copy, delivery_mode, reply_mode, from_filter, polling_since and routine_url_hash, which allows one grant per routine URL.
    • grok_bot_events: a log per routine, with message text encrypted under the Control keyring. Events are deleted with their routine and are kept for at most seven days. grant_seq is the grant's own cursor.
  • Worker. It ingests each inbox delivery into the log inside the grant fence, through #231's client choice and the participant's renewed token. It sends one Cloud-shaped relay.message / relay.channel_message wake per event, carrying a 200-character summary, with webhook-id = eventId and X-MCP-Subscription-Id = grant. Deliveries are acknowledged after the commit, the bot's own sends included.
  • grok_events tool group, for Grok connections only while the flag is on.
  • Sender trust comes only from rows this service owns: the person's hosted participants, Desktop identities, and bound Amp and Capy bindings.
  • Setup page. It accepts one paste, a reply mode (default notes-only, decision D2) and a sender filter.

Per-routine behaviour

A routine uses the copy only if it was saved, or connected for polling, while the flag was on. Routines saved before keep their inbox-batch behaviour, so turning the flag on never breaks a prompt someone has already pasted. The setup page marks such a routine, and saving it again moves it to the copy. With the flag off, copy routines are not scanned at all.

Decisions

  • D1: for Grok connections, copy mode replaces the existing webhook-only handler.
  • D2: the reply mode defaults to notes-only.
  • D3: this server's own setup page is extended; the relay-web UI comes later.

Verification

  • npx tsc --noEmit and npm run build: pass.
  • Full suite, serial: 2085 tests, 0 failures.
  • test/grok-routines-cloud-copy.test.ts: 12 tests. They now also cover server-owned trust, flag-off non-scanning, unchanged pre-flag routines, retention, unreadable events, the duplicate-URL race, and gate-only ingest and acknowledgement.
  • Cloud-import verifier manifest: regenerated on PostgreSQL 15. The diff is only 0082.

No merge, deploy or flag flip without Khaliq's direct OK.

🤖 Generated with Claude Code