Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 58 additions & 0 deletions docs/grok-bot.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,3 +94,61 @@ Scheduled polling can be a Grok schedule that calls `check_relay_inbox`; the
self-hosted connect tool accepts only `mode:"webhook"`. Use the
`agent-relay-grok-bot-selfhosted` skill from `AgentWorkforce/skills` for the
customer-facing setup; the hosted plugin's configured MCP URL points to Cloud.

## Cloud copy mode (`SELFHOST_GROK_ROUTINES_CLOUD_COPY`)

Off by default. With it off, everything above applies unchanged. With it on,
new Grok Bot routines get Agent Relay Cloud's routine behaviour: Cloud's
routine prompt, sender check and reply policy, copied as is. Cloud itself is
not changed. See [the spec](specs/grok-bot-dynamic-prompt.md), Phase 1. Apply
migration `0082_grok_routines_cloud_copy.sql` first.

- **Per routine, not per server.** A routine uses the copy only if it was
saved on the setup page, or connected for polling, while the flag was on
(`cloud_copy`). Routines saved before keep the inbox-batch behaviour above,
whatever the flag says now, because their pasted prompt reads
`check_relay_inbox`. The setup page marks such a routine. Replacing its
instructions in Grok and saving it again moves it to the copy. With the flag
off, copy routines are not scanned: they neither wake nor delay other
routines.
- `connect_grok_bot_routine` takes Cloud's `{name, from, mode}` and returns
Cloud's `routine_prompt` and `next_steps`. `mode:"webhook"` returns
`setup_url` (this server's page). `mode:"polling"` stores no credential and
returns `suggested_interval_minutes: 15`. Choosing a mode replaces the
other for this connection. The grant is checked before anything is joined.
`disconnect_grok_bot_routine` takes `mode` or `webhook_url`; passing neither
stops both.
- The copied prompt calls `get_event` and `get_recent_events`. These are
registered for Grok connections only, in tool group `grok_events`, which is
listed only while the flag is on. The worker ingests each inbox delivery into
`grok_bot_events`, with message text encrypted under the Control keyring,
and acknowledges the page only after the events have committed. That
includes the bot's own sends, so they cannot fill the 100-item page.
`check_relay_inbox` is therefore empty for a copy routine.
- Reads and acknowledgements use the same client as the rest of the scan.
On a gate-only install a gated participant reads and acknowledges through
relaygate with its own (renewed) token and never talks to Relaycast
directly.
- Events are kept for seven days, then deleted on the next scan whatever
the flag says. They are also deleted with their routine: on disconnect, on
revocation, or when the grant is no longer valid. Reads never return older
events. `cursor` is the grant's own sequence.
- A webhook routine gets one wake per message, with Cloud's body
(`{eventId, name:"relay.message"|"relay.channel_message", timestamp, cursor, data}`).
`data.summary` is the first 200 characters of the message. The headers are
`Authorization`, `webhook-id` = `eventId` and `X-MCP-Subscription-Id` =
grant id. A retry keeps the same `eventId`. An event whose payload can no
longer be decrypted is skipped rather than blocking later wakes. A `from`
filter limits which messages wake the routine.
- `get_event` returns Cloud's app block: `Sender check: trustedSender …` and
`Reply setting: replyMode …`, followed by the steps. A sender is trusted only
when its agent ID belongs to one of this person's own rows in this
workspace: a hosted participant, a Desktop identity, or a bound Amp or Capy
binding. Agent metadata is never used for trust. The setup page's **How to
reply** sets the reply mode. `notes-only` (the default) never replies.
`acknowledge` and `answer` reply automatically only to trusted senders and
ask the person about anyone else.
- The setup page also accepts one paste of the routine's URL and header. A
routine URL can be saved under only one connection on this server; a
concurrent second save gets the same refusal. Do not also register it in
Agent Relay Cloud or another deployment, or it wakes twice.
1 change: 1 addition & 0 deletions docs/repository-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -219,6 +219,7 @@ is explicit. History is served only by the sessions pipeline: see
| `SELFHOST_MCP_OAUTH` | Optional, default on. Hosted MCP OAuth connectors; `off`, `false` or `0` disables them (`on`/`true`/`1` enables; other spellings fail start-up). A missing or partial signing-key set, invalid key material or an unreadable MCP OIDC `_FILE` leaves the server running (routes answer 501 `mcp_oauth_unavailable`); a value supplied both directly and via `_FILE` still fails start-up. See [docs/mcp-oauth.md](mcp-oauth.md) |
| `SELFHOST_MCP_EVENTS` | Optional, default off (`on`/`true`/`1` or `off`/`false`/`0`). Setting for the separate MCP Events module, which this server does not mount. See [docs/mcp-oauth.md](mcp-oauth.md) |
| `SELFHOST_MCP_EVENTS_PUMP` | Optional, default off, same spellings. Events pump setting; `on` requires `SELFHOST_MCP_EVENTS=on` or start-up fails |
| `SELFHOST_GROK_ROUTINES_CLOUD_COPY` | Optional, default off, same spellings. Grok Bot routines use Agent Relay Cloud's copied prompt, polling mode, encrypted event log and per-message wakes (migration `0082`). See [docs/grok-bot.md](grok-bot.md#cloud-copy-mode-selfhost_grok_routines_cloud_copy) |
| `AMP_TRANSPORT_ORIGIN` / `AMP_TRANSPORT_TOKEN[_FILE]` | Optional, set together. Bare https origin of the persistent Amp process service and its bearer (at least 32 bytes); calls go to `POST /v1/internal/amp/operation`. Unset: every Amp operation answers 503 `amp_transport_not_configured` |
| `SELFHOST_AMP_INTERNAL_SECRET` | Optional (`_FILE` supported), at least 32 bytes. Bearer for `POST /api/v1/internal/amp/job` (scheduler sweeps and inject jobs). Unset: that route answers 404 |
| `SELFHOST_AMP_WORKER_INTERVAL_MS` / `SELFHOST_AMP_LEASE_MS` | Outbox drain interval, default 5000 (250-600000), and delivery lease, default 120000 (1000-3600000). An expired lease becomes `unknown` and is never resent |
Expand Down
23 changes: 11 additions & 12 deletions docs/specs/grok-bot-dynamic-prompt.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ There are three phases, all in relay-control:

1. **Copy** Cloud's Grok Bot webhook handling into relay-control as it is:
`grokRoutinePrompt`, `connect_grok_bot_routine` and what they directly need.
**This is a copy, not a migration.** Cloud (`AgentWorkforce/cloud`) is not
**This is a copy, not a migration.** Agent Relay Cloud is not
changed and keeps serving every bot connected to it. There is no cutover, no
move of existing routines and no Cloud rollback plan.
2. Make the Grok Bot initial prompt **dynamic**: a versioned rules source in
Expand All @@ -23,13 +23,13 @@ There are three phases, all in relay-control:

| Piece | Location in `cloud` | What it does |
|---|---|---|
| Routine contract | `packages/web/lib/mcp-events/grok-routine.ts` | `parseGrokRoutineUrl`, `parseGrokRoutineKey`, `parseGrokRoutineDetails` (one-paste), `parseGrokRoutineAgentName`, `perBotConnectionRequired`, `grokRoutineHeaders` (Bearer `crsr_` key + `X-MCP-Subscription-Id` + `webhook-id`), `SHOW_UI_GUIDANCE`, and **`grokRoutinePrompt()`**: a hardcoded template for webhook or polling mode, with or without reply rights |
| Sender-check strings | `lib/mcp-events/sender-check.ts` | `SENDER_CHECK` / `REPLY_SETTING` labels, quoted by both the prompt and `get_event`'s app block |
| MCP tools | `lib/mcp-events/server.ts` (~390–475) | `connect_grok_bot_routine` (webhook or polling; returns `routine_prompt`, `inbox_address`, `setup_url` or `suggested_interval_minutes`, `next_steps`), `disconnect_grok_bot_routine`; the prompt depends on `get_event` / `get_recent_events` |
| Delivery | `lib/mcp-events/service.ts` (`post` / `postRoutine`, ~513–529) | Events pump; POSTs a thin `relay.message` / `relay.channel_message` event to the routine URL. Row in `mcp_event_subscriptions`, `delivery_mode='routine'` (`secrets[0]` is the `crsr_` key) or `'polling'` |
| Setup context | `lib/mcp-events/grok-setup-context.ts`, `grok-setup.ts` | Setup-page query keys; `hasGrokRoutine(principal)` |
| UI | `app/connect/grok/*`, `app/dashboard/relay/grok-routine-*`, `app/oauth/connect/grok/*` | Next.js browser flows |
| Plugin | `integrations/grok-bot/` (v0.1.4): `mcp.json` → `https://agentrelay.com/cloud/api/v1/mcp/relay-events`; `skills/agent-relay-grok-bot/SKILL.md` | Static skill: connect, wake-up setup, wake handling, delegation, `show_ui` |
| Routine contract | Cloud's Grok routine module | `parseGrokRoutineUrl`, `parseGrokRoutineKey`, `parseGrokRoutineDetails` (one-paste), `parseGrokRoutineAgentName`, `perBotConnectionRequired`, `grokRoutineHeaders` (Bearer `crsr_` key + `X-MCP-Subscription-Id` + `webhook-id`), `SHOW_UI_GUIDANCE`, and **`grokRoutinePrompt()`**: a hardcoded template for webhook or polling mode, with or without reply rights |
| Sender-check strings | Cloud's sender-check module | `SENDER_CHECK` / `REPLY_SETTING` labels, quoted by both the prompt and `get_event`'s app block |
| MCP tools | Cloud's MCP Events server | `connect_grok_bot_routine` (webhook or polling; returns `routine_prompt`, `inbox_address`, `setup_url` or `suggested_interval_minutes`, `next_steps`), `disconnect_grok_bot_routine`; the prompt depends on `get_event` / `get_recent_events` |
| Delivery | Cloud's MCP Events service (`post` / `postRoutine`) | Events pump; POSTs a thin `relay.message` / `relay.channel_message` event to the routine URL. Row in `mcp_event_subscriptions`, `delivery_mode='routine'` (`secrets[0]` is the `crsr_` key) or `'polling'` |
| Setup context | Cloud's Grok setup helpers | Setup-page query keys; `hasGrokRoutine(principal)` |
| UI | Cloud's connect, dashboard and consent pages for Grok | Next.js browser flows |
| Plugin | The Grok Bot plugin: `mcp.json` → `https://agentrelay.com/cloud/api/v1/mcp/relay-events`; `skills/agent-relay-grok-bot/SKILL.md` | Static skill: connect, wake-up setup, wake handling, delegation, `show_ui` |

### 0.2 relay-control today (self-hosted port, merged in #136)

Expand Down Expand Up @@ -89,9 +89,8 @@ and data exist in relay-control:

**Not copied:** Cloud's MCP Events pump and `mcp_event_subscriptions`. The
existing worker delivers instead. Also not copied:
`grok-setup-context.ts` / `grok-setup.ts`, because relay-control keys setup by
grant id behind the browser session. Cloud's Next.js `app/connect/grok/*` and
`app/dashboard/relay/grok-routine-*` are not copied either; relay-control's
Cloud's Grok setup helpers, because relay-control keys setup by
grant id behind the browser session. Cloud's Next.js connect and dashboard pages for Grok are not copied either; relay-control's
server-rendered setup page gains the same fields (one-paste box, reply mode,
sender filter). Porting the dashboard UI to relay-web is separate (D3).

Expand Down Expand Up @@ -192,7 +191,7 @@ The text is returned as the application's own instructions, in a content block
labelled `Agent Relay app: operating rules (version …)`. It is not placed in the
untrusted-content wrapper that relay messages use. Cloud learned that chats
refuse instructions found inside untrusted blocks (see the comment on
`answer_reply_question` in Cloud `server.ts`).
`answer_reply_question` in Cloud).

