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. diff --git a/src/services/api/agentRouting.test.ts b/src/services/api/agentRouting.test.ts index 0c59146739..a29587e23c 100644 --- a/src/services/api/agentRouting.test.ts +++ b/src/services/api/agentRouting.test.ts @@ -1,11 +1,13 @@ -import { describe, expect, test } from 'bun:test' +import { afterEach, beforeEach, describe, expect, spyOn, test } from 'bun:test' import { applyAgentProviderOverrideToEnv, + isProviderOverride, resolveAgentModelProvider, resolveAgentProvider, resolveAgentRunModelRouting, resolveOutOfProcessTeammateProvider, resolveOutOfProcessTeammateProviderFromCliArgs, + shouldEnforceModelAllowlist, } from './agentRouting.js' import type { SettingsJson } from '../../utils/settings/types.js' @@ -23,6 +25,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', () => { @@ -164,8 +174,72 @@ 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 + 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.', + ) + }) + + 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', () => { @@ -217,6 +291,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', @@ -306,6 +388,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.', + ) }) }) @@ -492,3 +577,15 @@ describe('applyAgentProviderOverrideToEnv', () => { expect(env.ANTHROPIC_API_KEY).toBe('anthropic-key') }) }) + +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 9d9b6f0d09..b438c609da 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() + + // 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 } } /** @@ -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,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 } /** @@ -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( 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.`, ) 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