Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* v0.28: Unified model configuration.
*
* One resolver replaces every hardcoded `claude-*-X` string + every per-phase
* `dream.<phase>.model` config key. Hierarchy (highest precedence first):
*
* 1. CLI flag (--model)
* 2. New-key config (e.g. models.dream.synthesize)
* 3. Old-key config (deprecated dream.synthesize.model, dream.patterns.model)
* — read with stderr deprecation warning, one-per-process
* 4. Global default (models.default)
* 5. Env var (process.env[envVar] or GBRAIN_MODEL)
* 6. Hardcoded fallback (caller-supplied)
*
* Aliases (`opus`, `sonnet`, `haiku`, `gemini`, `gpt`) resolve at the end so any
* tier can use a short name. Unknown alias passes through unchanged so users can
* pass full provider IDs without registering aliases.
*
* Per Codex P1 #11: deprecated keys are honored but stderr-warn once per process
* AND lose to new-key config when both are set.
*/
import type { ConfigReader } from './config-snapshot.ts';
import { openrouterModelSupportsSubagentLoop } from './ai/openrouter-families.ts';
import { splitProviderModelId } from './model-id.ts';
import type { GBrainConfig } from './config.ts';
import { loadConfig } from './config.ts';
import { mergedProviderEnv } from './ai/provider-env.ts';
import { RECIPES } from './ai/recipes/index.ts';
import { latestOpenAITiers, rankOpenAIChatModels } from './ai/openai-latest.ts';
export type ModelTier = 'utility' | 'reasoning' | 'deep' | 'subagent';
export interface ResolveModelOpts {
/** CLI flag value (e.g. `--model opus` → 'opus'). Highest precedence. */
cliFlag?: string;
/** New-key config name (e.g. 'models.dream.synthesize'). */
configKey?: string;
/** Deprecated old-key config name (e.g. 'dream.synthesize.model'). */
deprecatedConfigKey?: string;
/** Env var to consult after global default. Defaults to `GBRAIN_MODEL`. */
envVar?: string;
/**
* Tier classification (v0.31.12). Looked up after the per-feature config
* keys and BEFORE `models.default` (#3873 — tier-specific beats generic),
* then before the env var. Routing groups: `utility` (haiku-class,
* classification + expansion + verdict), `reasoning` (sonnet-class,
* default chat + synthesis + fact extraction), `deep` (opus-class,
* expensive reasoning), `subagent` (Anthropic-only multi-turn tool loop —
* never inherits a non-Anthropic `models.default`; falls back to
* TIER_DEFAULTS.subagent with a one-shot stderr warn instead).
*/
tier?: ModelTier;
/** Hardcoded last-resort fallback. */
fallback: string;
}
/** Default aliases shipped in code. Users override via `models.aliases.<name>` config.
* Values include the `provider:` prefix so resolved model strings always
* carry an explicit provider — required by the v0.40.8+ subagent queue's
* classifyCapabilities() validation. Bare model ids (e.g. `claude-opus-4-7`)
* cause `resolveRecipe()` to throw "unknown provider" and the queue rejects
* the submit. */
export const DEFAULT_ALIASES: Record<string, string> = {
opus: 'anthropic:claude-opus-4-7',
sonnet: 'anthropic:claude-sonnet-4-6',
haiku: 'anthropic:claude-haiku-4-5-20251001',
// `gemini` repointed (#2507): `gemini-3-pro` only ever existed as a preview
// id (`gemini-3-pro-preview`) and was shut down — it was never chat-listed
// in the google recipe nor priced. 2.5-flash is the recipe's chat models[0];
// there is NO GA pro-class Gemini chat target today, so the alias
// deliberately sits a capability class below the opus convention until
// Google ships a GA pro. Guarded by test/default-alias-liveness.test.ts.
gemini: 'google:gemini-2.5-flash',
// `gpt` resolves DYNAMICALLY in resolveAlias (account-discovered OpenAI
// flagship, recipe-ranked static floor) — this entry keeps the alias
// enumerable but the value here is only the documentation floor; a pinned
// id would 404 within months (the previous 'openai:gpt-5' already did).
gpt: 'openai:gpt-5.6',
};
/**
* Default model for each tier. Used as the hardcoded fallback when no
* `models.tier.<tier>` config + no `models.default` is set. Subagent gets
* Sonnet (Anthropic Messages API tool-loop shape required); reasoning gets
* Sonnet (default workhorse); deep gets Opus 4.7 (expensive reasoning);
* utility gets Haiku (fast classification).
*
* Users override via `gbrain config set models.tier.<tier> <model>`.
*/
export const TIER_DEFAULTS: Record<ModelTier, string> = {
utility: 'anthropic:claude-haiku-4-5-20251001',
reasoning: 'anthropic:claude-sonnet-4-6',
deep: 'anthropic:claude-opus-4-7',
subagent: 'anthropic:claude-sonnet-4-6',
};
/**
* OpenAI static tier fallback — NO literal model pins. Derived from the
* openai recipe's chat list through the SAME ranking grammar latest-model
* discovery uses (openai-latest.ts), so there is exactly one place a human
* updates OpenAI entry points (the recipe) and one function that classifies
* them. The RUNTIME default overlays this with the account-discovered cache
* in resolveTierDefault below. Computed lazily + memoized: recipes are static
* data, so this is pure.
*/
let _openaiStaticTiers: Record<ModelTier, string> | null = null;
export function openaiStaticTierFallback(): Record<ModelTier, string> {
if (!_openaiStaticTiers) {
const recipeModels = RECIPES.get('openai')?.touchpoints.chat?.models ?? [];
const ranked = rankOpenAIChatModels(recipeModels, () => true).tiers;
// A recipe list that defeats its own grammar would be a build bug; the
// Anthropic tier defaults are the never-null floor.
_openaiStaticTiers = ranked ?? { ...TIER_DEFAULTS };
}
return _openaiStaticTiers;
}
/**
* Key-aware tier defaults. The FIRST entry whose env key is present (merged
* env: config-file keys folded, env wins, empty strings dropped) supplies the
* tier default. Anthropic first preserves today's behavior byte-for-byte on
* every keyed install; OpenAI second makes an OPENAI_API_KEY-only install
* actually work (fact extraction, expansion, synthesis) instead of routing
* every default to a provider whose key is absent. No key at all →
* TIER_DEFAULTS unchanged (keyless installs degrade honestly downstream).
*
* OpenAI tiers are RESOLVED PER CALL, never pinned: the account-discovered
* latest (openai-latest.ts cache, refreshed before the first OpenAI-routed gateway call, #6607) wins, the
* recipe-derived static ranking is the offline floor. The subagent tier runs
* without prompt caching on OpenAI → enforceSubagentCapable emits the
* degraded:no_caching cost warn.
*
* Adding a provider here needs a curated per-tier model choice — see the
* TODOS.md follow-up before extending.
*/
/** Account-discovered latest for a tier, else the recipe-ranked static floor. */
function discoveredOrStaticOpenAITier(tier: ModelTier): string {
const discovered = latestOpenAITiers(tier);
return typeof discovered === 'string' ? discovered : openaiStaticTierFallback()[tier];
}
export const PROVIDER_TIER_DEFAULTS: ReadonlyArray<{
provider: 'anthropic' | 'openai';
envKey: string;
tiers: (tier: ModelTier) => string;
}> = [
{ provider: 'anthropic', envKey: 'ANTHROPIC_API_KEY', tiers: (tier) => TIER_DEFAULTS[tier] },
{ provider: 'openai', envKey: 'OPENAI_API_KEY', tiers: discoveredOrStaticOpenAITier },
];
/** loadConfig, throw-safe (the hasAnthropicKey pattern): unreadable config = env-only. */
function throwSafeLoadConfig(): GBrainConfig | null {
try {
return loadConfig();
} catch {
return null;
}
}
/** Drop ''/undefined entries (#1249) from an injected env. */
function realEnv(env: Record<string, string | undefined>): Record<string, string> {
return Object.fromEntries(
Object.entries(env).filter(([, v]) => v !== undefined && v !== ''),
) as Record<string, string>;
}
/**
* Explicit tier→file-plane pin key map (utility→expansion_model, everything
* else→chat_model): an unmapped future caller mislabeling the warn would be a
* silent doc bug with a ternary.
*/
const PIN_KEY_BY_TIER: Record<ModelTier, 'expansion_model' | 'chat_model'> = {
utility: 'expansion_model', reasoning: 'chat_model', deep: 'chat_model', subagent: 'chat_model',
};
/**
* Resolve the default model for a tier, honoring which provider keys are
* actually present. When `env` is passed it is used EXCLUSIVELY (no config
* read — hermetic for tests and pre-merged callers); when omitted, the merged
* env is computed from the file-plane config + process.env, and a SERVABLE
* file-plane pin for the tier is consulted below the key walk (#3813).
*/
export function resolveTierDefault(
tier: ModelTier,
env?: Record<string, string | undefined>,
): string {
const fileCfg = env ? null : throwSafeLoadConfig();
const merged = env ? realEnv(env) : mergedProviderEnv(fileCfg, process.env);
for (const entry of PROVIDER_TIER_DEFAULTS) {
if (merged[entry.envKey]) return entry.tiers(tier);
}
// #3813: no anthropic/openai key. PROVIDER_TIER_DEFAULTS knows only those
// two, so a single-provider install (deepseek, openrouter, together, ...)
// used to land on the Anthropic floor and every bare-default caller
// (extract_atoms, facts classify, page-summary, ...) called a provider with
// no key. A servable pin for this tier beats the floor. Sits BELOW the key
// walk so keyed installs route byte-for-byte as before.
const rawPin = fileCfg?.[PIN_KEY_BY_TIER[tier]]?.trim();
const pin = rawPin ? (DEFAULT_ALIASES[rawPin] ?? rawPin) : undefined;
if (pin && providerKeyReady(pin, merged)) return pin;
return TIER_DEFAULTS[tier];
}
/**
* True when `model`'s provider can serve CHAT and has every required auth
* env var present in `env` (per its recipe's auth_env.required). Bare model
* ids (no provider prefix) and unknown providers return false — an
* unverifiable pin is not a servable pin. A keyed but chat-less recipe
* (e.g. an embedding-only provider pinned as chat_model) is also not ready:
* every caller of this function resolves a chat-shaped tier, and honoring
* such a pin would install a model `isAvailable('chat')` rejects instead of
* falling back to the key-aware default. Recipes with no required keys
* (e.g. local Ollama) are always ready.
*/
export function providerKeyReady(model: string, env: Record<string, string>): boolean {
const { provider } = splitProviderModelId(model);
if (!provider) return false;
const recipe = RECIPES.get(provider.trim().toLowerCase());
if (!recipe) return false;
if (!recipe.touchpoints?.chat) return false;
const required = recipe.auth_env?.required ?? [];
if (required.length === 0) return true;
return required.every((k) => !!env[k]);
}
const _unservablePinWarningsEmitted = new Set<string>();
export type EffectiveModelSource = 'env_model' | 'file_pin' | 'tier_default';
/**
* Engine-free effective-model resolution for a chat-shaped tier. ONE shared
* function — `reconfigureGatewayWithEngine`'s fallback layer and
* `detectCapabilities`' extraction probe both call it, so runtime routing and
* the capability report cannot diverge by construction.
*
* Reads the RAW file-plane config — never gateway state, which stamps
* defaults at boot and makes an explicit pin indistinguishable from a
* fabricated one. Precedence: GBRAIN_MODEL env > servable file pin (its
* provider's keys are present) > key-aware tier default. An unservable pin
* (init-era pin whose key is gone, or a provider switch) falls through with
* one stderr warn per (pin, process) — availability-aware, never a hard fail.
*/
function resolveEffectiveModelForTier(
tier: ModelTier,
pin: string | undefined,
fileCfg: GBrainConfig | null,
env: Record<string, string | undefined>,
): { model: string; source: EffectiveModelSource } {
const merged = mergedProviderEnv(fileCfg, env);
const envModel = merged.GBRAIN_MODEL?.trim();
if (envModel) {
// Same `gpt` discovery routing as the pin branch below and
// resolveAlias — GBRAIN_MODEL=gpt must not resolve differently
// depending on which resolver ran.
const model = envModel === 'gpt'
? discoveredOrStaticOpenAITier('deep')
: DEFAULT_ALIASES[envModel] ?? envModel;
return { model, source: 'env_model' };
}
const rawPin = pin?.trim();
if (rawPin) {
// A bare `gpt` alias pin resolves through the same discovery path as
// resolveAlias('gpt') — the DEFAULT_ALIASES entry is only the
// documentation floor and would silently bypass the account-discovered
// flagship.
const fullPin = rawPin === 'gpt'
? discoveredOrStaticOpenAITier('deep')
: DEFAULT_ALIASES[rawPin] ?? rawPin;
if (providerKeyReady(fullPin, merged)) return { model: fullPin, source: 'file_pin' };
if (!_unservablePinWarningsEmitted.has(fullPin)) {
_unservablePinWarningsEmitted.add(fullPin);
// A prefix-less pin is a DIFFERENT problem than a missing key — saying
// "no usable provider key" for `chat_model: "claude-sonnet-4-6"` sends
// the user hunting for a key problem they may not have.
const diagnosis = splitProviderModelId(fullPin).provider === null
? `has no provider prefix, so its key can't be verified — prefix it (e.g. "anthropic:${fullPin}")`
: `has no usable provider key — set the provider's API key, update the pin`;
process.stderr.write(
`[models] configured ${PIN_KEY_BY_TIER[tier]} "${fullPin}" ${diagnosis}, ` +
`or remove it from ~/.gbrain/config.json. Falling back to the key-aware default.\n`,
);
}
}
return { model: resolveTierDefault(tier, merged), source: 'tier_default' };
}
/** Effective chat model (reasoning tier) from raw file config + env. */
export function resolveEffectiveChatModel(
fileCfg: GBrainConfig | null,
env: Record<string, string | undefined> = process.env,
): { model: string; source: EffectiveModelSource } {
return resolveEffectiveModelForTier('reasoning', fileCfg?.chat_model, fileCfg, env);
}
/** Effective expansion model (utility tier) from raw file config + env. */
export function resolveEffectiveExpansionModel(
fileCfg: GBrainConfig | null,
env: Record<string, string | undefined> = process.env,
): { model: string; source: EffectiveModelSource } {
return resolveEffectiveModelForTier('utility', fileCfg?.expansion_model, fileCfg, env);
}
/**
* v0.31.12 subagent runtime enforcement (layer 2).
*
* Returns true if a resolved `provider:model` (or bare model id) points at
* an Anthropic-shape API. The subagent loop in
* `src/core/minions/handlers/subagent.ts` makes Anthropic Messages API calls
* with prompt caching on system + tools; routing it elsewhere silently
* breaks. When `tier === 'subagent'` resolves to a non-Anthropic provider,
* we log a stderr warn AND fall back to `TIER_DEFAULTS.subagent`.
*/
export function isAnthropicProvider(modelString: string): boolean {
if (!modelString) return false;
// v0.41.21.0: route through splitProviderModelId so slash form
// (`anthropic/claude-sonnet-4-6`) also classifies as Anthropic.
// Pre-fix the inline `:`-only split silently returned false for slash
// form → subagent guard bypass → silent fallback to TIER_DEFAULTS.
const { provider, model } = splitProviderModelId(modelString);
if (provider !== null) {
return provider.trim().toLowerCase() === 'anthropic';
}
// Bare model id (no separator): known Anthropic models start with `claude-`.
// Conservative: we'd rather warn-on-Anthropic-typo than silently route
// gpt-5 to the subagent loop.
return model.toLowerCase().startsWith('claude-');
}
/**
* OpenRouter Anthropic routes (`openrouter:anthropic/…`). These are NOT
* native Anthropic (`isAnthropicProvider` stays false — the Messages SDK
* cannot speak OR). The legacy `!useGatewayLoop && !isAnthropicProvider`
* pin treats them as an exception and auto-routes through gateway.toolLoop().
*/
export function isOpenRouterAnthropic(modelString: string): boolean {
if (!modelString) return false;
const { provider, model } = splitProviderModelId(modelString);
return provider?.trim().toLowerCase() === 'openrouter'
&& model.toLowerCase().startsWith('anthropic/');
}
/**
* `openrouter:<family>/…` where the family has a live abort/retry pin for the
* subagent loop (anthropic/, deepseek/ — see src/core/ai/openrouter-families.ts).
* The subagent handler auto-enables the gateway loop for these, because the
* legacy Anthropic-direct pin would otherwise refuse them when
* `agent.use_gateway_loop` is off.
*/
export function isOpenRouterSubagentFamily(modelString: string): boolean {
if (!modelString) return false;
const { provider, model } = splitProviderModelId(modelString);
return provider?.trim().toLowerCase() === 'openrouter' && openrouterModelSupportsSubagentLoop(model);
}
const _subagentTierWarningsEmitted = new Set<string>();
// Module-level set of deprecated config keys we've already warned about.
// Reset on process restart; one warning per (key, process) per Codex P1 #11.
const _deprecationWarningsEmitted = new Set<string>();
function emitDeprecationWarning(oldKey: string, newKey: string, ignored: boolean): void {
if (_deprecationWarningsEmitted.has(oldKey)) return;
_deprecationWarningsEmitted.add(oldKey);
if (ignored) {
process.stderr.write(
`[models] deprecated config "${oldKey}" ignored; "${newKey}" is set and wins. ` +
`Remove "${oldKey}" from your config in v0.30.\n`,
);
} else {
process.stderr.write(
`[models] deprecated config "${oldKey}" honored; rename to "${newKey}" before v0.30.\n`,
);
}
}
/**
* #4575 — the config-key precedence the subagent tier resolves through at
* runtime (`resolveModelDetailed` with configKey 'models.subagent' + tier
* 'subagent': steps 2 → 4 → 5 below). Doctor's `subagent_capability` check
* iterates THIS list so the check and the runtime cannot drift again —
* #3873 hoisted `models.tier.<tier>` above `models.default` in the runtime
* and the check kept the pre-fix order, producing an unclearable false
* positive whose own suggested fix (set models.tier.subagent) was the key
* the check read last.
*/
export const SUBAGENT_CONFIG_KEY_PRECEDENCE = [
'models.subagent',
'models.tier.subagent',
'models.default',
] as const;
/** Which step of the resolution chain produced the model. */
export type ResolveSource =
| 'cli_flag'
| 'config_key'
| 'deprecated_key'
| 'models_default'
| 'tier_config'
| 'env'
| 'tier_default'
| 'fallback';
/**
* A resolved model plus the chain step that produced it. When the subagent
* capability gate replaced the configured model, `substituted_from` is what
* was configured and `substitution_reason` says why (`no_tools`,
* `no_subagent_loop`, `unknown_provider`).
*/
export interface ResolvedModel {
model: string;
source: ResolveSource;
substituted_from?: string;
substitution_reason?: SubagentSubstitutionReason;
}
export type SubagentSubstitutionReason = 'no_tools' | 'no_subagent_loop' | 'unknown_provider';
/**
* Human-facing origin of a resolution step: the flag, config key or env var
* that supplied the model (`models.tier.deep`, `models.default`,
* `GBRAIN_MODEL`), or `built-in default`. Key names only, never values.
*/
export function describeResolveOrigin(
source: ResolveSource,
opts: Pick<ResolveModelOpts, 'configKey' | 'deprecatedConfigKey' | 'envVar' | 'tier'> & { flag?: string },
): string {
switch (source) {
case 'cli_flag': return opts.flag ?? 'flag';
case 'config_key': return opts.configKey ?? 'config';
case 'deprecated_key': return opts.deprecatedConfigKey ?? 'config';
case 'tier_config': return `models.tier.${opts.tier}`;
case 'models_default': return 'models.default';
case 'env': return opts.envVar ?? 'GBRAIN_MODEL';
case 'tier_default':
case 'fallback': return 'built-in default';
}
}
/**
* Resolve a model name through the precedence chain, reporting WHICH step
* produced it. Async because it reads config from the engine. Pass
* `engine: null` for callsites that don't have an engine (rare; usually CLI
* bootstrap before connect). Step 7 (tier default) is key-aware: it routes
* through `resolveTierDefault`, so an install whose only key is
* OPENAI_API_KEY resolves tier defaults to OpenAI models instead of an
* unservable Anthropic default.
*/
export async function resolveModelDetailed(
engine: ConfigReader | null,
opts: ResolveModelOpts,
): Promise<ResolvedModel> {
const envVar = opts.envVar ?? 'GBRAIN_MODEL';
// 1. CLI flag wins
if (opts.cliFlag && opts.cliFlag.trim()) {
return { model: await resolveAlias(engine, opts.cliFlag.trim()), source: 'cli_flag' };
}
if (engine) {
// 2. New-key config
if (opts.configKey) {
const v = await engine.getConfig(opts.configKey);
if (v && v.trim()) {
// If a deprecated key is also set, warn that it's being ignored.
if (opts.deprecatedConfigKey) {
const old = await engine.getConfig(opts.deprecatedConfigKey);
if (old && old.trim()) {
emitDeprecationWarning(opts.deprecatedConfigKey, opts.configKey, /*ignored=*/ true);
}
}
return { model: await resolveAlias(engine, v.trim()), source: 'config_key' };
}
}
// 3. Old-key (deprecated) config
if (opts.deprecatedConfigKey) {
const v = await engine.getConfig(opts.deprecatedConfigKey);
if (v && v.trim()) {
emitDeprecationWarning(opts.deprecatedConfigKey, opts.configKey ?? '<no replacement>', /*ignored=*/ false);
return { model: await resolveAlias(engine, v.trim()), source: 'deprecated_key' };
}
}
// 4. Tier override (v0.31.12; hoisted above models.default by #3873).
// `models.tier.<tier>` is strictly more specific than the generic
// `models.default`, so it must win — pre-fix, setting a cheap utility
// tier was silently ignored on any brain that also set models.default.
if (opts.tier) {
const tierVal = await engine.getConfig(`models.tier.${opts.tier}`);
if (tierVal && tierVal.trim()) {
const resolved = await resolveAlias(engine, tierVal.trim());
return withSubagentGate(resolved, opts.tier, `models.tier.${opts.tier}`, 'tier_config');
}
}
// 5. Global default
const def = await engine.getConfig('models.default');
if (def && def.trim()) {
const resolved = await resolveAlias(engine, def.trim());
return withSubagentGate(resolved, opts.tier, 'models.default', 'models_default');
}
}
// 6. Env var
const env = process.env[envVar];
if (env && env.trim()) {
const resolved = await resolveAlias(engine, env.trim());
return withSubagentGate(resolved, opts.tier, `env:${envVar}`, 'env');
}
// 7. Key-aware tier default — when no override beats us, the tier's
// canonical model for the first env-ready provider wins over the
// caller-supplied fallback.
if (opts.tier && TIER_DEFAULTS[opts.tier]) {
const resolved = await resolveAlias(engine, resolveTierDefault(opts.tier));
return withSubagentGate(resolved, opts.tier, 'tier-default', 'tier_default');
}
// 8. Hardcoded fallback (caller-supplied)
return { model: await resolveAlias(engine, opts.fallback), source: 'fallback' };
}
/**
* Resolve a model name through the precedence chain. Thin wrapper over
* `resolveModelDetailed` for the ~30 callers that don't care which step won.
*/
export async function resolveModel(
engine: ConfigReader | null,
opts: ResolveModelOpts,
): Promise<string> {
return (await resolveModelDetailed(engine, opts)).model;
}
/**
* v0.31.12 subagent runtime enforcement (layer 2): if `tier === 'subagent'`
* resolved to a non-Anthropic model, warn once per (source, model) and fall
* back to `TIER_DEFAULTS.subagent`. Source is the resolution-chain step that
* produced the bad value (`models.default`, `models.tier.subagent`, etc.) so
* the user sees where to fix it.
*
* Returns the resolved value unchanged for non-subagent tiers or when the
* resolved value is already Anthropic.
*/
/**
* v0.38 (D7) — replaces the legacy `enforceSubagentAnthropic` with a
* capability-based gate. The check now asks "can this model run a subagent
* tool loop?" via the recipe-driven capability classifier instead of "is
* this Anthropic?". Result:
*
* - `unusable:no_tools` → fall back to TIER_DEFAULTS.subagent + warn (the
* loop literally cannot dispatch tools, so the resolved model is wrong)
* - `unusable:no_subagent_loop` → fall back to TIER_DEFAULTS.subagent + warn
* (the recipe declares tool_call_ids unstable across crash/replay, so the
* loop can't reconcile — same refusal class as no_tools)
* - `unknown` → fall back to TIER_DEFAULTS.subagent + warn (unknown provider
* — defensive: don't burn money on a model we can't verify supports tools)
* - `degraded:no_caching` → return resolved; warn once per (source, model)
* about cost regression
* - `degraded:no_parallel` → return resolved; info-log
* - `ok` → return resolved unchanged
*
* Once-per-(source, model) warn seam preserved from v0.31.12 (same Set, same
* suppression key) so doctor + first-call surfaces don't double-warn.
*/
function enforceSubagentCapable(resolved: string, tier: ModelTier | undefined, source: string): string {
return subagentGate(resolved, tier, source).model;
}
function withSubagentGate(resolved: string, tier: ModelTier | undefined, sourceLabel: string, source: ResolveSource): ResolvedModel {
const gate = subagentGate(resolved, tier, sourceLabel);
return gate.reason
? { model: gate.model, source, substituted_from: resolved, substitution_reason: gate.reason }
: { model: gate.model, source };
}
function subagentGate(
resolved: string,
tier: ModelTier | undefined,
source: string,
): { model: string; reason?: SubagentSubstitutionReason } {
if (tier !== 'subagent') return { model: resolved };
// Lazy import keeps capabilities.ts out of model-config's eager-load surface
// (capabilities → model-resolver → recipes; this would create a cycle if
// model-config itself were imported by recipes, which it isn't, but
// defensive against future drift).
let verdict: 'ok' | 'degraded:no_caching' | 'degraded:no_parallel' | 'unusable:no_tools' | 'unusable:no_subagent_loop' | 'unknown';
try {
// Synchronous-style import via require shim isn't available in ESM; the
// helper is pure, so a synchronous static import is fine here. Pulling
// from capabilities.ts directly:
// eslint-disable-next-line @typescript-eslint/no-require-imports
const cap = require('./ai/capabilities.ts') as typeof import('./ai/capabilities.ts');
verdict = cap.classifyCapabilities(resolved);
} catch {
// If the import fails (e.g. malformed recipe registry during boot), be
// permissive and just return the resolved model — surface the underlying
// issue at gateway call time.
return { model: resolved };
}
const key = `${source}:${resolved}`;
if (verdict === 'unusable:no_tools' || verdict === 'unusable:no_subagent_loop' || verdict === 'unknown') {
const reason: SubagentSubstitutionReason = verdict === 'unusable:no_tools'
? 'no_tools'
: verdict === 'unusable:no_subagent_loop' ? 'no_subagent_loop' : 'unknown_provider';
if (!_subagentTierWarningsEmitted.has(key)) {
_subagentTierWarningsEmitted.add(key);
const prose = reason === 'no_tools'
? `lacks tool-calling support`
: reason === 'no_subagent_loop'
? `declares the subagent loop unsupported (supports_subagent_loop: false)`
: `is an unrecognized provider`;
process.stderr.write(
`[models] tier.subagent resolved to "${resolved}" via "${source}", which ${prose}. ` +
`The subagent tool loop cannot run on this model — falling back to ${TIER_DEFAULTS.subagent}. ` +
`Fix: gbrain config set models.tier.subagent <provider>:<model> ` +
`(the provider's recipe must declare supports_subagent_loop: true)\n`,
);
}
return { model: TIER_DEFAULTS.subagent, reason };
}
if (verdict === 'degraded:no_caching') {
if (!_subagentTierWarningsEmitted.has(key)) {
_subagentTierWarningsEmitted.add(key);
process.stderr.write(
`[models] tier.subagent resolved to "${resolved}" via "${source}" — provider does not support prompt caching. ` +
`The loop will run hot (cost scales linearly with conversation length). ` +
`For lower cost on long loops, set models.tier.subagent to an Anthropic model.\n`,
);
}
}
// degraded:no_parallel and ok return resolved unchanged (no warn).
return { model: resolved };
}
/**
* @deprecated v0.38 — renamed to `enforceSubagentCapable`. The old name and
* Anthropic-only semantics are preserved as a thin wrapper for any external
* callers (extensions, plugins) that imported it. New code MUST call
* `enforceSubagentCapable` instead.
*/
function enforceSubagentAnthropic(resolved: string, tier: ModelTier | undefined, source: string): string {
return enforceSubagentCapable(resolved, tier, source);
}
// Keep `enforceSubagentAnthropic` available for back-compat consumers that
// imported it. Marked unused-but-needed so the linter doesn't flag it.
void enforceSubagentAnthropic;
/**
* Resolve a name (possibly an alias) to its full provider model id. Order:
* 1. User-defined alias via `models.aliases.<name>` config
* 2. DEFAULT_ALIASES map
* 3. Pass-through (treat as already-full model id)
*
* Cycles in user-defined aliases are broken at depth 2 — if `opus` aliases
* to `super-opus` which aliases to `opus`, we return `super-opus` and stop.
*/
export async function resolveAlias(
engine: ConfigReader | null,
name: string,
depth = 0,
): Promise<string> {
if (depth > 2) return name; // cycle break
if (engine) {
const userAlias = await engine.getConfig(`models.aliases.${name}`);
if (userAlias && userAlias.trim() && userAlias.trim() !== name) {
return await resolveAlias(engine, userAlias.trim(), depth + 1);
}
}
if (name in DEFAULT_ALIASES) {
// `gpt` tracks the CURRENT OpenAI flagship (discovered from the account,
// recipe-ranked static floor) instead of a pinned id that goes stale.
const next = name === 'gpt' ? discoveredOrStaticOpenAITier('deep') : DEFAULT_ALIASES[name];
if (next && next !== name) return await resolveAlias(engine, next, depth + 1);
}
return name;
}
/** Test-only helper: clear the deprecation-warning memo so tests re-emit. */
export function _resetDeprecationWarningsForTest(): void {
_deprecationWarningsEmitted.clear();
_subagentTierWarningsEmitted.clear();
_unservablePinWarningsEmitted.clear();
}