refactor(mcp): derive the agent tool lists from one metadata table

[erkamyaman]

What and why

The "generate AGENT_INSPECTOR / ACTION_TOOLS / PAGE_AGENT_ENTRIES from metadata" item from #372.

Adding an agent tool used to mean editing several hand-kept lists in config.ts. Forgetting one failed quietly: the tool stayed visible with its inspector off, or kept writing under agent.readOnly. Every built-in agent tool and resource now has one entry in AGENT_ENTRIES (101 entries, grouped by inspector), and the old lists derive from it.

interface AgentEntry {
  kind: 'tool' | 'resource' | 'rpc';
  inspectors?: readonly PangularInspector[]; // first hides it; all are its tags; omitted = shared
  safety?: 'action' | 'destructive';         // omitted = read
  readOnlyVariant?: true;                    // kept as read under agent.readOnly
  actions?: readonly PangularAction[];       // ACTION_TOOLS membership
  freeModes?: readonly string[];             // ACTION_TOOL_FREE_MODES
  page?: true;                               // PAGE_AGENT_ENTRIES
}

AGENT_INSPECTOR, AGENT_SAFETY, READ_ONLY_VARIANTS, ACTION_TOOLS, ACTION_TOOL_FREE_MODES and PAGE_AGENT_ENTRIES keep their exported names, types and values. agentTags() and agentInspector() read the entry. The derivations are marked /* @__PURE__ */, so the panel bundle does not change (pnpm extension:build gives no diff). The table lives in config.ts because the panel compiles it without allowImportingTsExtensions.

Nothing changes in behaviour. The old exports were dumped before any edit and compared with the new ones: no differences. That dump is committed as a test fixture.

Docs: AGENTS.md's quiet-failure rule, "Add an agent tool" in the contributing guide (a field table, the coverage test and the fixture step), docs/CONTEXT.md, and the devtools-inspector and devtools-fix-issue skills.

Left as they are: the clear-recordings special case in agentAllowed, and RPC_INSPECTOR, which is still kept by hand.

Refs #372.

How it was verified

• pnpm commit:check
• pnpm format:check
• pnpm typecheck
• pnpm test:devtools (3116) and pnpm test:panel (738). New agent-metadata.test.ts:
  • the derived lists deep-equal the fixture of the old values;
  • coverage: it boots the server and fails when a registered tool, resource or RPC tool has no entry, an entry is never registered, or the kind is wrong (deleting the lint-pipes entry makes it fail by name);
  • each tool registers with its entry's safety tier and tags;
  • the stdio server with pageTools: false drops exactly the page entries;
  • entries are consistent with RPC_INSPECTOR and with each other.
• pnpm skills:check
• Docs in apps/docs updated and pnpm docs:build passes
• pnpm extension:build: no change to extension/ui

Summary by CodeRabbit

• Documentation
  • Updated contributor and development guidance to explain how agent tools and resources are configured, including their inspectors, safety levels, actions, and page requirements.
  • Clarified how RPC functions and agent tools are registered.
• Tests
  • Added checks for agent metadata consistency, tool and resource coverage, safety levels, and page-tool configuration.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: aeb1aa5a-87ae-407c-aef9-65e8d1f667b1

📥 Commits

Reviewing files that changed from the base of the PR and between afc89c8 and fedcbc9.

📒 Files selected for processing: 10

• .claude/skills/devtools-fix-issue/SKILL.md
• .claude/skills/devtools-inspector/SKILL.md
• AGENTS.md
• apps/docs/src/content/contributing/development.md
• docs/CONTEXT.md
• packages/devtools/src/__tests__/agent-metadata.test.ts
• packages/devtools/src/__tests__/fixtures/agent-metadata-derived.json
• packages/devtools/src/config.ts
• packages/devtools/src/devframe.ts
• packages/devtools/src/hub-messages.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 8 remain after this review.

📝 Walkthrough

The change adds AGENT_ENTRIES as the registry for built-in agent metadata and derives several existing mappings from it. Tests and contributor guidance now check and describe registry coverage and metadata.

Changes: Agent metadata configuration

Layer / File(s)	Summary
Define the registry and derive agent metadata packages/devtools/src/config.ts, packages/devtools/src/devframe.ts, packages/devtools/src/hub-messages.ts	Adds AgentEntry and AGENT_ENTRIES. Derives action, free-mode, safety, inspector, and page-entry mappings from the registry. agentInspector and agentTags read inspector metadata from registry entries. Comments identify the registry as the source of tool tiers and tags.
Validate and document registry entries packages/devtools/src/__tests__/*, .claude/skills/*, AGENTS.md, apps/docs/src/content/contributing/development.md, docs/CONTEXT.md	Adds fixture-based tests for derived metadata, registered entries, and entry consistency. Updates guidance to describe registry entries and distinguish RPC registration in RPC_INSPECTOR from agent registration in AGENT_ENTRIES.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Refactor

Merge Risk: ⚪ Minimal · up to fedcb

No actionable issue remains from this review. The metadata change appears mergeable after normal checks.

Security architecture risk: 🔵 Low · up to fedcb

The refactor centralizes security-sensitive tool metadata without an identified expansion of access. Registration checks remain in place, but authorization inside every write handler was not verified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• observed — The affected policy includes tools classified for changing component state, HTTP rules and recordings, plus destructive operations for erasing recordings and writing to the application's API routes. The review establishes their policy metadata, not exhaustive downstream effects or production and tenant exposure.

Trust Boundaries and Controls

• observed — The hub wrapper awaits the tool handler before calling agentWrite. Its authorization check therefore controls reporting, not pre-execution permission. Handler rejection bypasses this reporting step, and reporting failures do not fail the completed tool. This ordering predates the PR; the hub change only updates a comment.
• inferred — No expansion of tool authority was identified in the compared registration and metadata paths. Registration-time gating was verified, but authorization before every downstream write, including direct or retained handler calls and concurrent configuration changes, remains unestablished rather than proven safe.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 63.64% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 4 files. (6 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: deriving agent tool lists from a single metadata table.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 63.64% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 4 files. (6 skipped: 6 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

🚀 Deploying Preview to Cloudflare 🚀

Preview Deployments by commit

Status	Deployment URL	Commit	Updated (UTC)	See this deployment's details
Build: Failed ❌ View logs ↗		fedcbc9	2026-10-15T20:39:12.042Z	View logs ↗

[nx-cloud]

View your CI Pipeline Execution ↗ for commit fedcbc9

Command	Status	Duration	Result
nx affected -t test build	✅ Succeeded	2m 36s	View ↗

💡 Verify your cache is correct by running tasks in a sandbox. Read docs ↗

---

☁️ Nx Cloud last updated this comment at 2026-10-15 20:41:14 UTC