fix(agent-routing): support API model aliases

[chioarub]

Summary

• allow agentModels entries to set an optional provider-facing model value
• keep existing configs working by defaulting the API model to the agentModels key
• ignore blank api_key entries so broken local aliases do not create provider overrides
• document the route-key vs API-model distinction

Validation

• bun test src/services/api/agentRouting.test.ts src/tools/AgentTool/runAgent.routing.test.ts src/tools/AgentTool/AgentTool.routing.test.ts src/tools/AgentTool/AgentTool.teammateModel.test.ts src/utils/model/agent.test.ts src/utils/settings/flagSettings.test.ts

Summary by CodeRabbit

• New Features

  • Added support for model aliasing in agent routing—configure an optional model field in agentModels to map a route key to a different API model name.

• Documentation

  • Updated Agent Routing configuration examples with clarified guidance on route keys and model aliases.

• Tests

  • Added test coverage for model aliasing and agent provider resolution.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: fbb50da2-3338-4782-aee0-9691ee291585

📥 Commits

Reviewing files that changed from the base of the PR and between 1b7e550 and 4b7df5b.

📒 Files selected for processing (4)

• README.md
• src/services/api/agentRouting.test.ts
• src/services/api/agentRouting.ts
• src/utils/settings/types.ts

📜 Recent review details

🧰 Additional context used

📓 Path-based instructions (7)

**/*.{ts,tsx,js,jsx,py}

📄 CodeRabbit inference engine (CONTRIBUTING.md)

Follow the existing code style in the touched files and prefer small, readable changes over broad rewrites

Files:

• src/utils/settings/types.ts
• src/services/api/agentRouting.test.ts
• src/services/api/agentRouting.ts

**/*

⚙️ CodeRabbit configuration file

**/*: Apply the OpenClaude maintainer review rubric from AGENTS.md. Review the current diff, not stale discussion context. Separate real blockers from suggestions. Do not request changes for vague style churn. Treat approval as merge-ready from CodeRabbit's side, pending required human review and GitHub Checks. If checks are failing or unavailable, say so clearly instead of implying the PR is fully ready.

Files:

• src/utils/settings/types.ts
• src/services/api/agentRouting.test.ts
• src/services/api/agentRouting.ts
• README.md

**

⚙️ CodeRabbit configuration file

**: # Contributing to OpenClaude

Thanks for contributing.

OpenClaude is a fast-moving open-source coding-agent CLI with support for multiple providers, local backends, MCP, and a terminal-first workflow. The best contributions here are focused, well-tested, and easy to review.

Before You Start

• Search existing issues and discussions before opening a new thread.
• Check open pull requests for work that overlaps with your contribution. If a PR already exists that addresses the same change, open an issue or discussion first to align on direction — duplicate PRs may be closed without review.
• Use issues for confirmed bugs and actionable feature work.
• Use discussions for setup help, ideas, and general community conversation.
• For larger changes, open an issue first so the scope is clear before implementation.
• For security reports, follow SECURITY.md.

Pull Requests

Every PR needs a reason. Your PR description must include:

• what changed and why
• the user or developer impact
• the exact checks you ran
• a linked issue when one exists, using Fixes fix: skip assertMinVersion for third-party providers #123, `Closes `#123, or another clear link
• screenshots when the PR touches UI, terminal presentation, or the VS Code extension
• which provider path was tested when the PR changes provider behavior

The PR author is responsible for ensuring their PR is merge-ready. PRs with merge conflicts will not be reviewed or approved until the conflicts are resolved.

Issues are the recommended starting point for anything non-trivial — opening one first helps avoid wasted effort if the change is out of scope or already being worked on. Small fixes, doc corrections, and obvious improvements can stand on their own without a linked issue, as long as the PR description explains the intent.

What Gets Closed Without Review

PRs may be closed without review...

Files:

• src/utils/settings/types.ts
• src/services/api/agentRouting.test.ts
• src/services/api/agentRouting.ts
• README.md

**/*.test.{ts,js}

📄 CodeRabbit inference engine (CONTRIBUTING.md)

Add or update tests when the change affects behavior

Files:

• src/services/api/agentRouting.test.ts

{src/services/api/**,src/integrations/**,src/utils/model/**,src/utils/provider*.ts,src/commands/provider/**}

⚙️ CodeRabbit configuration file

{src/services/api/**,src/integrations/**,src/utils/model/**,src/utils/provider*.ts,src/commands/provider/**}: Review provider routing, model selection, env precedence, auth/token handling, OpenAI-compatible shims, retries, proxy behavior, and outbound HTTP behavior with high scrutiny. Block on silent default changes, hidden fallback expansion, credential reuse mistakes, hardcoded provider assumptions, or new network reach that is not intentional and documented.

Files:

• src/services/api/agentRouting.test.ts
• src/services/api/agentRouting.ts

{src/**/*.test.ts,src/**/*.test.tsx,tests/**,scripts/**/*.test.ts,vscode-extension/**/*.test.js}

⚙️ CodeRabbit configuration file