**HTTP** (for non-MCP consumers such as `lead-run.sh`):
`GET /api/v1/agent-rules/{audience}` (and the `/cloud` alias). The response has
Expand Down
39 changes: 39 additions & 0 deletions migrations/0082_grok_routines_cloud_copy.sql
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
-- Grok Bot routines, Cloud copy (docs/specs/grok-bot-dynamic-prompt.md, Phase 1).
-- Existing rows keep the inbox-batch behaviour (cloud_copy false) whatever
-- SELFHOST_GROK_ROUTINES_CLOUD_COPY says; a row becomes a Cloud-copy row only
-- when it is saved, or connected for polling, with the flag on.

-- A polling routine has no webhook credential.
ALTER TABLE grok_bot_routines
ALTER COLUMN credentials_ciphertext DROP NOT NULL,
ADD COLUMN cloud_copy boolean NOT NULL DEFAULT false,
ADD COLUMN delivery_mode text NOT NULL DEFAULT 'webhook' CHECK (delivery_mode IN ('webhook', 'polling')),
ADD COLUMN reply_mode text NOT NULL DEFAULT 'notes-only' CHECK (reply_mode IN ('notes-only', 'acknowledge', 'answer')),
ADD COLUMN from_filter text CHECK (from_filter IS NULL OR length(from_filter) BETWEEN 1 AND 512),
ADD COLUMN polling_since timestamptz,
-- sha256 of the routine URL, so one Grok routine is saved under at most one grant.
ADD COLUMN routine_url_hash text,
ADD CONSTRAINT grok_bot_routines_polling_copy CHECK (delivery_mode <> 'polling' OR cloud_copy),
ADD CONSTRAINT grok_bot_routines_credentials CHECK (delivery_mode = 'polling' OR credentials_ciphertext IS NOT NULL);
CREATE UNIQUE INDEX grok_bot_routines_routine_url ON grok_bot_routines(routine_url_hash) WHERE routine_url_hash IS NOT NULL;

