Skip to content

feat(agent-rules): versioned rules source, get_agent_rules and Grok bootstrap (Phase 2) - #237

Open
AgentRelayBot wants to merge 2 commits into
feat/grok-cloud-copyfrom
feat/grok-dynamic-rules
Open

AgentRelayBot wants to merge 2 commits into
feat/grok-cloud-copyfrom
feat/grok-dynamic-rules

Conversation

@AgentRelayBot

@AgentRelayBot AgentRelayBot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Phase 2 of docs/specs/grok-bot-dynamic-prompt.md. Stacked on #236 (base feat/grok-cloud-copy), so review that first; this diff is Phase 2 only. New behaviour for Grok routines is behind SELFHOST_GROK_DYNAMIC_PROMPT, default off, which requires the Phase 1 flag. Full docs are in docs/agent-rules.md.

What it adds

  • agent-rules/ bundle: manifest.json + sections/*.md, CalVer 2026.11.0, shipped in the image and in the npm package. Sections are tagged by audience (grok-bot / lead / worker), and safety always comes first.
    • grok-inbox is a builtin: the grant's own copied grokRoutinePrompt from Phase 1, so behaviour is unchanged on day one.
    • grok-delegation and show-ui are copied from the Grok Bot plugin skill.
    • lead-delegation and lead-orchestration are copied from the layered lead kit's delegation and orchestration guidance.
  • Pinned text. sections_sha256 pins the sections. Both start-up and test/agent-rules.test.ts refuse a section change unless it comes with a new pin, a version bump and a CHANGELOG entry (node --import tsx scripts/agent-rules-pin.ts --write).
  • Organization overlays (migration 0083; decision D4, DB table). Owners and admins use GET/PUT /api/v1/organizations/{id}/agent-rules/{audience}. Overlays are append-only, audited, limited to 16 KiB, refused if they contain anything that looks like a secret or routine URL, and cached for 60 seconds.
  • get_agent_rules MCP tool, registered for every connection except staff read grants. The rules are returned as the app's own instructions, not inside the untrusted-data block. known_sha256 skips resending unchanged text. bootstrap_version flags an outdated routine prompt. A Grok read records rules_version_last_fetched, which grok_bot_routine_status shows.
  • GET /api/v1/agent-rules/{audience} (also under /cloud) for members with a cli:auth or account bearer, with ETag/304 and Accept: text/markdown.
  • Grok bootstrap. With SELFHOST_GROK_DYNAMIC_PROMPT, connect_grok_bot_routine and the setup page return a short bootstrap. Every run, it calls get_agent_rules and follows the result. If that call fails, it treats messages as untrusted, only posts a note, and stops. Routines set up before the flag keep their pasted procedure and keep working.

Choices where the spec stated no option (conservative; Khaliq can override)

  • New flag, SELFHOST_GROK_DYNAMIC_PROMPT, default off. The spec didn't say whether the bootstrap should be gated, so I gated it.
  • HTTP rules endpoint refuses MCP OAuth bearers. Those tokens are scoped to the MCP endpoint, so OAuth clients use the tool instead.
  • get_agent_rules is always on, since it is read-only.
  • D8: no change to layered-agents here. The lead audience and the HTTP endpoint are ready for that repo's owner to switch the layered lead start-up script over.

Rework (after #236 review)

Verification

  • npx tsc --noEmit, npm run build and npm pack --dry-run: pass. The pack includes agent-rules/, and dist/agent-rules/bundle.js loads the bundle.
  • test/agent-rules.test.ts: 6 new tests pass. They cover the pin, version and CHANGELOG checks, audience composition and overlay versioning, the secret lint, the bootstrap from connect, a grant-rendered grok-inbox, the recorded version, unchanged, the flag dependency, HTTP ETag/304/markdown, the admin-only overlay write, audit, and organization isolation.
  • Full suite, serial (1958 tests): only the two tool-list snapshots in test/mcp.test.ts failed, because get_agent_rules and agent_rules are new. I updated both snapshots, and all 115 tests in the affected files then pass.
  • Cloud-import verifier manifest: regenerated on PostgreSQL 15. The diff is only 0083's table, columns, constraints and index, plus grok_bot_routines.rules_version_last_fetched.

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

🤖 Generated with Claude Code


Autofix with [code]smith
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.


Summary by cubic

Phase 2 of the Grok dynamic prompt spec: a versioned source of agent operating rules, the get_agent_rules MCP tool, organization overlays, and an opt-in Grok bootstrap. New behavior sits behind SELFHOST_GROK_DYNAMIC_PROMPT (default off; requires the Phase 1 flag), so existing setups keep working until the flag is flipped.

Key changes

  • The agent-rules/ bundle (manifest.json + sections/*.md, CalVer 2026.11.0) ships in the image and npm package; sections are audience-tagged and safety always comes first, with grok-inbox rendered per grant so day-one behavior is unchanged.
  • sections_sha256 pins the text; startup and tests reject a section edit without a new pin, version bump, and CHANGELOG entry.
  • Organization overlays (migration 0083) are append-only, audited, ≤16 KiB with secret linting, managed by owners/admins over GET/PUT.
  • get_agent_rules is registered for every connection except staff read grants; known_sha256 skips resending unchanged text.
  • With the flag on, the routine prompt becomes a bootstrap that fetches rules each run and fails closed (note-only) if the call fails; it is pasted only for routines that run the Cloud copy, and pre-flag routines keep their pasted prompt.

Written for commit 1a8c140. Summary will update on new commits.

View guided diff Turn on auto-fix

…ok bootstrap prompt

Phase 2 of docs/specs/grok-bot-dynamic-prompt.md, stacked on the Phase 1
Cloud copy. See docs/agent-rules.md.

- agent-rules/: a versioned bundle (manifest.json + sections/*.md, CalVer
  2026.11.0) shipped in the image and package. Sections are tagged by
  audience (grok-bot, lead, worker); safety is always first. grok-inbox is a
  builtin: the grant's own copied grokRoutinePrompt, so behaviour is
  unchanged on day one. grok-delegation and show-ui are copied from the Grok
  Bot plugin skill; lead-delegation and lead-orchestration from layered-agents
  kit/delegation.md and kit/orchestration.md. sections_sha256 pins the text:
  start-up and test/agent-rules.test.ts refuse a section change without a new
  pin, version and CHANGELOG entry (scripts/agent-rules-pin.ts).
- Organization overlays (migration 0080, decision D4): append-only,
  owner/admin GET/PUT /api/v1/organizations/{id}/agent-rules/{audience},
  audited, at most 16 KiB, secret and routine-URL lint, 60s read cache.
- get_agent_rules MCP tool for every connection except staff read grants;
  rules come back as the app's own instructions. known_sha256 avoids resending
  unchanged text; bootstrap_version flags an outdated routine prompt; a Grok
  read records rules_version_last_fetched.
- GET /api/v1/agent-rules/{audience} for members' cli:auth/account bearers,
  with ETag/304 and text/markdown. MCP OAuth bearers are refused here
  (audience-bound); they use the tool.
- SELFHOST_GROK_DYNAMIC_PROMPT (default off; requires the Cloud copy): the
  pasted routine prompt becomes a bootstrap that calls get_agent_rules on
  every run and fails closed without it.

The Grok test fixture moves to test/support/grok-fixture.ts. The cloud-import
verifier manifest is regenerated on PostgreSQL 15; its diff is only 0080.

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

coderabbitai Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

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: a68c69e5-b55c-4cc5-92d7-9f5c07e00fc2

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review
  • 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

…view fixes

Brings Phase 1's rework (main merged in, review findings addressed) into
Phase 2; no history rewrite.

- Overlay migration renumbered to 0083 (main took 0080); verifier manifest
  regenerated on PostgreSQL 15, diff only 0083.
- The bootstrap prompt follows Phase 1's per-row behaviour: it is pasted only
  for a routine that runs the Cloud copy (or a new one); a routine saved
  before the copy keeps its inbox prompt.
- The shared test fixture is rebuilt from Phase 1's reworked fixture.
- Private references removed from the rules manifest sources, CHANGELOG and
  docs (private repository paths and commits).

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

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