Skip to content
15 changes: 15 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
100 changes: 99 additions & 1 deletion src/services/api/agentRouting.test.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import { describe, expect, test } from 'bun:test'
import { afterEach, beforeEach, describe, expect, spyOn, test } from 'bun:test'
import {
applyAgentProviderOverrideToEnv,
isProviderOverride,
resolveAgentModelProvider,
resolveAgentProvider,
resolveAgentRunModelRouting,
Expand All @@ -23,6 +24,14 @@ const baseSettings = {
} as unknown as SettingsJson

describe('resolveAgentProvider', () => {
let errorSpy: ReturnType<typeof spyOn>
beforeEach(() => {
errorSpy = spyOn(console, 'error').mockImplementation(() => {})
})
afterEach(() => {
errorSpy.mockRestore()
})

// ── Priority chain ──────────────────────────────────────────

test('name takes priority over subagentType', () => {
Expand Down Expand Up @@ -164,10 +173,74 @@ 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.',
)
})

})

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', () => {
let errorSpy: ReturnType<typeof spyOn>
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' })
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()
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.',
)
})
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

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()
Expand Down Expand Up @@ -217,6 +290,14 @@ describe('resolveAgentModelProvider', () => {
})

describe('resolveAgentRunModelRouting', () => {
let errorSpy: ReturnType<typeof spyOn>
beforeEach(() => {
errorSpy = spyOn(console, 'error').mockImplementation(() => {})
})
afterEach(() => {
errorSpy.mockRestore()
})

test('explicit configured model wins over agentRouting', () => {
const result = resolveAgentRunModelRouting({
resolvedAgentModel: 'parent-model',
Expand Down Expand Up @@ -306,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.',
)
})
})

Expand Down Expand Up @@ -492,3 +576,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)
})
})
85 changes: 60 additions & 25 deletions src/services/api/agentRouting.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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()

// Model-only route: no credentials → reuse the active provider, swap the model.
if (!baseURL && !apiKey) return { model }

return {
model: modelConfig.model?.trim() || configuredModelKey,
baseURL: modelConfig.base_url,
apiKey,
// 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 }
}

/**
Expand All @@ -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
Expand Down Expand Up @@ -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({
Expand All @@ -150,21 +169,36 @@ 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 }
}

/**
* 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
}

/**
Expand All @@ -189,13 +223,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(
Expand Down
11 changes: 9 additions & 2 deletions src/tools/AgentTool/runAgent.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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.`,
)
Expand Down
35 changes: 35 additions & 0 deletions src/utils/settings/agentModelsSchema.test.ts
Original file line number Diff line number Diff line change
@@ -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)
})
Loading