Skip to content

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

Open
AgentRelayBot wants to merge 2 commits into
mainfrom
feat/grok-cloud-copy
Open

AgentRelayBot wants to merge 2 commits into
mainfrom
feat/grok-cloud-copy

Conversation

@AgentRelayBot

@AgentRelayBot AgentRelayBot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

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 fix(mcp): hosted participants enrol through relaygate on gate-only installs #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

…OK_ROUTINES_CLOUD_COPY

Phase 1 of docs/specs/grok-bot-dynamic-prompt.md. A copy, not a migration:
Cloud is unchanged and keeps serving its bots. Default off; with the flag off
the #136 behaviour in docs/grok-bot.md is unchanged.

Copied as is from AgentWorkforce/cloud @ 84578009505b:
- grok-routine.ts: grokRoutinePrompt, SHOW_UI_GUIDANCE, grokRoutineHeaders,
  parseGrokRoutineUrl/Key/Details/AgentName, perBotConnectionRequired
  (byte-identical apart from RoutineConfigError's base class).
- sender-check.ts, and the reply policy (eventSteps, repliesAutomatically,
  CHANNEL_ASK_TO_REPLY, replyCall) in grok-events-policy.ts.
- connect_grok_bot_routine (webhook and polling; name/from/mode;
  next_steps), disconnect_grok_bot_routine (mode/webhook_url), get_event
  and get_recent_events descriptions and output.

What the copied prompt directly needs:
- Migration 0079: routine delivery_mode, reply_mode (default notes-only,
  decision D2), from_filter, polling_since, routine_url_hash (one grant per
  routine URL); grok_bot_events, a per-grant event log with message text
  encrypted under the Control keyring, kept seven days.
- The worker ingests each inbox delivery into that log inside the grant
  fence, sends one Cloud-shaped relay.message / relay.channel_message wake
  per event (summary only; webhook-id = eventId; X-MCP-Subscription-Id =
  grant), and acknowledges deliveries only after commit. A failed wake keeps
  its event id and backs off.
- get_event / get_recent_events (tool group grok_events, Grok connections
  only). The sender is trusted only as a roster agent the person owns.
- The setup page accepts one paste, a reply mode and a sender filter.
- Copy mode replaces the #136 webhook-only handler (decision D1).

Cloud-import verifier manifest regenerated on PostgreSQL 15 with the dry-run
harness: the diff is only 0079's objects.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

Important

  • Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: f383ba0a-fc47-4c20-b040-fa6c7a81b508
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@agent-relay-code agent-relay-code Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed at 4d81b30. Requesting changes: two defects block the merge, and the branch has to be reworked on top of #231, which lands first.

Blocking

  1. Flag off is not unchanged once a polling row exists (src/mcp/grok-routines.ts, tick). The candidate query selects delivery_mode='polling' rows whatever the flag says, and the flag-off branch returns at if (!routine.credentials_ciphertext) return; without moving next_attempt_at. After an operator turns the flag on, someone connects in polling mode and the flag goes off again, that row is picked every tick forever (one authenticatedAgent call each time), and because the scan is ORDER BY next_attempt_at LIMIT 20, twenty such rows starve every webhook routine. Either leave polling rows out of the candidate query when the copy is off, or advance next_attempt_at in that branch. Needs a test.

  2. Sender trust rests on agent metadata (src/mcp/grok-events.ts, senderTrust). An agent is "your agent" when its roster metadata.owner_hash equals sha256(userId). That value is a plain hash of an id other workspace members can see, and it sits in metadata that is not only written by this service (an agent holding its own token can merge metadata into its own card; #231's gate path relies on exactly that call). With acknowledge or answer, a trusted sender gets an automatic reply, so this decision should not depend on a value the sender may be able to set. Decide trust from rows this service owns: the sender's agent id must match one of this person's hosted participant, desktop identity or binding rows. Needs a test with a roster agent that carries the right hash and is not in those tables. Note that after #231 gated agents carry no owner marker at all, so the metadata check would also never trust a person's own agents on a gate-only install.

  3. Rework on top of #231 (it merges first and takes migration 0079):

    • renumber the migration to the next free number, regenerate scripts/cloud-import-verify/schema-manifest.json, and update the file name in docs/grok-bot.md;
    • copyScan and the post-commit acknowledgement must go through the same client #231 selects for the participant (the gate client and refreshed token for a gated participant) and run after its recovery early-returns; on a gate-only install the routine must never talk to Relaycast with the participant token directly. The roster read should follow the same directory choice;
    • the copied connect tool calls join before any grant() check (main's tool calls status() first). With #231's grant-level admission kind, a grant that is not a Grok Bot grant would be joined and enrolled before it is refused. Check the grant first;
    • add a gate-only test for ingest and acknowledgement.

Should fix in this PR

  1. Retention (copyScan, disconnect, the grant-failure delete in tick). Events older than seven days are deleted only inside copyScan for a grant with a live routine. Disconnecting, losing the grant check in tick, or turning the flag off leaves the encrypted events in place, and get_event / get_recent_events do not filter by age. Delete a grant's events when its routine row goes, and sweep by created_at independent of the flag (the docs promise seven days).

  2. Turning the flag on changes existing routines silently. Existing webhook routines move to one wake per event with deliveries acknowledged by the worker, while their already-pasted prompt still reads the inbox, which is now always empty: the bot wakes and sees nothing until the person pastes the new prompt. Those rows also keep routine_url_hash NULL, so the one-URL rule does not cover them. Ingest only for rows saved under the copy, or state the migration step and enforce it.

  3. Duplicate URL race answers 500. The duplicate check is a SELECT then an INSERT; two saves of the same URL at once make the loser fail the unique index with an error that is not a GrokRoutineError. Map 23505 on that index to the duplicate answer.

Smaller

  1. With the flag off, describe_capabilities now lists the new group as unavailable with the generic "not part of this edition" text. Leave the group out when the flag is off, or give it its own reason.
  2. A wake whose stored payload cannot be decrypted stays pending and blocks later wakes for that grant. Deliveries the bot sent itself are filtered but never acknowledged, so they can fill the 100-item page. The seq cursor is one sequence across all grants, so its gaps show other tenants' volume; a per-grant cursor avoids that.
  3. Public text. Comments and docs in this diff name a private repository's paths and a commit of it, a private issue number, a production incident date, and an example agent name built from a person's name. The PR description does the same. Please remove these; this repository is public.

Checked and sound: webhook target pinning and redirect: "error"; secrets stay out of errors and logs; event reads are scoped to the grant; ingest is idempotent and acknowledges only after commit; OAuth revocation removes events; the new table and sequence are in src/control-tables.ts; the migration adds constant-default columns only.

I did not run the suite on this head; the points above are from reading the code. I will re-review after the rework.

Merges main (including #231's relaygate path); no history rewrite.

Review findings on #236:
- Migration renumbered to 0082 (main took 0079-0081); verifier manifest
  regenerated on PostgreSQL 15, diff only 0082.
- Flag off no longer scans Cloud-copy rows. A per-row cloud_copy marker
  decides behaviour: rows saved before the flag keep inbox-batch wakes when
  it is turned on, so an already-pasted prompt is never silently broken;
  saving again with the flag on moves a row to the copy. The setup page marks
  such a routine. Polling rows are always copy rows (CHECK).
- Sender trust comes only from rows this service owns: the person's hosted
  participants, Desktop identities and bound Amp/Capy bindings in this
  workspace. Agent metadata is never used; person identities give the sender
  kind. The scan no longer reads the roster.
- Ingest and post-commit acknowledgements use #231's client choice and the
  renewed token, after its recovery early-returns; a gated participant never
  talks to Relaycast directly. Gate-only test added.
- connect_grok_bot_routine checks the grant (setup allowed) before joining.
- Retention: events reference their routine row ON DELETE CASCADE
  (disconnect, revocation, grant loss), every scan deletes events older than
  seven days whatever the flag, and reads never return them.
- A concurrent duplicate routine-URL save maps the unique-index error to the
  duplicate answer. The URL hash is stored for every save.
- grok_events gets its own capability reason. An undecryptable event is
  skipped instead of blocking later wakes; the bot's own deliveries are
  acknowledged; the cursor is a per-grant sequence.
- Private references removed from comments, docs and the spec (repository
  paths, a commit, an issue number, incident dates, a person-derived example
  agent name).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@AgentRelayBot

Copy link
Copy Markdown
Contributor Author

Addressed in 1d9f17c. Main was merged in rather than rebased, so no history was rewritten. Each finding:

  1. Flag off with a polling row. Copy rows are now marked cloud_copy. While the flag is off, both the candidate query and the row lock skip them, so they are never scanned and cannot starve other routines. Tested.
  2. Sender trust. It now comes only from rows this service owns: the person's hosted_relay_participants, desktop_relay_identities, and bound amp_bindings / capy_bindings, all in this workspace's Relaycast workspace. Agent metadata is never consulted, and the roster read is gone. A test covers an agent whose metadata carries the right hash but has no row: it is not trusted.
  3. fix(mcp): hosted participants enrol through relaygate on gate-only installs #231.
    • Migration renumbered to 0082, the manifest regenerated on PostgreSQL 15, and the docs updated.
    • copyScan and the post-commit acknowledgements use the scan's via client and its renewed token, after the recovery early-returns. A gate-only test asserts the reads and acks go through relaygate, with no direct Relaycast call.
    • The connect tool checks the grant (status(..., {setup: true})) before joining.
  4. Retention. grok_bot_events now references grok_bot_routines(grant_id) ON DELETE CASCADE, so disconnect, grant loss and revocation all delete a routine's events. Every scan deletes events older than seven days whatever the flag says, and get_event / get_recent_events filter by age. Tested.
  5. Turning the flag on. Behaviour is decided per row: routines saved before the flag keep inbox-batch wakes and an untouched inbox. The setup page marks them, and saving again moves them to the copy. The URL hash is now stored on every save. Tested.
  6. Duplicate URL race. A 23505 on grok_bot_routines_routine_url now maps to the duplicate answer. Tested against a real index violation.
  7. Capabilities. grok_events has its own reason and how-to-enable text when it isn't planned.
  8. Small items. An undecryptable event is skipped (tested). The bot's own deliveries on the page are acknowledged. The cursor is the grant's own grant_seq.
  9. Private references. Repository paths, a commit, an issue number, incident dates and the person-derived example agent name are removed from the comments, docs, spec and PR description. Older commits still contain them until a squash merge; rewriting history needs Khaliq's separate OK.

Please re-review.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant