fix(#3229): shared model catalog source of truth for agent profiles + runtime tier defaults (#3230)

* docs(adr): add ADR-0003 model catalog module

* fix(#3229): add shared model catalog as source of truth for agent profiles and runtime tier defaults

Research / design (ADR-0003):
- Existing drift came from 4 independent model truths:
  1. CJS model-profiles.cjs
  2. SDK config-query.ts stale copy (18 agents)
  3. settings-advanced.md runtime tier table
  4. session-runner Claude-only profile map
- New design: one machine-readable Model Catalog Module in sdk/shared/
  that both packages ship and consume.

Implementation:
- sdk/shared/model-catalog.json — canonical source of truth for:
  - full 33-agent registry
  - per-agent golden (quality) alias + balanced/budget aliases
  - adaptive derivation from routingTier
  - agent→phaseType map
  - agent→dynamic-routing default tier map
  - runtime tier defaults for all supported runtimes
- get-shit-done/bin/lib/model-catalog.cjs — CJS adapter over the catalog
- sdk/src/model-catalog.ts — SDK adapter over the same catalog
- CJS model-profiles.cjs now re-exports derived data from model-catalog.cjs
- SDK config-query.ts now re-exports MODEL_PROFILES/VALID_PROFILES from
  model-catalog.ts instead of maintaining its own list
- sdk/src/query/helpers.ts runtime list now comes from the catalog (fixes hermes drift)
- sdk/src/session-runner.ts Claude profile→model-id mapping now resolves via catalog
- docs/CONFIGURATION.md + settings-advanced.md runtime tables updated to match catalog

Behavior changes:
- resolve-model now covers every shipped agent file on disk (33 agents)
- unknown-agent fallback is profile-semantic, not hardcoded sonnet:
  quality→opus, budget→haiku, balanced/adaptive→sonnet, inherit→inherit
- Group B runtimes remain known runtimes but do not get built-in tier defaults

Tests (RED→GREEN):
- root tests: shipped agent files must equal MODEL_PROFILES keys
- sdk tests: shipped agent files must equal MODEL_PROFILES keys
- direct fix assertion: gsd-code-reviewer resolves to opus under quality with no unknown_agent
- runtime defaults parity test: settings-advanced.md + CONFIGURATION.md tables must match catalog
- helper tests: hermes included in SUPPORTED_RUNTIMES and getRuntimeConfigDir()

Closes #3229

* chore(changeset): update #3229 changeset pr field to 3230

* fix(ci): update inherit fallback expectations and inventory parity for model catalog
This commit is contained in:
Tom Boucher
2026-05-08 21:25:37 -04:00
committed by GitHub
parent deeb6deb67
commit 96806003c5
23 changed files with 557 additions and 368 deletions

View File

@@ -7,6 +7,7 @@ const os = require('os');
const path = require('path');
const { execSync, execFileSync, spawnSync } = require('child_process');
const { MODEL_PROFILES, AGENT_TO_PHASE_TYPE, VALID_PHASE_TYPES, AGENT_DEFAULT_TIERS, VALID_AGENT_TIERS, nextTier } = require('./model-profiles.cjs');
const { MODEL_ALIAS_MAP, RUNTIME_PROFILE_MAP, KNOWN_RUNTIMES, RUNTIMES_WITH_REASONING_EFFORT } = require('./model-catalog.cjs');
// Compatibility shim: new imports should use planning-workspace.cjs directly.
const {
planningDir,
@@ -1301,102 +1302,9 @@ function checkAgentsInstalled() {
// ─── Model alias resolution ───────────────────────────────────────────────────
/**
* Map short model aliases to full model IDs.
* Updated each release to match current model versions.
* Users can override with model_overrides in config.json for custom/latest models.
*/
const MODEL_ALIAS_MAP = {
'opus': 'claude-opus-4-7',
'sonnet': 'claude-sonnet-4-6',
'haiku': 'claude-haiku-4-5',
};
/**
* #2517 — runtime-aware tier resolution.
* Maps `model_profile` tiers (opus/sonnet/haiku) to runtime-native model IDs and
* (where supported) reasoning_effort settings.
*
* Each entry: { model: <id>, reasoning_effort?: <level> }
*
* `claude` mirrors MODEL_ALIAS_MAP — present for symmetry so `runtime: "claude"`
* resolves through the same code path. `codex` defaults are taken from the spec
* in #2517. Unknown runtimes fall back to the Claude alias to avoid emitting
* provider-specific IDs the runtime cannot accept.
*/
const RUNTIME_PROFILE_MAP = {
claude: Object.fromEntries(
Object.entries(MODEL_ALIAS_MAP).map(([tier, model]) => [tier, { model }])
),
codex: {
opus: { model: 'gpt-5.4', reasoning_effort: 'xhigh' },
sonnet: { model: 'gpt-5.3-codex', reasoning_effort: 'medium' },
haiku: { model: 'gpt-5.4-mini', reasoning_effort: 'medium' },
},
gemini: {
opus: { model: 'gemini-3-pro' },
sonnet: { model: 'gemini-3-flash' },
haiku: { model: 'gemini-2.5-flash-lite' },
},
qwen: {
opus: { model: 'qwen3-max-2026-01-23' },
sonnet: { model: 'qwen3-coder-plus' },
haiku: { model: 'qwen3-coder-next' },
},
opencode: {
opus: { model: 'anthropic/claude-opus-4-7' },
sonnet: { model: 'anthropic/claude-sonnet-4-6' },
haiku: { model: 'anthropic/claude-haiku-4-5' },
},
copilot: {
opus: { model: 'claude-opus-4-7' },
sonnet: { model: 'claude-sonnet-4-6' },
haiku: { model: 'claude-haiku-4-5' },
},
hermes: {
// Hermes Agent is provider-agnostic; users pick any provider in ~/.hermes/config.yaml.
// Defaults use OpenRouter slugs because (a) OpenRouter is Hermes' default provider and
// (b) the same slugs resolve on OpenRouter, native Anthropic, and Copilot via Hermes'
// aggregator-aware resolver. Users on a different provider override per-tier via
// model_profile_overrides.hermes.{opus,sonnet,haiku} in .planning/config.json.
opus: { model: 'anthropic/claude-opus-4-7' },
sonnet: { model: 'anthropic/claude-sonnet-4-6' },
haiku: { model: 'anthropic/claude-haiku-4-5' },
},
};
const RUNTIMES_WITH_REASONING_EFFORT = new Set(['codex']);
/**
* Tier enum allowed under `model_profile_overrides[runtime][tier]`. Mirrors the
* regex in `config-schema.cjs` (DYNAMIC_KEY_PATTERNS) so loadConfig surfaces the
* same constraint at read time, not only at config-set time (review finding #10).
*/
const RUNTIME_OVERRIDE_TIERS = new Set(['opus', 'sonnet', 'haiku']);
/**
* Allowlist of runtime names the install pipeline currently knows how to emit
* native model IDs for. Synced with `getDirName` in `bin/install.js` and the
* runtime list in `docs/CONFIGURATION.md`. Free-string runtimes outside this
* set are still accepted (#2517 deliberately leaves the runtime field open) —
* a warning fires once at loadConfig so a typo like `runtime: "codx"` does not
* silently fall back to Claude defaults (review findings #10, #13).
*/
const KNOWN_RUNTIMES = new Set([
'claude', 'codex', 'opencode', 'kilo', 'gemini', 'qwen',
'copilot', 'cursor', 'windsurf', 'augment', 'trae', 'codebuddy',
'antigravity', 'cline', 'hermes',
]);
const _warnedConfigKeys = new Set();
/**
* Emit a one-time stderr warning for unknown runtime/tier keys in a parsed
* config blob. Idempotent across calls — the same (file, key) pair only warns
* once per process so loadConfig can be called repeatedly without spamming.
*
* Does NOT reject — preserves back-compat for users on a runtime not yet in the
* allowlist (the new-runtime case must always be possible without code changes).
*/
function _warnUnknownProfileOverrides(parsed, configLabel) {
if (!parsed || typeof parsed !== 'object') return;
@@ -1574,7 +1482,12 @@ function resolveModelInternal(cwd, agentType) {
}
// 5. Profile lookup (Claude-native default).
if (!agentModels) return 'sonnet';
if (!agentModels) {
return profile === 'quality' ? 'opus'
: profile === 'budget' ? 'haiku'
: profile === 'inherit' ? 'inherit'
: 'sonnet';
}
// Gate on tier (not profile) so a valid phase-type override beats
// profile=inherit (#3030 CR Major).
if (tier === 'inherit') return 'inherit';

View File

@@ -0,0 +1,92 @@
'use strict';
const path = require('node:path');
const catalog = require(path.join(__dirname, '..', '..', '..', 'sdk', 'shared', 'model-catalog.json'));
const VALID_PROFILES = [...catalog.profiles];
const VALID_PHASE_TYPES = new Set(catalog.phaseTypes);
const VALID_AGENT_TIERS = new Set(Object.keys(catalog.adaptiveTierMap));
const MODEL_PROFILES = Object.fromEntries(
Object.entries(catalog.agents).map(([agent, meta]) => [agent, {
quality: meta.golden,
balanced: meta.balanced,
budget: meta.budget,
adaptive: catalog.adaptiveTierMap[meta.routingTier],
}])
);
const AGENT_TO_PHASE_TYPE = Object.fromEntries(
Object.entries(catalog.agents).map(([agent, meta]) => [agent, meta.phaseType])
);
const AGENT_DEFAULT_TIERS = Object.fromEntries(
Object.entries(catalog.agents).map(([agent, meta]) => [agent, meta.routingTier])
);
const MODEL_ALIAS_MAP = Object.fromEntries(
Object.entries(catalog.runtimeTierDefaults.claude).map(([tier, entry]) => [tier, entry?.model])
);
const RUNTIME_PROFILE_MAP = Object.fromEntries(
Object.entries(catalog.runtimeTierDefaults)
.map(([runtime, tiers]) => [
runtime,
Object.fromEntries(
Object.entries(tiers).filter(([, entry]) => entry).map(([tier, entry]) => [tier, entry])
),
])
.filter(([, tiers]) => Object.keys(tiers).length > 0)
);
const KNOWN_RUNTIMES = new Set(Object.keys(catalog.runtimeTierDefaults));
const RUNTIMES_WITH_REASONING_EFFORT = new Set(
Object.entries(catalog.runtimeTierDefaults)
.filter(([, tiers]) => Object.values(tiers).some((entry) => entry && entry.reasoning_effort))
.map(([runtime]) => runtime)
);
function nextTier(currentTier) {
const order = ['light', 'standard', 'heavy'];
const idx = order.indexOf(String(currentTier));
if (idx === -1) return null;
return order[Math.min(idx + 1, order.length - 1)];
}
function formatAgentToModelMapAsTable(agentToModelMap) {
const agentWidth = Math.max('Agent'.length, ...Object.keys(agentToModelMap).map((a) => a.length));
const modelWidth = Math.max('Model'.length, ...Object.values(agentToModelMap).map((m) => m.length));
const sep = '─'.repeat(agentWidth + 2) + '┼' + '─'.repeat(modelWidth + 2);
const header = ` ${'Agent'.padEnd(agentWidth)} │ ${'Model'.padEnd(modelWidth)}`;
let out = `${header}\n${sep}\n`;
for (const [agent, model] of Object.entries(agentToModelMap)) {
out += ` ${agent.padEnd(agentWidth)} │ ${model.padEnd(modelWidth)}\n`;
}
return out;
}
function getAgentToModelMapForProfile(normalizedProfile) {
const profile = VALID_PROFILES.includes(normalizedProfile) ? normalizedProfile : 'balanced';
const out = {};
for (const [agent, profiles] of Object.entries(MODEL_PROFILES)) {
out[agent] = profile === 'inherit' ? 'inherit' : profiles[profile];
}
return out;
}
module.exports = {
catalog,
MODEL_PROFILES,
VALID_PROFILES,
AGENT_TO_PHASE_TYPE,
VALID_PHASE_TYPES,
AGENT_DEFAULT_TIERS,
VALID_AGENT_TIERS,
MODEL_ALIAS_MAP,
RUNTIME_PROFILE_MAP,
KNOWN_RUNTIMES,
RUNTIMES_WITH_REASONING_EFFORT,
nextTier,
formatAgentToModelMapAsTable,
getAgentToModelMapForProfile,
};

View File

@@ -1,184 +1,16 @@
/**
* Mapping of GSD agent to model for each profile.
*
* Should be in sync with the profiles table in `get-shit-done/references/model-profiles.md`. But
* possibly worth making this the single source of truth at some point, and removing the markdown
* reference table in favor of programmatically determining the model to use for an agent (which
* would be faster, use fewer tokens, and be less error-prone).
*/
const MODEL_PROFILES = {
'gsd-planner': { quality: 'opus', balanced: 'opus', budget: 'sonnet', adaptive: 'opus' },
'gsd-roadmapper': { quality: 'opus', balanced: 'sonnet', budget: 'sonnet', adaptive: 'sonnet' },
'gsd-executor': { quality: 'opus', balanced: 'sonnet', budget: 'sonnet', adaptive: 'sonnet' },
'gsd-phase-researcher': { quality: 'opus', balanced: 'sonnet', budget: 'haiku', adaptive: 'sonnet' },
'gsd-project-researcher': { quality: 'opus', balanced: 'sonnet', budget: 'haiku', adaptive: 'sonnet' },
'gsd-research-synthesizer': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku', adaptive: 'haiku' },
'gsd-debugger': { quality: 'opus', balanced: 'sonnet', budget: 'sonnet', adaptive: 'opus' },
'gsd-codebase-mapper': { quality: 'sonnet', balanced: 'haiku', budget: 'haiku', adaptive: 'haiku' },
'gsd-verifier': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku', adaptive: 'sonnet' },
'gsd-plan-checker': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku', adaptive: 'haiku' },
'gsd-integration-checker': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku', adaptive: 'haiku' },
'gsd-nyquist-auditor': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku', adaptive: 'haiku' },
'gsd-pattern-mapper': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku', adaptive: 'haiku' },
'gsd-ui-researcher': { quality: 'opus', balanced: 'sonnet', budget: 'haiku', adaptive: 'sonnet' },
'gsd-ui-checker': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku', adaptive: 'haiku' },
'gsd-ui-auditor': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku', adaptive: 'haiku' },
'gsd-doc-writer': { quality: 'opus', balanced: 'sonnet', budget: 'haiku', adaptive: 'sonnet' },
'gsd-doc-verifier': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku', adaptive: 'haiku' },
};
const VALID_PROFILES = [...Object.keys(MODEL_PROFILES['gsd-planner']), 'inherit'];
'use strict';
/**
* #3023 — Phase-type → agent mapping table.
*
* Lets users tune model selection at the *phase-type* level (planning,
* research, execution, verification, ...) instead of per-agent. Maps
* each agent in MODEL_PROFILES to exactly one phase-type so resolution
* is deterministic.
*
* Adding a new agent to MODEL_PROFILES requires adding an entry here too;
* tests/feat-3023-phase-type-models.test.cjs asserts coverage.
*
* Phase-type semantics:
* - planning: produces the plan (PLAN.md, ROADMAP.md, patterns)
* - discuss: collaborative scoping (no subagent today; reserved
* for orchestrators that may spawn one)
* - research: gathers external/codebase context (RESEARCH.md)
* - execution: implements the plan or writes user-facing artifacts
* - verification: checks correctness (VERIFICATION.md, audits)
* - completion: post-execution wrap-up (no subagent today; reserved)
*/
const AGENT_TO_PHASE_TYPE = {
// Planning — produces the plan / roadmap / pattern map
'gsd-planner': 'planning',
'gsd-roadmapper': 'planning',
'gsd-pattern-mapper': 'planning',
// Research — external/codebase information gathering
'gsd-phase-researcher': 'research',
'gsd-project-researcher': 'research',
'gsd-research-synthesizer': 'research',
'gsd-codebase-mapper': 'research',
'gsd-ui-researcher': 'research',
// Execution — implementation, debugging, doc writing
'gsd-executor': 'execution',
'gsd-debugger': 'execution',
'gsd-doc-writer': 'execution',
// Verification — correctness checks, audits, gap analysis
'gsd-verifier': 'verification',
'gsd-plan-checker': 'verification',
'gsd-integration-checker': 'verification',
'gsd-nyquist-auditor': 'verification',
'gsd-ui-checker': 'verification',
'gsd-ui-auditor': 'verification',
'gsd-doc-verifier': 'verification',
};
/**
* The six phase-type slots accepted in `.planning/config.json` `models`
* block. `discuss` and `completion` are reserved — no current agent maps
* to them today — so users can pre-configure those slots without
* breaking validation when an orchestrator starts honoring them.
*/
const VALID_PHASE_TYPES = new Set([
'planning', 'discuss', 'research', 'execution', 'verification', 'completion',
]);
/**
* #3024 — Per-agent default tier for dynamic routing.
*
* Each agent declares a default routing tier (light/standard/heavy)
* that the dynamic-routing resolver uses to pick from
* `dynamic_routing.tier_models[tier]` on the first attempt. On
* orchestrator-detected soft failure, the resolver escalates to the
* next tier up (capped at `max_escalations`).
*
* Tier semantics:
* - light: cheap/fast — pure mappers/scanners, low-stakes verifiers
* - standard: default workhorse — most researchers/writers/checkers
* - heavy: deep reasoning — planners/debuggers; can't escalate further
*
* Adding a new agent to MODEL_PROFILES requires adding an entry here too;
* tests/feat-3024-dynamic-routing.test.cjs asserts coverage.
*/
const AGENT_DEFAULT_TIERS = {
// Heavy — deep reasoning, planning, hard debugging
'gsd-planner': 'heavy',
'gsd-roadmapper': 'heavy',
'gsd-debugger': 'heavy',
// Standard — default workhorse: research, writing, primary verification
'gsd-executor': 'standard',
'gsd-phase-researcher': 'standard',
'gsd-project-researcher': 'standard',
'gsd-verifier': 'standard',
'gsd-doc-writer': 'standard',
'gsd-ui-researcher': 'standard',
// Light — fast scanners, structural mappers, low-stakes audits
'gsd-codebase-mapper': 'light',
'gsd-pattern-mapper': 'light',
'gsd-research-synthesizer': 'light',
'gsd-plan-checker': 'light',
'gsd-integration-checker': 'light',
'gsd-nyquist-auditor': 'light',
'gsd-ui-checker': 'light',
'gsd-ui-auditor': 'light',
'gsd-doc-verifier': 'light',
};
/**
* The three valid agent tier slots for dynamic routing. Used to
* validate `dynamic_routing.tier_models.<tier>` keys at config-set
* time and the AGENT_DEFAULT_TIERS values at startup.
*/
const VALID_AGENT_TIERS = new Set(['light', 'standard', 'heavy']);
/**
* Tier escalation order: light → standard → heavy.
* `nextTier(currentTier)` returns the tier one step up. `heavy` stays
* at heavy (no tier above). Returns null for invalid input so callers
* can detect mis-config rather than silently degrade.
*/
const _TIER_ESCALATION = { light: 'standard', standard: 'heavy', heavy: 'heavy' };
function nextTier(currentTier) {
if (typeof currentTier !== 'string') return null;
return _TIER_ESCALATION[currentTier] || null;
}
/**
* Formats the agent-to-model mapping as a human-readable table (in string format).
*
* @param {Object<string, string>} agentToModelMap - A mapping from agent to model
* @returns {string} A formatted table string
*/
function formatAgentToModelMapAsTable(agentToModelMap) {
const agentWidth = Math.max('Agent'.length, ...Object.keys(agentToModelMap).map((a) => a.length));
const modelWidth = Math.max(
'Model'.length,
...Object.values(agentToModelMap).map((m) => m.length)
);
const sep = '─'.repeat(agentWidth + 2) + '┼' + '─'.repeat(modelWidth + 2);
const header = ' ' + 'Agent'.padEnd(agentWidth) + ' │ ' + 'Model'.padEnd(modelWidth);
let agentToModelTable = header + '\n' + sep + '\n';
for (const [agent, model] of Object.entries(agentToModelMap)) {
agentToModelTable += ' ' + agent.padEnd(agentWidth) + ' │ ' + model.padEnd(modelWidth) + '\n';
}
return agentToModelTable;
}
/**
* Returns a mapping from agent to model for the given model profile.
*
* @param {string} normalizedProfile - The normalized (lowercase and trimmed) profile name
* @returns {Object<string, string>} A mapping from agent to model for the given profile
*/
function getAgentToModelMapForProfile(normalizedProfile) {
const agentToModelMap = {};
for (const [agent, profileToModelMap] of Object.entries(MODEL_PROFILES)) {
agentToModelMap[agent] = normalizedProfile === 'inherit'
? 'inherit'
: profileToModelMap[normalizedProfile];
}
return agentToModelMap;
}
const {
MODEL_PROFILES,
VALID_PROFILES,
AGENT_TO_PHASE_TYPE,
VALID_PHASE_TYPES,
AGENT_DEFAULT_TIERS,
VALID_AGENT_TIERS,
nextTier,
formatAgentToModelMapAsTable,
getAgentToModelMapForProfile,
} = require('./model-catalog.cjs');
module.exports = {
MODEL_PROFILES,

View File

@@ -349,6 +349,7 @@ Built-in tier defaults by runtime:
| `qwen` | `qwen3-max-2026-01-23` | `qwen3-coder-plus` | `qwen3-coder-next` |
| `opencode` | `anthropic/claude-opus-4-7` | `anthropic/claude-sonnet-4-6` | `anthropic/claude-haiku-4-5` |
| `copilot` | `claude-opus-4-7` | `claude-sonnet-4-6` | `claude-haiku-4-5` |
| `hermes` | `anthropic/claude-opus-4-7` | `anthropic/claude-sonnet-4-6` | `anthropic/claude-haiku-4-5` |
| Group B (`kilo`, `cline`, `cursor`, `windsurf`, `augment`, `trae`, `codebuddy`, `antigravity`) | (no built-in default — your runtime handles model selection) | | |
Display a table to the user showing the effective configuration: