mixdog 0.9.2 → 0.9.4

package/src/runtime/agent/orchestrator/config.mjs

@@ -231,6 +231,29 @@ function persistAgentConfig(build) {
     updateSection('agent', (current) => build(hasKeys(current) ? current : {}));
 }
 
+// Recap toggle (recap.enabled, default true) gates ONLY the background memory
+// cycles. The memory module itself is always-on. On load we fold a legacy
+// `modules.memory === false` flag into recap.enabled=false one time; the caller
+// (loadConfig) persists the migration so the legacy flag is dropped from disk.
+let _migratedRecapLegacy = false;
+function normalizeRecapConfig(rawRecap, rawModules) {
+    const recap = rawRecap && typeof rawRecap === 'object' ? { ...rawRecap } : {};
+    if (!('enabled' in recap)) {
+        const legacyMemory = rawModules && typeof rawModules === 'object' ? rawModules.memory : undefined;
+        const legacyDisabled = legacyMemory === false
+            || (legacyMemory && typeof legacyMemory === 'object' && legacyMemory.enabled === false);
+        if (legacyDisabled) {
+            recap.enabled = false;
+            _migratedRecapLegacy = true;
+        } else {
+            recap.enabled = true;
+        }
+    } else {
+        recap.enabled = recap.enabled !== false;
+    }
+    return recap;
+}
+
 export function loadConfig(options = {}) {
     const includeSecrets = options.secrets !== false;
     const sectionRaw = readSection('agent');
@@ -353,6 +376,40 @@ export function loadConfig(options = {}) {
                     process.stderr.write(`[config] persist maintenance migration failed: ${err?.message}\n`);
                 }
             }
+            // One-time recap migration: fold a legacy `modules.memory === false`
+            // flag into `recap.enabled=false` and drop the legacy flag on disk.
+            // Compute the recap shape here (before the return) so the
+            // _migratedRecapLegacy latch is set, then persist under the lock.
+            const recapConfig = normalizeRecapConfig(raw.recap, raw.modules);
+            if (_migratedRecapLegacy) {
+                _migratedRecapLegacy = false;
+                try {
+                    persistAgentConfig((current) => {
+                        const cur = { ...current };
+                        const target = (cur.agent && cur.agent.providers)
+                            ? (cur.agent = { ...cur.agent })
+                            : cur;
+                        const recap = (target.recap && typeof target.recap === 'object') ? { ...target.recap } : {};
+                        if (!('enabled' in recap)) recap.enabled = false;
+                        target.recap = recap;
+                        if (target.modules && typeof target.modules === 'object' && target.modules.memory === false) {
+                            const modules = { ...target.modules };
+                            delete modules.memory;
+                            target.modules = modules;
+                        } else if (target.modules && typeof target.modules === 'object' && target.modules.memory) {
+                            const modules = { ...target.modules };
+                            const memoryMod = { ...modules.memory };
+                            delete memoryMod.enabled;
+                            if (Object.keys(memoryMod).length === 0) delete modules.memory;
+                            else modules.memory = memoryMod;
+                            target.modules = modules;
+                        }
+                        return cur;
+                    });
+                } catch (err) {
+                    process.stderr.write(`[config] persist recap migration failed: ${err?.message}\n`);
+                }
+            }
             const rawPresets = Array.isArray(raw.presets) ? raw.presets : [];
             const normalizedPresets = rawPresets
                 .map(p => normalizePreset(p))
@@ -378,12 +435,18 @@ export function loadConfig(options = {}) {
                 workflow: raw.workflow && typeof raw.workflow === 'object' ? { active: String(raw.workflow.active || 'default') } : { active: 'default' },
                 agentMaintenance: { enabled: true, interval: '1h', ...raw.agentMaintenance },
                 profile: normalizeProfileConfig(raw.profile),
-                autoClear: { enabled: true, idleMs: 60 * 60 * 1000, ...raw.autoClear },
+                // No idleMs default here: absent idleMs means "provider default"
+                // (config-helpers normalizeAutoClearConfig custom:false path).
+                // Injecting a fixed 1h would mark every config custom:true and
+                // bypass the per-provider auto-clear table.
+                autoClear: { enabled: true, ...raw.autoClear },
                 compaction: raw.compaction && typeof raw.compaction === 'object' ? { ...raw.compaction } : {},
                 trajectory: { enabled: true, ...raw.trajectory },
                 runtime: raw.runtime && typeof raw.runtime === 'object' ? raw.runtime : {},
                 shell: raw.shell && typeof raw.shell === 'object' ? raw.shell : {},
                 update: raw.update && typeof raw.update === 'object' ? { ...raw.update } : {},
+                recap: recapConfig,
+                modules: raw.modules && typeof raw.modules === 'object' ? { ...raw.modules } : {},
             };
         }
         catch { /* fall through */ }
@@ -404,12 +467,14 @@ export function loadConfig(options = {}) {
         workflow: { active: 'default' },
         agentMaintenance: { enabled: true, interval: '1h' },
         profile: normalizeProfileConfig(null),
-        autoClear: { enabled: true, idleMs: 60 * 60 * 1000 },
+                autoClear: { enabled: true },
         compaction: {},
         trajectory: { enabled: true },
         runtime: {},
         shell: {},
         update: {},
+        recap: { enabled: true },
+        modules: {},
     };
 }
 /**
@@ -485,6 +550,8 @@ export function saveConfig(config) {
         runtime: config.runtime || {},
         shell: config.shell || {},
         update: config.update || {},
+        recap: config.recap || {},
+        modules: config.modules || existingRaw.modules || {},
     }));
 }
 // --- Preset helpers ---

package/src/runtime/agent/orchestrator/context/collect.mjs

@@ -33,6 +33,47 @@ function mixdogAssetDirs(projectDir, kind) {
     dirs.push(mixdogGlobalDir(kind));
     return dirs;
 }
+/**
+ * Absolute path to the plugin registry file, or null when the data dir is
+ * unresolvable. Included in the skills mtime gate so plugin add/remove
+ * (which rewrites registry.json) invalidates the cached skill list even
+ * when no surviving skills dir got a newer mtime.
+ */
+function pluginRegistryPath() {
+    try {
+        return join(resolvePluginData(), 'plugins', 'registry.json');
+    } catch {
+        return null;
+    }
+}
+/**
+ * Read `<resolvePluginData()>/plugins/registry.json` (safe JSON parse, ignore
+ * errors) and yield `<root>/skills` for each registered plugin whose `root`
+ * exists on disk and has a `skills` subdirectory.
+ */
+function pluginSkillDirs() {
+    const registryPath = pluginRegistryPath();
+    if (!registryPath)
+        return [];
+    let registry;
+    try {
+        registry = JSON.parse(readFileSync(registryPath, 'utf-8'));
+    } catch {
+        return [];
+    }
+    if (!registry || !Array.isArray(registry.plugins))
+        return [];
+    const dirs = [];
+    for (const entry of registry.plugins) {
+        const root = entry && typeof entry.root === 'string' ? entry.root : null;
+        if (!root || !existsSync(root))
+            continue;
+        const skillsDir = join(root, 'skills');
+        if (existsSync(skillsDir))
+            dirs.push(skillsDir);
+    }
+    return dirs;
+}
 /**
  * Collect available skills (frontmatter only — token efficient).
  * Full content loaded on demand via loadSkillContent().
@@ -49,6 +90,9 @@ export function collectSkills(cwd) {
     // first, then user-global. When cwd is missing, only the global dir is
     // searched.
     const dirs = mixdogAssetDirs(projectDir, 'skills');
+    // Plugin-provided skills load last so project-local and global mixdog
+    // skill dirs keep precedence; `seen` below dedupes by frontmatter name.
+    dirs.push(...pluginSkillDirs());
     const seen = new Set();
     for (const dir of dirs) {
         if (!existsSync(dir))
@@ -88,6 +132,13 @@ export function collectSkillsCached(cwd) {
     const projectDir = (typeof cwd === 'string' && cwd.length > 0) ? cwd : null;
     // Same mixdog-owned dirs collectSkills() reads, used as the freshness gate.
     const skillsDirs = mixdogAssetDirs(projectDir, 'skills');
+    skillsDirs.push(...pluginSkillDirs());
+    // registry.json itself gates plugin add/remove: removal deletes the
+    // plugin's skills dir (so no dir mtime advances), but saveRegistry()
+    // always rewrites this file. maxMtimeRecursive stats plain files directly.
+    const registryPath = pluginRegistryPath();
+    if (registryPath)
+        skillsDirs.push(registryPath);
     let mtime;
     const mtimeCached = _mtimeCache.get(key);
     if (mtimeCached && Date.now() - mtimeCached.checkedAt < _MTIME_TTL_MS) {

package/src/runtime/agent/orchestrator/mcp/client.mjs

@@ -1,4 +1,5 @@
-import { readFileSync, existsSync, mkdirSync, writeFileSync } from 'fs';
+import { readFileSync, existsSync, mkdirSync } from 'fs';
+import { writeFile } from 'fs/promises';
 import { join } from 'path';
 import { tmpdir } from 'os';
 import { randomUUID } from 'crypto';
@@ -273,7 +274,10 @@ function capMcpOutput(content) {
         const dir = join(tmpdir(), 'mixdog-mcp-output');
         mkdirSync(dir, { recursive: true });
         spillPath = join(dir, `mcp-${Date.now()}-${randomUUID().slice(0, 8)}.txt`);
-        writeFileSync(spillPath, s, 'utf-8');
+        // Fire-and-forget: the spill path is returned to the caller
+        // immediately (below) for later recovery; the write itself must not
+        // block this hot tool-result path.
+        writeFile(spillPath, s, 'utf-8').catch(() => { /* spill best-effort */ });
     } catch { /* spill best-effort */ }
     const spillNote = spillPath
         ? `\n\n... [full output spilled to ${spillPath}] ...`