{src/**/*.test.ts,src/**/*.test.tsx,tests/**,scripts/**/*.test.ts,vscode-extension/**/*.test.js}: Review tests for meaningful coverage of the changed behavior, isolation of global/env/config state, async cleanup, fake timers, provider profile leaks, and Windows-compatible assumptions. Block when risky runtime changes lack focused regression coverage or tests assert implementation details while missing the user-visible behavior.

Files:

• src/services/api/agentRouting.test.ts

{README.md,CONTRIBUTING.md,docs/**,.github/pull_request_template.md}

⚙️ CodeRabbit configuration file

{README.md,CONTRIBUTING.md,docs/**,.github/pull_request_template.md}: Review docs for accuracy against current code behavior. Flag security or provider claims that overpromise, stale install commands, missing setup caveats, and instructions that could push users toward unsafe credential handling. Keep purely wording-level suggestions non-blocking.

Files:

• README.md

🧠 Learnings (2)

📓 Common learnings

Learnt from: CR
Repo: Gitlawb/openclaude PR: 0
File: coderabbit-custom-pre-merge-checks-unique-id-file-non-traceable-F7F2B60C-1728-4C9A-8889-4F2235E186CA.txt:0-0
Timestamp: 2026-06-04T22:10:40.834Z
Learning: Verify that product, trust-model, routing-default, telemetry/network, and permission-policy changes are not hidden inside unrelated cleanup. Flag the PR if the policy decision needs explicit maintainer alignment.

Learnt from: CR
Repo: Gitlawb/openclaude PR: 0
File: coderabbit-custom-pre-merge-checks-unique-id-file-non-traceable-F7F2B60C-1728-4C9A-8889-4F2235E186CA.txt:0-0
Timestamp: 2026-06-04T23:14:07.629Z
Learning: Verify that product, trust-model, routing-default, telemetry/network, and permission-policy changes are not hidden inside unrelated cleanup. Flag the PR if the policy decision needs explicit maintainer alignment.

📚 Learning: 2026-06-04T23:13:58.119Z

Learnt from: CR
Repo: Gitlawb/openclaude PR: 0
File: CONTRIBUTING.md:0-0
Timestamp: 2026-06-04T23:13:58.119Z
Learning: Applies to **/providers/**/*.{ts,tsx,js} : Provider changes must explicitly state which providers are affected and test the exact provider/model path that was changed

Applied to files:

• src/services/api/agentRouting.test.ts
• src/services/api/agentRouting.ts

🔇 Additional comments (4)

src/utils/settings/types.ts (1)

753-766: LGTM!

src/services/api/agentRouting.ts (1)

21-21: LGTM!

Also applies to: 54-68, 116-116, 130-130

src/services/api/agentRouting.test.ts (1)

133-167: LGTM!

Also applies to: 195-212, 292-309

README.md (1)

213-217: LGTM!

Also applies to: 227-227, 235-235

---

📝 Walkthrough

Walkthrough

This PR adds support for aliasing route keys to different API model names in agent routing. A new optional model field in agentModels entries allows configuring which actual model name is sent to the provider API, while the record key serves as a routing key. The provider override resolution is refactored to use a shared toProviderOverride() helper that normalizes and trims API keys.

Changes

Agent Model Aliasing Configuration

Layer / File(s)	Summary
Settings schema: agentModels with optional model field src/utils/settings/types.ts	agentModels record entries now include optional model field (actual API model name); record key is treated as route key/alias with guidance to use model when they differ.
Provider override resolution with normalization src/services/api/agentRouting.ts	Introduces AgentModelConfig type and shared toProviderOverride() helper that converts agentModels entries to ProviderOverride objects, trimming api_key and normalizing model names; resolveAgentProvider() and resolveAgentModelProvider() use the helper instead of inline construction.
Test coverage for model aliasing and blank keys src/services/api/agentRouting.test.ts	Added test cases for aliasing route keys to different API models, verifying null return when api_key is blank, and confirming fallback to parent model when selected provider has blank credentials.
README: configuration example and explanation README.md	Updated Agent Routing example to show agentModels.zai-default entry mapping to glm-5.1 model; revised explanation text clarifying how route keys map to API model names via optional model field.

---

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 3

❌ Failed checks (2 warnings, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 60.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Risk Surface Disclosed	⚠️ Warning	PR touches auth (API key handling) and provider routing but lacks explicit risk surface disclosure in review documentation.	Ensure review explicitly calls out auth/routing risks (api_key trimming, provider selection) and clarifies blocker status before merge.
Description check	❓ Inconclusive	The description covers what changed and why, but omits the required Impact and Testing sections from the template.	Add Impact (user-facing and developer impact) and Testing sections with checkboxes for build/smoke/check steps. Consolidate validation details into the Testing section format.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and accurately describes the main change: supporting API model aliases in agent routing configuration.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
No Hidden Policy Change	✅ Passed	No hidden policy changes. PR adds agent routing for model aliasing with explicit configuration, documented fallbacks, and intentional env override application only when routing configured.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[jatmn]

Thanks for the contribution. I do not see any actionable issues from my review.

[jatmn]

@kevincodex1