From ac05394adcb5f6897d2518578d22cc92190317c4 Mon Sep 17 00:00:00 2001 From: beardthelion <56458543+beardthelion@users.noreply.github.com> Date: Sat, 13 Jun 2026 19:03:05 -0500 Subject: [PATCH 1/6] feat(agent-routing): allow model-only agentModels entries in settings schema --- src/utils/settings/agentModelsSchema.test.ts | 35 ++++++++++++++++++++ src/utils/settings/types.ts | 14 ++++++-- 2 files changed, 46 insertions(+), 3 deletions(-) create mode 100644 src/utils/settings/agentModelsSchema.test.ts diff --git a/src/utils/settings/agentModelsSchema.test.ts b/src/utils/settings/agentModelsSchema.test.ts new file mode 100644 index 0000000000..4eba44afc4 --- /dev/null +++ b/src/utils/settings/agentModelsSchema.test.ts @@ -0,0 +1,35 @@ +import { expect, test } from 'bun:test' +import { SettingsSchema } from './types.js' + +test('agentModels accepts a model-only entry (no base_url/api_key)', () => { + const result = SettingsSchema().safeParse({ + agentModels: { mini: { model: 'gpt-5-mini' } }, + agentRouting: { verification: 'mini' }, + }) + expect(result.success).toBe(true) +}) + +test('agentModels accepts a bare entry whose key is the model name', () => { + const result = SettingsSchema().safeParse({ + agentModels: { 'gpt-5-mini': {} }, + agentRouting: { verification: 'gpt-5-mini' }, + }) + expect(result.success).toBe(true) +}) + +test('agentModels still accepts a full cross-provider entry', () => { + const result = SettingsSchema().safeParse({ + agentModels: { + ds: { base_url: 'https://api.deepseek.com/v1', api_key: 'sk-ds' }, + }, + agentRouting: { verification: 'ds' }, + }) + expect(result.success).toBe(true) +}) + +test('agentModels rejects a non-URL base_url', () => { + const result = SettingsSchema().safeParse({ + agentModels: { bad: { base_url: 'not-a-url', api_key: 'sk' } }, + }) + expect(result.success).toBe(false) +}) diff --git a/src/utils/settings/types.ts b/src/utils/settings/types.ts index 514a1d617f..787161e2ca 100644 --- a/src/utils/settings/types.ts +++ b/src/utils/settings/types.ts @@ -754,14 +754,22 @@ export const SettingsSchema = lazySchema(() => .string() .optional() .describe('Actual model name to send to the API. Defaults to the surrounding agentModels key.'), - base_url: z.string().url().describe('OpenAI-compatible API endpoint (must be https:// or http://)'), - api_key: z.string().describe('API key for this provider'), + base_url: z + .string() + .url() + .optional() + .describe('OpenAI-compatible API endpoint (must be https:// or http://). Omit together with api_key to reuse the current provider (model-only route).'), + api_key: z + .string() + .optional() + .describe('API key for this provider. Omit together with base_url to reuse the current provider (model-only route).'), }), ) .optional() .describe( 'Map of route key to provider connection info. ' + - 'Example: { "deepseek-chat": { "base_url": "https://api.deepseek.com/v1", "api_key": "sk-xxx" } }. ' + + 'Cross-provider: { "deepseek-chat": { "base_url": "https://api.deepseek.com/v1", "api_key": "sk-xxx" } }. ' + + 'Model-only (reuse current provider): { "mini": { "model": "gpt-5-mini" } }. ' + 'Use "model" when the route key is an alias for a different API model name.', ), agentRouting: z From 2ad82f5b3473708505ae26f72b9608bad7b0b51e Mon Sep 17 00:00:00 2001 From: beardthelion <56458543+beardthelion@users.noreply.github.com> Date: Sat, 13 Jun 2026 19:04:20 -0500 Subject: [PATCH 2/6] feat(agent-routing): resolve model-only agent routes that reuse the current provider --- src/services/api/agentRouting.test.ts | 56 +++++++++++++++++++++ src/services/api/agentRouting.ts | 71 +++++++++++++++++---------- 2 files changed, 102 insertions(+), 25 deletions(-) diff --git a/src/services/api/agentRouting.test.ts b/src/services/api/agentRouting.test.ts index 0c59146739..fd1ec8ca56 100644 --- a/src/services/api/agentRouting.test.ts +++ b/src/services/api/agentRouting.test.ts @@ -168,6 +168,62 @@ describe('resolveAgentProvider', () => { }) +import { + isProviderOverride, + resolveAgentProvider, + resolveAgentRunModelRouting, +} from './agentRouting.js' + +const modelOnlySettings = { + agentModels: { + mini: { model: 'gpt-5-mini' }, + bare: {}, + 'half-entry': { base_url: 'https://api.example.com/v1' }, // missing api_key + }, + agentRouting: { + verification: 'mini', + Explore: 'bare', + Plan: 'half-entry', + }, +} as unknown as SettingsJson + +describe('model-only routes', () => { + test('resolveAgentProvider returns a model-only route (no credentials)', () => { + const route = resolveAgentProvider(undefined, 'verification', modelOnlySettings) + expect(route).toEqual({ model: 'gpt-5-mini' }) + expect(isProviderOverride(route!)).toBe(false) + }) + + test('bare entry defaults the model to the route key', () => { + const route = resolveAgentProvider(undefined, 'Explore', modelOnlySettings) + expect(route).toEqual({ model: 'bare' }) + }) + + test('partial entry (only base_url) is skipped', () => { + const route = resolveAgentProvider(undefined, 'Plan', modelOnlySettings) + expect(route).toBeNull() + }) + + test('resolveAgentRunModelRouting: model-only sets mainLoopModel, no providerOverride', () => { + const result = resolveAgentRunModelRouting({ + resolvedAgentModel: 'parent-model', + subagentType: 'verification', + settings: modelOnlySettings, + }) + expect(result).toEqual({ mainLoopModel: 'gpt-5-mini' }) + expect('providerOverride' in result).toBe(false) + }) + + test('resolveAgentRunModelRouting: no route falls back to resolvedAgentModel', () => { + const result = resolveAgentRunModelRouting({ + resolvedAgentModel: 'parent-model', + subagentType: 'unconfigured', + settings: modelOnlySettings, + }) + expect(result).toEqual({ mainLoopModel: 'parent-model' }) + }) +}) + describe('resolveAgentModelProvider', () => { test('returns null when settings is null', () => { expect(resolveAgentModelProvider('deepseek-chat', null)).toBeNull() diff --git a/src/services/api/agentRouting.ts b/src/services/api/agentRouting.ts index 9d9b6f0d09..a5873e1555 100644 --- a/src/services/api/agentRouting.ts +++ b/src/services/api/agentRouting.ts @@ -13,6 +13,17 @@ export interface ProviderOverride { apiKey: string } +/** A model-only route: reuse the session's current provider, just change the model. */ +export type AgentModelOnly = { model: string } + +/** A resolved agent route — a full cross-provider override or a model-only swap. */ +export type AgentRoute = ProviderOverride | AgentModelOnly + +/** Narrow an AgentRoute to a full cross-provider ProviderOverride. */ +export function isProviderOverride(route: AgentRoute): route is ProviderOverride { + return 'apiKey' in route && 'baseURL' in route +} + export interface AgentRunModelRouting { mainLoopModel: string providerOverride?: ProviderOverride @@ -51,20 +62,28 @@ function normalize(key: string): string { return key.toLowerCase().replace(/[-_]/g, '') } -function toProviderOverride( +function toAgentRoute( configuredModelKey: string, modelConfig: AgentModelConfig | undefined, -): ProviderOverride | null { +): AgentRoute | null { if (!modelConfig) return null - const apiKey = modelConfig.api_key.trim() - if (!apiKey) return null + const model = modelConfig.model?.trim() || configuredModelKey + const baseURL = modelConfig.base_url?.trim() + const apiKey = modelConfig.api_key?.trim() - return { - model: modelConfig.model?.trim() || configuredModelKey, - baseURL: modelConfig.base_url, - apiKey, + // Model-only route: no credentials → reuse the active provider, swap the model. + if (!baseURL && !apiKey) return { model } + + // Misconfiguration: a cross-provider route needs BOTH endpoint and key. + if (!baseURL || !apiKey) { + console.error( + `[agentRouting] Warning: agentModels entry "${configuredModelKey}" has only one of base_url/api_key; both are required for cross-provider routing. Skipping this route.`, + ) + return null } + + return { model, baseURL, apiKey } } /** @@ -76,7 +95,7 @@ export function resolveAgentProvider( name: string | undefined, subagentType: string | undefined, settings: SettingsJson | null, -): ProviderOverride | null { +): AgentRoute | null { if (!settings) return null const routing = settings.agentRouting @@ -113,21 +132,21 @@ export function resolveAgentProvider( if (!modelName) return null - return toProviderOverride(modelName, models[modelName]) + return toAgentRoute(modelName, models[modelName]) } /** - * Resolve provider override directly from a requested model name. + * Resolve an agent route directly from a requested model name (cross-provider or model-only). * Checks for an exact match in agentModels. Does not fuzzy match or normalize case. */ export function resolveAgentModelProvider( modelName: string | undefined, settings: SettingsJson | null, -): ProviderOverride | null { +): AgentRoute | null { if (!settings || !settings.agentModels || !modelName) return null const trimmedModelName = modelName.trim() - return toProviderOverride(trimmedModelName, settings.agentModels[trimmedModelName]) + return toAgentRoute(trimmedModelName, settings.agentModels[trimmedModelName]) } export function resolveAgentRunModelRouting({ @@ -150,21 +169,22 @@ export function resolveAgentRunModelRouting({ // Tool-specified models are explicit. If the request is not a configured // agentModels key, preserve getAgentModel() alias/inherit/custom-ID behavior // instead of falling through to persistent agentRouting. - const providerOverride = resolveAgentModelProvider(toolRequestedModel, settings) - return { - mainLoopModel: providerOverride?.model ?? resolvedAgentModel, - ...(providerOverride && { providerOverride }), + const route = resolveAgentModelProvider(toolRequestedModel, settings) + if (!route) return { mainLoopModel: resolvedAgentModel } + if (isProviderOverride(route)) { + return { mainLoopModel: route.model, providerOverride: route } } + return { mainLoopModel: route.model } } - const providerOverride = + const route = resolveAgentProvider(agentName, subagentType, settings) ?? resolveAgentModelProvider(agentDefinitionModel, settings) - - return { - mainLoopModel: providerOverride?.model ?? resolvedAgentModel, - ...(providerOverride && { providerOverride }), + if (!route) return { mainLoopModel: resolvedAgentModel } + if (isProviderOverride(route)) { + return { mainLoopModel: route.model, providerOverride: route } } + return { mainLoopModel: route.model } } /** @@ -189,13 +209,14 @@ export function resolveOutOfProcessTeammateProvider({ }): ProviderOverride | null { const requestedModel = cliModel?.trim() if (requestedModel) { - return resolveAgentModelProvider(requestedModel, settings) + const route = resolveAgentModelProvider(requestedModel, settings) + return route && isProviderOverride(route) ? route : null } - return ( + const route = resolveAgentProvider(agentName, agentType, settings) ?? resolveAgentModelProvider(agentDefinitionModel, settings) - ) + return route && isProviderOverride(route) ? route : null } export function resolveOutOfProcessTeammateProviderFromCliArgs( From 6237e43c708cf010b1a2ec9d59b8c9ff86fcd28f Mon Sep 17 00:00:00 2001 From: beardthelion <56458543+beardthelion@users.noreply.github.com> Date: Sat, 13 Jun 2026 19:07:18 -0500 Subject: [PATCH 3/6] feat(agent-routing): enforce org model allowlist for model-only agent routes --- src/services/api/agentRouting.test.ts | 21 +++++++++++++++------ src/services/api/agentRouting.ts | 14 ++++++++++++++ src/tools/AgentTool/runAgent.ts | 11 +++++++++-- 3 files changed, 38 insertions(+), 8 deletions(-) diff --git a/src/services/api/agentRouting.test.ts b/src/services/api/agentRouting.test.ts index fd1ec8ca56..3d35a34a7a 100644 --- a/src/services/api/agentRouting.test.ts +++ b/src/services/api/agentRouting.test.ts @@ -1,6 +1,7 @@ import { describe, expect, test } from 'bun:test' import { applyAgentProviderOverrideToEnv, + isProviderOverride, resolveAgentModelProvider, resolveAgentProvider, resolveAgentRunModelRouting, @@ -168,12 +169,6 @@ describe('resolveAgentProvider', () => { }) -import { - isProviderOverride, - resolveAgentProvider, - resolveAgentRunModelRouting, -} from './agentRouting.js' - const modelOnlySettings = { agentModels: { mini: { model: 'gpt-5-mini' }, @@ -548,3 +543,17 @@ describe('applyAgentProviderOverrideToEnv', () => { expect(env.ANTHROPIC_API_KEY).toBe('anthropic-key') }) }) + +import { shouldEnforceModelAllowlist } from './agentRouting.js' + +describe('shouldEnforceModelAllowlist', () => { + test('enforces when a provider override is present', () => { + expect(shouldEnforceModelAllowlist('m', 'm', true)).toBe(true) + }) + test('enforces when a model-only route changed the effective model', () => { + expect(shouldEnforceModelAllowlist('parent', 'gpt-5-mini', false)).toBe(true) + }) + test('does not enforce when the model is unchanged and no override', () => { + expect(shouldEnforceModelAllowlist('m', 'm', false)).toBe(false) + }) +}) diff --git a/src/services/api/agentRouting.ts b/src/services/api/agentRouting.ts index a5873e1555..b438c609da 100644 --- a/src/services/api/agentRouting.ts +++ b/src/services/api/agentRouting.ts @@ -187,6 +187,20 @@ export function resolveAgentRunModelRouting({ return { mainLoopModel: route.model } } +/** + * Whether the org model allowlist must be enforced for a resolved agent run. + * Enforce whenever routing changed the model: a cross-provider override is set, + * or a model-only route changed the effective model from what getAgentModel() + * resolved. An unchanged inherited model was already vetted upstream. + */ +export function shouldEnforceModelAllowlist( + resolvedAgentModel: string, + effectiveModel: string, + hasProviderOverride: boolean, +): boolean { + return hasProviderOverride || effectiveModel !== resolvedAgentModel +} + /** * Resolve provider routing for a teammate that will run as its own CLI process. * diff --git a/src/tools/AgentTool/runAgent.ts b/src/tools/AgentTool/runAgent.ts index 1b317e36c2..8251119214 100644 --- a/src/tools/AgentTool/runAgent.ts +++ b/src/tools/AgentTool/runAgent.ts @@ -58,7 +58,7 @@ import { executeSubagentStartHooks } from '../../utils/hooks.js' import { createUserMessage } from '../../utils/messages.js' import { getAgentModel } from '../../utils/model/agent.js' import { isModelAllowed } from '../../utils/model/modelAllowlist.js' -import { resolveAgentRunModelRouting } from '../../services/api/agentRouting.js' +import { resolveAgentRunModelRouting, shouldEnforceModelAllowlist } from '../../services/api/agentRouting.js' import { getInitialSettings } from '../../utils/settings/settings.js' import { clearAgentTranscriptSubdir, @@ -357,7 +357,14 @@ export async function* runAgent({ settings, }) - if (providerOverride && !isModelAllowed(effectiveModel)) { + if ( + shouldEnforceModelAllowlist( + resolvedAgentModel, + effectiveModel, + providerOverride !== undefined, + ) && + !isModelAllowed(effectiveModel) + ) { throw new Error( `Model '${effectiveModel}' is not available. Your organization restricts model selection.`, ) From b9140178f7a030b101520a3ffa5f5d7dad87f3cc Mon Sep 17 00:00:00 2001 From: beardthelion <56458543+beardthelion@users.noreply.github.com> Date: Sat, 13 Jun 2026 19:07:30 -0500 Subject: [PATCH 4/6] docs(agent-routing): document model-only routes and built-in agent keys --- README.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/README.md b/README.md index 8e53ff098c..542214094c 100644 --- a/README.md +++ b/README.md @@ -240,6 +240,21 @@ When no routing match is found, the global provider remains the fallback. > **Note:** `api_key` values in `settings.json` are stored in plaintext. Keep this file private and do not commit it to version control. +**Model-only routes (same provider):** Omit `base_url` and `api_key` to run an agent on a different model using your *current* provider's endpoint and key — no credential duplication: + +```json +{ + "agentModels": { + "mini": { "model": "gpt-5-mini" } + }, + "agentRouting": { + "verification": "mini" + } +} +``` + +**Built-in agents are routable by their type name.** Useful keys: `verification` (the read-only auditor that runs before completion), `Explore`, and `Plan`. For example, `"agentRouting": { "verification": "mini" }` runs the verifier on `gpt-5-mini` while your main session stays on its model. Absent any entry, the verifier inherits the main-loop model. + ## Web Search and Fetch By default, `WebSearch` works on non-Anthropic models using DuckDuckGo. This gives GPT-4o, DeepSeek, Gemini, Ollama, and other OpenAI-compatible providers a free web search path out of the box. From 3882ec4cb1ade6b96d21bd71e87cb381b550501b Mon Sep 17 00:00:00 2001 From: beardthelion <56458543+beardthelion@users.noreply.github.com> Date: Sat, 13 Jun 2026 20:28:52 -0500 Subject: [PATCH 5/6] test(agent-routing): stub and assert partial-entry routing warnings Silence the intentional console.error noise from partial agentModels entries in CI logs by stubbing console.error per describe block and asserting the expected warning message fires, so future routing warnings or failures are not masked. --- src/services/api/agentRouting.test.ts | 35 ++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/src/services/api/agentRouting.test.ts b/src/services/api/agentRouting.test.ts index 3d35a34a7a..0f76e7f690 100644 --- a/src/services/api/agentRouting.test.ts +++ b/src/services/api/agentRouting.test.ts @@ -1,4 +1,4 @@ -import { describe, expect, test } from 'bun:test' +import { afterEach, beforeEach, describe, expect, spyOn, test } from 'bun:test' import { applyAgentProviderOverrideToEnv, isProviderOverride, @@ -24,6 +24,14 @@ const baseSettings = { } as unknown as SettingsJson describe('resolveAgentProvider', () => { + let errorSpy: ReturnType + beforeEach(() => { + errorSpy = spyOn(console, 'error').mockImplementation(() => {}) + }) + afterEach(() => { + errorSpy.mockRestore() + }) + // ── Priority chain ────────────────────────────────────────── test('name takes priority over subagentType', () => { @@ -165,6 +173,9 @@ describe('resolveAgentProvider', () => { } as unknown as SettingsJson expect(resolveAgentProvider(undefined, undefined, settings)).toBeNull() + expect(errorSpy).toHaveBeenCalledWith( + '[agentRouting] Warning: agentModels entry "zai" has only one of base_url/api_key; both are required for cross-provider routing. Skipping this route.', + ) }) }) @@ -183,6 +194,14 @@ const modelOnlySettings = { } as unknown as SettingsJson describe('model-only routes', () => { + let errorSpy: ReturnType + beforeEach(() => { + errorSpy = spyOn(console, 'error').mockImplementation(() => {}) + }) + afterEach(() => { + errorSpy.mockRestore() + }) + test('resolveAgentProvider returns a model-only route (no credentials)', () => { const route = resolveAgentProvider(undefined, 'verification', modelOnlySettings) expect(route).toEqual({ model: 'gpt-5-mini' }) @@ -197,6 +216,9 @@ describe('model-only routes', () => { test('partial entry (only base_url) is skipped', () => { const route = resolveAgentProvider(undefined, 'Plan', modelOnlySettings) expect(route).toBeNull() + expect(errorSpy).toHaveBeenCalledWith( + '[agentRouting] Warning: agentModels entry "half-entry" has only one of base_url/api_key; both are required for cross-provider routing. Skipping this route.', + ) }) test('resolveAgentRunModelRouting: model-only sets mainLoopModel, no providerOverride', () => { @@ -268,6 +290,14 @@ describe('resolveAgentModelProvider', () => { }) describe('resolveAgentRunModelRouting', () => { + let errorSpy: ReturnType + beforeEach(() => { + errorSpy = spyOn(console, 'error').mockImplementation(() => {}) + }) + afterEach(() => { + errorSpy.mockRestore() + }) + test('explicit configured model wins over agentRouting', () => { const result = resolveAgentRunModelRouting({ resolvedAgentModel: 'parent-model', @@ -357,6 +387,9 @@ describe('resolveAgentRunModelRouting', () => { }) expect(result).toEqual({ mainLoopModel: 'parent-runtime-model' }) + expect(errorSpy).toHaveBeenCalledWith( + '[agentRouting] Warning: agentModels entry "zai" has only one of base_url/api_key; both are required for cross-provider routing. Skipping this route.', + ) }) }) From dc9d510acc736a4ed203036e9b27a7188107d863 Mon Sep 17 00:00:00 2001 From: beardthelion <56458543+beardthelion@users.noreply.github.com> Date: Sat, 13 Jun 2026 20:42:36 -0500 Subject: [PATCH 6/6] test(agent-routing): consolidate shouldEnforceModelAllowlist import Move the import to the top import block instead of mid-file. --- src/services/api/agentRouting.test.ts | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/services/api/agentRouting.test.ts b/src/services/api/agentRouting.test.ts index 0f76e7f690..a29587e23c 100644 --- a/src/services/api/agentRouting.test.ts +++ b/src/services/api/agentRouting.test.ts @@ -7,6 +7,7 @@ import { resolveAgentRunModelRouting, resolveOutOfProcessTeammateProvider, resolveOutOfProcessTeammateProviderFromCliArgs, + shouldEnforceModelAllowlist, } from './agentRouting.js' import type { SettingsJson } from '../../utils/settings/types.js' @@ -577,8 +578,6 @@ describe('applyAgentProviderOverrideToEnv', () => { }) }) -import { shouldEnforceModelAllowlist } from './agentRouting.js' - describe('shouldEnforceModelAllowlist', () => { test('enforces when a provider override is present', () => { expect(shouldEnforceModelAllowlist('m', 'm', true)).toBe(true)