package/src/runtime/agent/orchestrator/providers/anthropic-effort.mjs

@@ -1,8 +1,21 @@
 /**
- * Anthropic effort API alignment (Claude Code effort.ts + configureEffortParams).
+ * Anthropic "effort" (extended-thinking budget) request parameter handling.
  */
 
-export const EFFORT_LEVELS = Object.freeze(['low', 'medium', 'high', 'max']);
+export const EFFORT_LEVELS = Object.freeze(['low', 'medium', 'high', 'xhigh', 'max']);
+
+// Canonical display/transport ordering for effort levels. Used only to sort
+// whatever set the catalog actually advertises — NOT as an allowlist. The
+// catalog (capabilities.effort) is the source of truth for which levels a
+// model exposes; this array just keeps them in a stable low→max order.
+const EFFORT_LEVEL_ORDER = Object.freeze(['none', 'low', 'medium', 'high', 'xhigh', 'max']);
+function _sortEffortLevels(levels) {
+    const rank = (l) => {
+        const i = EFFORT_LEVEL_ORDER.indexOf(l);
+        return i === -1 ? EFFORT_LEVEL_ORDER.length : i;
+    };
+    return [...levels].sort((a, b) => rank(a) - rank(b));
+}
 
 export const EFFORT_BETA_HEADER = 'effort-2025-11-24';
 
@@ -10,6 +23,7 @@ export const LEGACY_EFFORT_BUDGET = Object.freeze({
     low: 1024,
     medium: 4096,
     high: 16384,
+    xhigh: 32768,
     max: 32768,
 });
 const _LOGGED_EFFORT_NORMALIZATION = new Set();
@@ -59,11 +73,28 @@ export function modelSupportsEffort(model) {
     return false;
 }
 
+// @[MODEL LAUNCH]: extend when new models support xhigh effort.
+// Per platform.claude.com/docs/en/build-with-claude/effort — xhigh is
+// supported by: Fable 5, Mythos 5, Opus 4.8, Opus 4.7, Sonnet 5.
+// NOT Opus 4.6 / Sonnet 4.6 (those support max but not xhigh).
+export function modelSupportsXhighEffort(model) {
+    const m = normalizeModelId(model);
+    if (/^claude-opus-4-(7|8)(?:$|[-@])/.test(m)) return true;
+    if (/^claude-opus-5(?:$|[-@])/.test(m)) return true;
+    if (/^claude-sonnet-5(?:$|[-@])/.test(m)) return true;
+    if (/^claude-fable-5(?:$|[-@])/.test(m)) return true;
+    if (/^claude-mythos-5(?:$|[-@])/.test(m)) return true;
+    if (/^claude-mythos-preview(?:$|[-@])/.test(m)) return true;
+    return false;
+}
+
 // @[MODEL LAUNCH]: extend when new Opus models support max effort.
+// Max list = xhigh list PLUS Opus 4.6, Sonnet 4.6, Opus 4.5.
 export function modelSupportsMaxEffort(model) {
+    if (modelSupportsXhighEffort(model)) return true;
     const m = normalizeModelId(model);
-    if (/^claude-opus-4-(6|7|8)(?:$|[-@])/.test(m)) return true;
-    if (/^claude-opus-5-/.test(m)) return true;
+    if (/^claude-opus-4-(5|6)(?:$|[-@])/.test(m)) return true;
+    if (/^claude-sonnet-4-6(?:$|[-@])/.test(m)) return true;
     return false;
 }
 
@@ -79,26 +110,24 @@ function logOnce(key, write) {
 }
 
 /**
- * Normalize user/config effort to API levels (low/medium/high/max).
- * Maps legacy xhigh → max (Opus 4.6+) or high; clamps max on non-Opus models.
+ * Normalize user/config effort to API levels (low/medium/high/xhigh/max).
+ * Accepts extra-high / very-high aliases as xhigh; clamps xhigh/max down to
+ * high on models that don't support the top Opus tiers.
  */
 export function normalizeAnthropicEffortInput(raw, model, logTag = 'anthropic') {
     if (raw === undefined || raw === null || raw === '') return undefined;
     let level = String(raw).trim().toLowerCase();
     if (level === 'extra-high' || level === 'very-high') level = 'xhigh';
 
-    if (level === 'xhigh') {
-        const mapped = modelSupportsMaxEffort(model) ? 'max' : 'high';
-        logOnce(`xhigh:${mapped}`, () => {
-            process.stderr.write(
-                `[${logTag}] effort "xhigh" normalized to "${mapped}" (official levels: ${EFFORT_LEVELS.join(', ')})\n`,
-            );
+    if (level === 'xhigh' && !modelSupportsXhighEffort(model)) {
+        logOnce(`xhigh:high`, () => {
+            process.stderr.write(`[${logTag}] effort "xhigh" downgraded to "high" for model ${model}\n`);
         });
-        return mapped;
+        return 'high';
     }
 
     if (level === 'max' && !modelSupportsMaxEffort(model)) {
-        logOnce('max:high', () => {
+        logOnce(`max:high`, () => {
             process.stderr.write(`[${logTag}] effort "max" downgraded to "high" for model ${model}\n`);
         });
         return 'high';
@@ -174,15 +203,28 @@ export function applyAnthropicEffortToBody(
 
 export function effortValuesForModel(capabilities, modelId) {
     const effort = capabilities?.effort;
+    if (!effort) return [];
+    // Catalog-first: when capabilities.effort enumerates per-level support,
+    // that map is the source of truth — expose exactly the levels the model
+    // advertises (xhigh, max, or anything future), no hardcoded allowlist.
+    if (effort !== true && typeof effort === 'object') {
+        const advertised = Object.keys(effort).filter(
+            (level) => effort[level] === true || effort[level]?.supported === true,
+        );
+        if (advertised.length) return _sortEffortLevels(advertised);
+        // Object with no per-level flags: fall through to the boolean/supported
+        // fallback below only when it explicitly marks blanket support.
+        if (effort.supported !== true) return [];
+    }
+    // Fallback (effort === true, or {supported:true} with no per-level map):
+    // the model supports effort but doesn't enumerate levels, so derive the
+    // set from the known level ladder, gated by the top-tier model check.
     let levels = [...EFFORT_LEVELS];
     if (!modelSupportsMaxEffort(modelId)) {
         levels = levels.filter((level) => level !== 'max');
     }
-    if (!effort) return [];
-    if (effort === true) return levels;
-    const values = levels.filter(
-        (level) => effort?.[level] === true || effort?.[level]?.supported === true,
-    );
-    if (values.length) return values;
-    return effort.supported === true ? levels : [];
+    if (!modelSupportsXhighEffort(modelId)) {
+        levels = levels.filter((level) => level !== 'xhigh');
+    }
+    return levels;
 }

package/src/runtime/agent/orchestrator/providers/anthropic-max-tokens.mjs

@@ -0,0 +1,93 @@
+// Shared catalog-driven max_tokens resolution for both Anthropic providers
+// (OAuth and API-key). Extracted from anthropic-oauth.mjs so anthropic.mjs
+// (the API-key twin) gets the same sonnet-5+ / haiku fix instead of drifting
+// with its own hardcoded table.
+//
+// Resolution order:
+//   1. MIXDOG_ANTHROPIC_MAX_OUTPUT_TOKENS env override, if set to a positive
+//      int, wins outright (returned as the safety cap itself).
+//   2. Catalog outputTokens for the model id (trusted over hardcoded
+//      heuristics when present — the API reports real per-model limits),
+//      clamped to [MAX_TOKENS_FLOOR, safetyCap].
+//   3. Static per-model table / family heuristic fallback when the catalog
+//      has no entry for this model, also capped at the safety cap.
+
+export const MAX_TOKENS_FLOOR = 8192;
+export const DEFAULT_SAFETY_CAP = 65536;
+const ENV_VAR = 'MIXDOG_ANTHROPIC_MAX_OUTPUT_TOKENS';
+
+// Per-model max_tokens when the model id is explicitly listed. New models
+// (e.g., Sonnet 4.7) won't match a specific entry and fall through to the
+// family-based heuristic below. Conservative defaults — model may support
+// more but we'd rather stay within safe bounds.
+const MAX_TOKENS = {
+    'claude-opus-4-8': 65536,
+    'claude-opus-4-7': 65536,
+    'claude-opus-4-6': 65536,
+    'claude-sonnet-4-6': 16384,
+    'claude-haiku-4-5-20251001': 8192,
+};
+
+// Strict-positive env override parsing. Invalid values ("0", negatives,
+// garbage, whitespace) are treated as UNSET — not as "use the default cap
+// outright" — so catalog/fallback still decide for low-cap models. Raw env
+// truthiness must never bypass resolution.
+export function envAnthropicMaxOutputOverride() {
+    const raw = process.env[ENV_VAR];
+    if (raw == null || String(raw).trim() === '') return null;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0) return null;
+    return Math.floor(n);
+}
+
+export function resolveAnthropicSafetyCap() {
+    return envAnthropicMaxOutputOverride() ?? DEFAULT_SAFETY_CAP;
+}
+
+// Pure lookup over an already-loaded catalog array (disk cache or in-memory
+// mirror) — no I/O, no caching strategy. Callers own how/when the array is
+// loaded/refreshed.
+export function lookupCatalogOutputTokens(models, id) {
+    if (!id || !Array.isArray(models)) return null;
+    const entry = models.find(m => m?.id === id);
+    const out = Number(entry?.outputTokens);
+    return Number.isFinite(out) && out > 0 ? out : null;
+}
+
+// Static per-model table + family heuristic, used when the catalog has no
+// entry for this model id. Sonnet 5+ ships a much larger output budget than
+// the legacy 4.x line (this is the claude-sonnet-5 fix: 16384 was starving
+// visible output once extended thinking ate into the same hard cap). Keep
+// sonnet-4-x conservative at 16384; only bump 5+.
+export function fallbackAnthropicMaxTokens(model) {
+    if (MAX_TOKENS[model]) return MAX_TOKENS[model];
+    const id = String(model || '').toLowerCase();
+    if (id.includes('opus')) return 65536;
+    if (id.includes('fable')) return 65536;
+    const sonnetVersion = id.match(/^claude-sonnet-(\d+)/);
+    if (sonnetVersion) return Number(sonnetVersion[1]) >= 5 ? 65536 : 16384;
+    if (id.includes('sonnet')) return 16384;
+    if (id.includes('haiku')) return 8192;
+    return 8192;
+}
+
+// catalogLookup(model) -> number|null. Providers supply their own strategy
+// for sourcing the catalog array (in-memory mirror + disk fallback for OAuth,
+// plain disk read for the API-key twin — see anthropic.mjs).
+export function resolveAnthropicMaxTokens(model, { catalogLookup } = {}) {
+    const envOverride = envAnthropicMaxOutputOverride();
+    if (envOverride != null) return envOverride;
+    const safetyCap = DEFAULT_SAFETY_CAP;
+    let catalogValue = null;
+    if (typeof catalogLookup === 'function') {
+        try {
+            catalogValue = catalogLookup(model);
+        } catch {
+            catalogValue = null;
+        }
+    }
+    if (Number.isFinite(catalogValue) && catalogValue > 0) {
+        return Math.max(MAX_TOKENS_FLOOR, Math.min(catalogValue, safetyCap));
+    }
+    return Math.min(fallbackAnthropicMaxTokens(model), safetyCap);
+}

package/src/runtime/agent/orchestrator/providers/anthropic-model-resolve.mjs

@@ -0,0 +1,209 @@
+/**
+ * anthropic-model-resolve.mjs — Anthropic OAuth model-catalog cache + resolvers.
+ *
+ * Extracted from anthropic-oauth.mjs. Owns the disk-backed catalog cache and
+ * its in-memory mirror (single instance; the provider imports every reader/
+ * writer from here so there is exactly ONE catalog state in the process).
+ */
+import { enrichModels } from './model-catalog.mjs';
+import { sanitizeModelList } from './model-list-sanitize.mjs';
+import { makeModelCache } from './model-cache.mjs';
+import { effortValuesForModel } from './anthropic-effort.mjs';
+
+// Disk-backed cache so repeated process starts (cron, tool calls) don't
+// hammer /v1/models. 24h TTL matches the upstream client cadence.
+const MODEL_CACHE_TTL_MS = 24 * 60 * 60_000;
+// Bump when the on-disk cache shape changes so stale-shape entries are
+// discarded instead of misread.
+const ANTHROPIC_MODEL_CACHE_SCHEMA_VERSION = 1;
+
+const _modelCache = makeModelCache({
+    fileName: 'anthropic-oauth-models.json',
+    ttlMs: MODEL_CACHE_TTL_MS,
+    version: ANTHROPIC_MODEL_CACHE_SCHEMA_VERSION,
+    onSave: (m) => { _inMemoryCatalog = Array.isArray(m) ? m.slice() : null; },
+});
+
+// Async wrappers so callers can keep awaiting; the shared cache CRUD is sync.
+export async function _loadModelCache() {
+    return _modelCache.loadSync();
+}
+
+export async function _saveModelCache(models) {
+    _modelCache.save(models);
+}
+
+// In-memory mirror of the disk catalog — populated on first listModels() and
+// refreshed after every _saveModelCache. Used by _catalogHas and _displayModel
+// so hot paths don't hit disk on every response.
+let _inMemoryCatalog = null;
+
+// The mirror is written both by this module (onSave) and by the provider's
+// listModels() warm path, so expose a setter instead of the raw binding.
+export function _setInMemoryCatalog(models) {
+    _inMemoryCatalog = Array.isArray(models) ? models.slice() : null;
+}
+
+export function _catalogHas(id) {
+    if (!id || !Array.isArray(_inMemoryCatalog)) return false;
+    return _inMemoryCatalog.some(m => m.id === id);
+}
+
+// Display-name normalization for trace / usage. Turns dated or version-alias
+// ids into the version alias form: claude-opus-4-7 → claude-opus-4.7,
+// claude-haiku-4-5-20251001 → claude-haiku-4.5. Falls back to the raw id.
+export function _displayModel(id) {
+    if (!id || typeof id !== 'string') return id;
+    const m = id.match(/^claude-([a-z]+)-(\d+)(?:-(\d+))?(?:-\d{8})?$/i);
+    if (!m) return id;
+    return `claude-${m[1].toLowerCase()}-${m[2]}${m[3] ? `.${m[3]}` : ''}`;
+}
+
+function _capabilitySupported(capability) {
+    return capability === true || capability?.supported === true;
+}
+
+// Classify a model id into our common tier/family shape. Anthropic's catalog
+// mixes dated ids (claude-opus-4-5-20251101), versioned aliases
+// (claude-opus-4-6), and the raw family tokens resolved via env vars.
+export function _normalizeAnthropicModel(raw) {
+    const id = raw?.id || raw?.name;
+    if (!id) return null;
+    const familyMatch = id.match(/^claude-([a-z]+)/i);
+    const family = familyMatch ? familyMatch[1].toLowerCase() : 'other';
+    // Dated: trailing -YYYYMMDD (8 digits).
+    const dated = /-\d{8}$/.test(id);
+    // Versioned alias: claude-<family>-<major>-<minor>[-...] with no dated suffix.
+    const versioned = !dated && /^claude-[a-z]+-\d+(?:-\d+)?$/i.test(id);
+    const tier = dated ? 'dated' : versioned ? 'version' : 'family';
+    const releaseDate = dated
+        ? id.match(/-(\d{4})(\d{2})(\d{2})$/)
+        : null;
+    const effortValues = effortValuesForModel(raw?.capabilities, id);
+    return {
+        id,
+        display: raw?.display_name || _prettyName(id, family),
+        family,
+        provider: 'anthropic-oauth',
+        contextWindow: raw?.context_window || raw?.max_context_window || raw?.max_input_tokens || _defaultContextForModel(id, family),
+        outputTokens: raw?.max_tokens || raw?.max_output_tokens || null,
+        tier,
+        latest: false, // assigned in a second pass once full list is known
+        releaseDate: releaseDate ? `${releaseDate[1]}-${releaseDate[2]}-${releaseDate[3]}` : null,
+        supportsReasoning: effortValues.length > 0 || _capabilitySupported(raw?.capabilities?.thinking),
+        reasoningOptions: effortValues.length ? [{ type: 'effort', values: effortValues }] : [],
+    };
+}
+
+function _prettyName(id, family) {
+    const v = id.match(/^claude-[a-z]+-(\d+)(?:-(\d+))?/i);
+    const base = family[0].toUpperCase() + family.slice(1);
+    return v ? `${base} ${v[1]}${v[2] ? `.${v[2]}` : ''}` : base;
+}
+
+function _defaultContextForModel(id, family) {
+    const text = String(id || '');
+    const version = text.match(/^claude-[a-z]+-(\d+)(?:-(\d+))?/i);
+    if (Number(version?.[1] || 0) >= 5) return 1000000;
+    if (/^claude-(opus|sonnet)-4-(6|7|8)(?:$|-)/i.test(text)) return 1000000;
+    if (family && family !== 'other') return 200000;
+    return 200000;
+}
+
+// Mark the highest-numbered version per family as `latest: true`. Uses a simple
+// lexicographic comparison on the numeric parts embedded in the id.
+export function _markLatestByFamily(models) {
+    const byFamily = new Map();
+    for (const m of models) {
+        if (m.tier !== 'version') continue;
+        const cur = byFamily.get(m.family);
+        if (!cur || _compareVersion(m.id, cur.id) > 0) {
+            byFamily.set(m.family, m);
+        }
+    }
+    for (const m of byFamily.values()) m.latest = true;
+}
+
+function _compareVersion(a, b) {
+    const na = (a.match(/^claude-[a-z]+-(\d+)(?:-(\d+))?/i) || []).slice(1).map(Number);
+    const nb = (b.match(/^claude-[a-z]+-(\d+)(?:-(\d+))?/i) || []).slice(1).map(Number);
+    for (let i = 0; i < Math.max(na.length, nb.length); i++) {
+        if ((na[i] || 0) !== (nb[i] || 0)) return (na[i] || 0) - (nb[i] || 0);
+    }
+    return a.localeCompare(b);
+}
+
+// Newest HIGH-TIER chat model by version, read from the SYNC in-memory catalog
+// mirror. Anthropic ships three families: opus / sonnet / haiku. "Latest" is the
+// highest version across opus + sonnet only — haiku is the cheap tier and is
+// never the flagship default. Returns null until listModels() populates the
+// mirror; callers must warm the catalog (ensureLatestAnthropicModel) when null.
+export function resolveLatestAnthropicModel() {
+    if (!Array.isArray(_inMemoryCatalog)) return null;
+    let best = null;
+    for (const m of _inMemoryCatalog) {
+        if (!m?.id || (m.family !== 'opus' && m.family !== 'sonnet')) continue;
+        if (!best || _compareVersion(m.id, best.id) > 0) best = m;
+    }
+    return best?.id || null;
+}
+
+export function resolveAnthropicModelAfter404(requested) {
+    if (!Array.isArray(_inMemoryCatalog)) return null;
+    const wanted = String(requested || '');
+    const family = (wanted.match(/^claude-([a-z]+)/i) || [])[1]?.toLowerCase() || null;
+    let best = null;
+    for (const m of _inMemoryCatalog) {
+        if (!m?.id) continue;
+        if (family && m.family !== family) continue;
+        if (!family && m.family !== 'opus' && m.family !== 'sonnet') continue;
+        if (!best || _compareVersion(m.id, best.id) > 0) best = m;
+    }
+    if (best?.id && best.id !== wanted) return best.id;
+    if (family === 'opus') {
+        const flagship = resolveLatestAnthropicModel();
+        if (flagship && flagship !== wanted) return flagship;
+    }
+    return null;
+}
+
+export async function ensureLatestAnthropicModel(provider) {
+    let m = resolveLatestAnthropicModel();
+    if (m) return m;
+    await provider._refreshModelCache();
+    m = resolveLatestAnthropicModel();
+    if (m) return m;
+    throw new Error('[anthropic-oauth] model catalog unavailable after warmup — cannot resolve default model');
+}
+
+// Catalog-reported outputTokens for a model id, read from the in-memory
+// catalog mirror (lazily populated from the disk cache if the mirror hasn't
+// been warmed yet by listModels()). Never throws — any failure just means
+// "no catalog data", and callers fall back to the static heuristics.
+export function _catalogOutputTokens(model) {
+    if (!model) return null;
+    try {
+        if (!Array.isArray(_inMemoryCatalog)) {
+            const cached = _modelCache.loadSync();
+            if (Array.isArray(cached)) _inMemoryCatalog = cached.slice();
+        }
+        if (!Array.isArray(_inMemoryCatalog)) return null;
+        const entry = _inMemoryCatalog.find(m => m?.id === model);
+        const out = Number(entry?.outputTokens);
+        return Number.isFinite(out) && out > 0 ? out : null;
+    } catch {
+        return null;
+    }
+}
+
+// Normalize + mark-latest + LiteLLM-enrich + persist one fetched /v1/models
+// payload. Shared by the provider's listModels() and _refreshModelCache().
+export async function normalizeAndSaveCatalog(items) {
+    const normalized = (Array.isArray(items) ? items : [])
+        .map(m => _normalizeAnthropicModel(m))
+        .filter(Boolean);
+    _markLatestByFamily(normalized);
+    const enriched = sanitizeModelList(await enrichModels(normalized), { provider: 'anthropic' });
+    await _saveModelCache(enriched);
+    return enriched;
+}