-- Cloud's copied prompt reads a durable event log (get_event, get_recent_events)
-- and never acknowledges Relaycast deliveries itself. The worker ingests each
-- delivery here (message text encrypted with the Control keyring), then
-- acknowledges it. Events belong to the routine row and go with it; the worker
-- also deletes any older than seven days. grant_seq is the grant's own cursor.
CREATE TABLE grok_bot_events (
grant_id uuid NOT NULL REFERENCES grok_bot_routines(grant_id) ON DELETE CASCADE,
event_id text NOT NULL CHECK (event_id ~ '^evt_[a-f0-9]{32}$'),
grant_seq bigint NOT NULL CHECK (grant_seq >= 1),
name text NOT NULL CHECK (name IN ('relay.message', 'relay.channel_message')),
sender text,
occurred_at timestamptz NOT NULL,
trusted_reason text CHECK (trusted_reason IS NULL OR trusted_reason IN ('your agent')),
payload_ciphertext text NOT NULL,
notified_at timestamptz,
created_at timestamptz NOT NULL DEFAULT now(),
PRIMARY KEY (grant_id, event_id),
UNIQUE (grant_id, grant_seq)
);
CREATE INDEX grok_bot_events_created ON grok_bot_events(created_at);
8 changes: 6 additions & 2 deletions openapi.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -548,6 +548,7 @@ paths:
/cloud/api/v1/grok-bot/routine:
parameters:
- {name: grant, in: query, required: true, schema: {type: string, format: uuid}}
- {name: from, in: query, required: false, schema: {type: string, maxLength: 512}, description: "Cloud copy only: sender filter carried from connect_grok_bot_routine"}
get:
operationId: grokRoutineSetup
tags: [MCP OAuth]
Expand All @@ -574,13 +575,16 @@ paths:
application/json:
schema:
type: object
required: [webhook_url, authorization]
description: webhook_url and authorization are required unless SELFHOST_GROK_ROUTINES_CLOUD_COPY is on and routine_details is given.
properties:
webhook_url: {type: string, maxLength: 512, writeOnly: true}
authorization: {type: string, writeOnly: true, description: The routine crsr_ key or Authorization Bearer header}
routine_details: {type: string, maxLength: 4096, writeOnly: true, description: "Cloud copy only: one paste containing exactly one routine URL and one crsr_ key"}
reply_mode: {type: string, enum: [notes-only, acknowledge, answer], description: "Cloud copy only; default notes-only. acknowledge and answer reply automatically only to agents the person owns"}
from: {type: string, maxLength: 512, description: "Cloud copy only: wake only for messages from this agent (defaults to the page's from query parameter)"}
responses:
"200": {description: Configuration saved without echoing secrets}
"400": {description: Invalid credentials or unavailable/unowned/unpinned Grok grant}
"400": {description: Invalid credentials or reply mode, a routine already saved under another connection, or an unavailable/unowned/unpinned Grok grant}
"401": {description: Browser sign-in required; MCP bearers are refused}
"403": {description: Invalid Origin or browser account capability}
"404": {description: Module disabled, invalid grant ID or workspace inaccessible}
Expand Down
Loading
Loading