feat: Enhance model routing specs, documentation, and validation features

[yacosta738]

This pull request introduces a new capability registry system to the agent runtime, which formalizes how tools are described, registered, and validated as "capabilities." It ensures that the set of active tools matches the set of registered capabilities after profile and MCP (Managed Capability Provider) filtering, and adds comprehensive validation and error handling for capability descriptors. Additionally, it includes new and updated tests for classification logic and registry correctness, and minor workflow improvements for documentation checks.

Capability registry and tool registration:

• Introduces a new CapabilityRegistry type and related modules (descriptor, registry, tool_registration) that define, register, and validate tool capabilities using structured descriptors, including error handling for duplicate IDs, missing fields, and invalid metadata. (clients/agent-runtime/src/capabilities/descriptor.rs [1] clients/agent-runtime/src/capabilities/registry.rs [2] clients/agent-runtime/src/capabilities/mod.rs [3]
• Updates BootstrapContext to include a capability_registry field, ensuring the registry is built from the final set of active tools after profile filtering, and adds validation to guarantee registry and tool list consistency. (clients/agent-runtime/src/bootstrap/mod.rs [1] [2] [3] [4]
• Adds tests to verify that the capability registry matches the filtered tool set, preserves MCP/native tool classification, and enforces error handling for registration and validation. (clients/agent-runtime/src/bootstrap/mod.rs [1] [2] clients/agent-runtime/src/capabilities/registry.rs [3]

Classification and agent tests:

• Adds new tests for the agent's model classification logic, ensuring correct fallback to the default model when classification is disabled or no rules match. (clients/agent-runtime/src/agent/agent.rs clients/agent-runtime/src/agent/agent.rsR3069-R3130)

Workflow improvements:

• Updates the docs-quality.yml workflow to include and run the model-routing-docs.test.mjs script, improving documentation validation coverage. (.github/workflows/docs-quality.yml [1] [2]

Closes: #453

[linear]

DALLAY-173 Productize model routing and query classification for Corvus

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 4ea2f70e-dbf8-4c6a-a945-8bc21b43bbe6

📥 Commits

Reviewing files that changed from the base of the PR and between a8fb28e and 16d5326.

📒 Files selected for processing (18)

• clients/agent-runtime/src/bootstrap/mod.rs
• clients/agent-runtime/src/capabilities/descriptor.rs
• clients/agent-runtime/src/capabilities/mod.rs
• clients/agent-runtime/src/capabilities/registry.rs
• clients/agent-runtime/src/capabilities/tool_registration.rs
• clients/agent-runtime/src/lib.rs
• clients/agent-runtime/src/main.rs
• clients/agent-runtime/src/tools/mcp/adapter.rs
• clients/agent-runtime/src/tools/mcp/prompt_adapter.rs
• clients/agent-runtime/src/tools/mcp/resource_adapter.rs
• clients/agent-runtime/src/tools/traits.rs
• clients/web/apps/docs/src/content/docs/guides/model-routing.md
• openspec/changes/descriptive-capability-registry/design.md
• openspec/changes/descriptive-capability-registry/exploration.md
• openspec/changes/descriptive-capability-registry/proposal.md
• openspec/changes/descriptive-capability-registry/specs/capability-architecture/spec.md
• openspec/changes/descriptive-capability-registry/tasks.md
• openspec/changes/descriptive-capability-registry/verify-report.md

Disabled knowledge base sources:

• Linear integration is disabled

You can enable these sources in your CodeRabbit configuration.

---

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Introduced a capability registry system to track and describe available tools and capabilities within the runtime.
  • Registry is finalized during bootstrap after tool selection and profile filtering.
  • Supports both native tools and MCP-based capabilities (tools, resources, and prompts).
  • Added validation framework for capability descriptors with structured error handling.

• Documentation

  • Added comprehensive design and specification documents for the capability registry architecture.

Walkthrough

This PR introduces a non-executing descriptive capability registry system that registers native tools and MCP-derived capabilities during bootstrap after profile filtering, while preserving all existing runtime execution paths and dispatch behavior unchanged.

Changes

Cohort / File(s)	Summary
Capability Registry Module clients/agent-runtime/src/capabilities/{descriptor,registry,tool_registration,mod}.rs	Introduces descriptor model with versioning/lifecycle/security/compatibility/metadata types; validates descriptor shape, uniqueness, and MCP-required fields; builds registry from tool slice via descriptor construction and registration with duplicate detection.
Module Exports & Wiring clients/agent-runtime/src/{lib,main}.rs	Exposes new capabilities module at crate root.
Bootstrap Integration clients/agent-runtime/src/bootstrap/mod.rs	Adds capability_registry: CapabilityRegistry field to BootstrapContext; builds registry from final post-filtered tool set via build_registry_from_tools; adds unit tests verifying descriptor IDs match active tools and MCP classification semantics.
Tool Trait Extensions clients/agent-runtime/src/tools/{traits,mcp/{adapter,resource_adapter,prompt_adapter}}.rs	Adds optional descriptor_hint() method to Tool trait (default no-op); implements hint providers in MCP adapters with server/upstream/URI/mime-type/prompt-argument metadata; adds PartialEq/Eq derives to ToolSourceMetadata.
Documentation openspec/changes/descriptive-capability-registry/{design,exploration,proposal,tasks,verify-report}.md, openspec/changes/descriptive-capability-registry/specs/capability-architecture/spec.md	Design specification, exploration context, implementation proposal, phased task plan, and verification report for M2 capability registry feature.
Example Update clients/web/apps/docs/src/content/docs/guides/model-routing.md	Minor: updates Qwen model example from qwen/qwen3-32b to qwen-qwq-32b.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

• feat: Centralize bootstrap wiring and introduce Agent Loop specification #167 — Adds BootstrapContext that this PR directly extends with the capability_registry field and post-filter registry construction.
• feat(agent-runtime): complete gateway webhook dispatcher parity #283 — Modifies bootstrap flow in clients/agent-runtime/src/bootstrap/mod.rs, which this PR builds upon for registry wiring.
• feat: expand mcp platform support beyond tools only integration #336 — Extends MCP tooling (adapters, normalization, bootstrap) to expose descriptors integrated into the capability registry in this PR.

Suggested labels

area:architecture, type:feature, status:ready-for-review

Suggested reviewers

• yuniel-acosta

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 51.19% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main change (model routing specs, documentation, and validation features) and follows Conventional Commit style with 'feat' prefix, though it exceeds the 72-character limit by 1 character.
Description check	✅ Passed	The PR description is comprehensive, covering capability registry implementation, tool registration, validation, classification tests, and workflow improvements. All major sections align with the template structure.
Linked Issues check	✅ Passed	The PR fully implements the objectives from #453: introduces CapabilityRegistry with descriptor validation, registers native and MCP tools, validates shape/uniqueness/collisions, preserves security metadata, adds comprehensive tests, and leaves runtime execution unchanged.
Out of Scope Changes check	✅ Passed	All changes are in scope for #453. The PR adds capability registry infrastructure, validation, bootstrap integration, tests for classification and registry correctness, and documentation/workflow improvements—all aligned with the issue requirements. No unrelated refactoring or out-of-scope additions detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/dallay-173-productize-model-routing

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[cloudflare-workers-and-pages]

Deploying corvus with    Cloudflare Pages

Latest commit:	16d5326
Status:	✅  Deploy successful!
Preview URL:	https://ca3984ee.corvus-42x.pages.dev
Branch Preview URL:	https://feature-dallay-173-productiz.corvus-42x.pages.dev

View logs

[github-actions]

✅ Contributor Report

User: @yacosta738
Status: Passed (12/13 metrics passed)

Metric	Description	Value	Threshold	Status
PR Merge Rate	PRs merged vs closed	89%	>= 30%	✅
Repo Quality	Repos with ≥100 stars	0	>= 0	✅
Positive Reactions	Positive reactions received	10	>= 1	✅
Negative Reactions	Negative reactions received	0	<= 5	✅
Account Age	GitHub account age	3084 days	>= 30 days	✅
Activity Consistency	Regular activity over time	108%	>= 0%	✅
Issue Engagement	Issues with community engagement	0	>= 0	✅
Code Reviews	Code reviews given to others	530	>= 0	✅
Merger Diversity	Unique maintainers who merged PRs	2	>= 0	✅
Repo History Merge Rate	Merge rate in this repo	91%	>= 0%	✅
Repo History Min PRs	Previous PRs in this repo	207	>= 0	✅
Profile Completeness	Profile richness (bio, followers)	90	>= 0	✅
Suspicious Patterns	Spam-like activity detection	1	N/A	❌

---

_{Contributor Report evaluates based on public GitHub activity. Analysis period: 2025-04-07 to 2026-04-07}

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
91.5% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud