evolcore 0.0.22 → 0.0.24

package/dist/agents/claude-runner.js

@@ -1,6 +1,8 @@
+import { getRunnerCatalog, peekRunnerCatalog, catalogEfforts, resolveCatalogModel, assertCatalogSelectable } from '../core/model/model-catalog.js';
 import { query, forkSession as sdkForkSession, getSessionMessages as sdkGetSessionMessages, resolveSettings as sdkResolveSettings, } from '@anthropic-ai/claude-agent-sdk';
 import { spawn } from 'child_process';
-import { atomicReadJson, atomicWriteJson, ensureDir } from '../utils/atomic-write.js';
+import { createRequire } from 'module';
+import { ensureDir } from '../utils/atomic-write.js';
 import { resolveAnthropicConfig } from './baseagent.js';
 import { buildModelRequestHeaders } from './request-identity.js';
 import { DEFAULT_PERMISSION_MODE } from '../types.js';
@@ -29,6 +31,42 @@ import { auditToolInfrastructureFailure, auditToolPreflightDenial } from '../cor
 import { getManagedTaskTempDir, isManagedSessionRuntimeDir } from '../cli/task-context.js';
 import { hasTrustedFullAccessContext } from './runner-types.js';
 import { contextTokensForUsage, usageForContext, isClaudeContextUsageModel, isOneMillionContextModel, realContextWindowForModel, autoCompactWindowForModel } from './runner-types.js';
+const resolveModule = createRequire(import.meta.url);
+/**
+ * Resolve the platform package explicitly instead of relying on the SDK's
+ * internal optional-dependency lookup. The latter is sensitive to the module
+ * installation/loader context and can report a missing binary even when the
+ * package is present in the same node_modules tree.
+ */
+export function resolveBundledClaudeExecutable() {
+    if (process.platform !== 'win32')
+        return undefined;
+    const nativePackage = process.arch === 'arm64'
+        ? '@anthropic-ai/claude-agent-sdk-win32-arm64'
+        : process.arch === 'x64'
+            ? '@anthropic-ai/claude-agent-sdk-win32-x64'
+            : undefined;
+    if (!nativePackage)
+        return undefined;
+    const binarySpecifier = `${nativePackage}/claude.exe`;
+    try {
+        const executable = resolveModule.resolve(binarySpecifier);
+        if (fs.existsSync(executable))
+            return executable;
+    }
+    catch {
+        // Fall through to a direct sibling lookup for package layouts where the
+        // optional package does not expose its binary through exports.
+    }
+    try {
+        const sdkEntry = resolveModule.resolve('@anthropic-ai/claude-agent-sdk');
+        const executable = path.resolve(path.dirname(sdkEntry), '..', '@anthropic-ai', nativePackage.slice('@anthropic-ai/'.length), 'claude.exe');
+        return fs.existsSync(executable) ? executable : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 export { hasCompact, hasModelSwitcher, hasPermissionController } from './runner-types.js';
 // Built-in tools execute inside the Claude runtime and are covered by the
 // runner's filesystem/shell policy. MCP and future unknown tools can perform
@@ -108,6 +146,40 @@ function appendQueryParams(baseUrl, queryParams) {
         return baseUrl;
     }
 }
+function claudeSessionFilePath(projectPath, agentSessionId) {
+    return path.join(os.homedir(), '.claude', 'projects', encodePath(projectPath), `${agentSessionId}.jsonl`);
+}
+/** A discovered Claude session is resumable only after its transcript header is durable. */
+function isClaudeSessionFileReady(projectPath, agentSessionId) {
+    const sessionFile = claudeSessionFilePath(projectPath, agentSessionId);
+    if (!fs.existsSync(sessionFile))
+        return false;
+    try {
+        const content = fs.readFileSync(sessionFile, 'utf8');
+        for (const line of content.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                const data = JSON.parse(line);
+                if (data.sessionId && data.version)
+                    return true;
+            }
+            catch { }
+        }
+    }
+    catch { }
+    return false;
+}
+async function waitForClaudeSessionFile(projectPath, agentSessionId, timeoutMs = 250) {
+    const deadline = Date.now() + timeoutMs;
+    do {
+        if (isClaudeSessionFileReady(projectPath, agentSessionId))
+            return true;
+        if (Date.now() >= deadline)
+            return false;
+        await new Promise(resolve => setTimeout(resolve, 10));
+    } while (true);
+}
 function stableClaudePermissionValue(value, depth = 0) {
     if (depth > 8)
         return '[truncated]';
@@ -261,103 +333,6 @@ async function assertClaudeSettingSourcesHaveLiteralSandboxPaths(cwd, settingSou
         }
     }
 }
-// ── 模型别名解析 ──
-// SDK 内置的别名表可能落后于代理实际可用的最新模型，
-// 因此优先从 {baseUrl}/models 动态获取各系列最新版本，失败则使用持久化的最近成功值。
-// 已验证可用但尚未出现在 /models 列表中的模型 ID 会被注入候选列表，
-// 等列表更新后注入自动变为 no-op。
-const MODEL_FAMILIES = ['opus', 'sonnet', 'haiku'];
-/** 已验证可用但可能尚未出现在 /models 列表中的模型 ID（注入候选） */
-const INJECTED_MODELS = [];
-/** 启动默认值：某网关尚无任何成功刷新记录时使用。 */
-const BOOTSTRAP_MODEL_ALIASES = {
-    'opus': 'claude-opus-4-8',
-    'sonnet': 'claude-sonnet-4-6',
-    'haiku': 'claude-haiku-4-5-20251001',
-};
-const MODEL_ALIAS_TTL_MS = 5 * 60 * 1000; // 5min
-const MODEL_ALIAS_STORE_VERSION = 1;
-const modelAliasCache = new Map(); // key: baseUrl
-const modelAliasFallbacks = new Map(); // key: baseUrl，最近一次成功解析值
-const modelAliasInFlight = new Set(); // 去重并发刷新
-const loadedModelAliasFallbacks = new Set(); // key: store path + gateway hash
-function normalizeModelGatewayUrl(baseUrl) {
-    return baseUrl.trim().replace(/\/+$/, '');
-}
-function modelGatewayKey(baseUrl) {
-    return crypto.createHash('sha256').update(normalizeModelGatewayUrl(baseUrl)).digest('hex');
-}
-function modelAliasStorePath() {
-    return resolvePaths().claudeModelCache;
-}
-function sanitizeModelAliases(value) {
-    if (!value || typeof value !== 'object' || Array.isArray(value))
-        return {};
-    const aliases = {};
-    for (const family of MODEL_FAMILIES) {
-        const model = value[family];
-        if (typeof model !== 'string')
-            continue;
-        const pattern = new RegExp(`^claude-${family}-[A-Za-z0-9._-]+$`);
-        if (pattern.test(model))
-            aliases[family] = model;
-    }
-    return aliases;
-}
-function readPersistedAliasStore() {
-    try {
-        const value = atomicReadJson(modelAliasStorePath());
-        if (!value || typeof value !== 'object' || Array.isArray(value)) {
-            return { $schema_version: MODEL_ALIAS_STORE_VERSION, gateways: {} };
-        }
-        const raw = value;
-        if (raw.$schema_version !== MODEL_ALIAS_STORE_VERSION || !raw.gateways || typeof raw.gateways !== 'object' || Array.isArray(raw.gateways)) {
-            return { $schema_version: MODEL_ALIAS_STORE_VERSION, gateways: {} };
-        }
-        const gateways = {};
-        for (const [key, entry] of Object.entries(raw.gateways)) {
-            if (!/^[a-f0-9]{64}$/.test(key) || !entry || typeof entry !== 'object' || Array.isArray(entry))
-                continue;
-            const record = entry;
-            const aliases = sanitizeModelAliases(record.aliases);
-            if (Object.keys(aliases).length === 0)
-                continue;
-            gateways[key] = {
-                aliases,
-                updatedAt: typeof record.updatedAt === 'number' && Number.isFinite(record.updatedAt) ? record.updatedAt : 0,
-            };
-        }
-        return { $schema_version: MODEL_ALIAS_STORE_VERSION, gateways };
-    }
-    catch (error) {
-        logger.warn(`[AgentRunner] Failed to load persisted model aliases: ${error instanceof Error ? error.message : String(error)}`);
-        return { $schema_version: MODEL_ALIAS_STORE_VERSION, gateways: {} };
-    }
-}
-function loadPersistedModelAliases(baseUrl) {
-    const cacheKey = normalizeModelGatewayUrl(baseUrl);
-    const storePath = modelAliasStorePath();
-    const gatewayKey = modelGatewayKey(cacheKey);
-    const loadKey = `${storePath}\0${gatewayKey}`;
-    if (loadedModelAliasFallbacks.has(loadKey))
-        return;
-    loadedModelAliasFallbacks.add(loadKey);
-    const persisted = readPersistedAliasStore().gateways[gatewayKey];
-    if (!persisted)
-        return;
-    modelAliasFallbacks.set(cacheKey, persisted.aliases);
-    logger.info(`[AgentRunner] Loaded persisted model aliases: ${JSON.stringify(persisted.aliases)}`);
-}
-function persistModelAliases(baseUrl, aliases, updatedAt) {
-    try {
-        const store = readPersistedAliasStore();
-        store.gateways[modelGatewayKey(baseUrl)] = { aliases, updatedAt };
-        atomicWriteJson(modelAliasStorePath(), store);
-    }
-    catch (error) {
-        logger.warn(`[AgentRunner] Failed to persist model aliases: ${error instanceof Error ? error.message : String(error)}`);
-    }
-}
 // ── 网关价格缓存（从 /v1/models 的 pricing/effective_pricing 提取）─────────────
 // 与别名刷新同范式：按 baseUrl 缓存，1h TTL，stale-while-revalidate（缺失/过期时
 // fire-and-forget 触发刷新，本轮先用旧值或回退，不阻塞查询）。
@@ -432,94 +407,6 @@ async function refreshGatewayPricing(baseUrl, apiKey, requestHeaders) {
         gatewayPricingInFlight.delete(baseUrl);
     }
 }
-/** 从模型 ID 列表中提取各 claude 系列的最新版本（按 major.minor 取最高，minor 可省略） */
-function deriveAliasesFromModelIds(ids) {
-    // 注入已验证可用的模型（如果列表中已有则去重无影响）
-    const allIds = [...new Set([...ids, ...INJECTED_MODELS])];
-    const best = {};
-    for (const id of allIds) {
-        const m = id.match(/^claude-(opus|sonnet|haiku)-(\d+)(?:-(\d+))?/);
-        if (!m)
-            continue;
-        const [, family, majorStr, minorStr] = m;
-        const major = parseInt(majorStr, 10);
-        const minor = minorStr ? parseInt(minorStr, 10) : 0;
-        const cur = best[family];
-        if (!cur || major > cur.major || (major === cur.major && minor > cur.minor)) {
-            best[family] = { id, major, minor };
-        }
-    }
-    const aliases = {};
-    for (const family of MODEL_FAMILIES) {
-        const info = best[family];
-        if (info)
-            aliases[family] = info.id;
-    }
-    return aliases;
-}
-/** 异步刷新某 baseUrl 的别名缓存（失败静默，不抛出） */
-async function refreshModelAliases(baseUrl, apiKey, requestHeaders) {
-    const cacheKey = normalizeModelGatewayUrl(baseUrl);
-    if (modelAliasInFlight.has(cacheKey))
-        return;
-    modelAliasInFlight.add(cacheKey);
-    loadPersistedModelAliases(cacheKey);
-    try {
-        const url = `${cacheKey}/models`;
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), 5000);
-        const resp = await fetch(url, {
-            signal: controller.signal,
-            headers: {
-                ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
-                ...requestHeaders,
-            },
-        });
-        clearTimeout(timer);
-        if (!resp.ok)
-            return;
-        const json = await resp.json();
-        const ids = Array.isArray(json?.data)
-            ? json.data.map((m) => m?.id).filter((x) => typeof x === 'string')
-            : [];
-        const aliases = deriveAliasesFromModelIds(ids);
-        if (ids.length > 0 || Object.keys(aliases).length > 0) {
-            const updatedAt = Date.now();
-            modelAliasCache.set(cacheKey, { aliases, ids, fetchedAt: updatedAt });
-            if (Object.keys(aliases).length > 0) {
-                const previousAliases = modelAliasFallbacks.get(cacheKey) || {};
-                const latestAliases = { ...previousAliases, ...aliases };
-                modelAliasFallbacks.set(cacheKey, latestAliases);
-                persistModelAliases(cacheKey, latestAliases, updatedAt);
-            }
-            logger.info(`[AgentRunner] Refreshed models from ${url}: ${ids.length} ids, aliases ${JSON.stringify(aliases)}`);
-        }
-    }
-    catch {
-        // 网络/解析失败：保留该网关最近一次成功结果，不打断查询
-    }
-    finally {
-        modelAliasInFlight.delete(cacheKey);
-    }
-}
-/** 将短别名展开为完整 model ID，已是完整 ID 则原样返回 */
-function resolveModelAlias(model, baseUrl) {
-    // 非短别名（已经是完整 ID）直接返回
-    if (!MODEL_FAMILIES.includes(model))
-        return model;
-    const family = model;
-    // 优先使用动态缓存
-    if (baseUrl) {
-        const cacheKey = normalizeModelGatewayUrl(baseUrl);
-        loadPersistedModelAliases(cacheKey);
-        const cached = modelAliasCache.get(cacheKey);
-        if (cached && (Date.now() - cached.fetchedAt < MODEL_ALIAS_TTL_MS)) {
-            return cached.aliases[family] || modelAliasFallbacks.get(cacheKey)?.[family] || BOOTSTRAP_MODEL_ALIASES[family];
-        }
-        return modelAliasFallbacks.get(cacheKey)?.[family] || BOOTSTRAP_MODEL_ALIASES[family];
-    }
-    return BOOTSTRAP_MODEL_ALIASES[family];
-}
 /**
  * 为支持 1M 上下文的模型追加 `[1m]` 后缀——仅在交给 SDK query() 时调用。
  * 目录与校验层始终使用不带后缀的基础 ID，避免与网关 /models 返回值（无 `[1m]`）冲突。
@@ -531,10 +418,6 @@ function applyContextWindow(modelId) {
         return `${modelId}[1m]`;
     return modelId;
 }
-/** 解析别名 + 追加 1M 后缀，得到最终交给 SDK 的 model 串。 */
-function resolveSdkModel(model, baseUrl) {
-    return applyContextWindow(resolveModelAlias(model, baseUrl));
-}
 class MessageStream {
     queue = [];
     waiting = null;
@@ -692,9 +575,10 @@ export class AgentRunner {
         this.agentAid = runtime?.agentAid ?? legacy?.['evolcoreAgentAid'];
         this.agentConfig = runtime?.agentConfig ?? legacy?.['evolcoreAgentConfig'];
         this.onSessionIdUpdate = onSessionIdUpdate;
+        this.claudeExecutablePath = resolveBundledClaudeExecutable();
         if (config) {
             const anthropic = resolveAnthropicConfig(config);
-            this.claudeExecutablePath = anthropic.pathToClaudeCodeExecutable;
+            this.claudeExecutablePath = anthropic.pathToClaudeCodeExecutable || this.claudeExecutablePath;
             this.customHeaders = buildModelRequestHeaders({
                 baseagent: 'claude',
                 baseUrl: anthropic.baseUrl,
@@ -780,31 +664,22 @@ export class AgentRunner {
             },
         };
     }
+    catalogConnection() {
+        return { baseUrl: this.baseUrl, apiKey: this.apiKey, headers: this.customHeaders, queryParams: this.customQueryParams };
+    }
+    getModelCatalog() {
+        return getRunnerCatalog('claude', this.agentAid, this.catalogConnection());
+    }
     async listModels() {
-        if (this.baseUrl) {
-            const cacheKey = normalizeModelGatewayUrl(this.baseUrl);
-            loadPersistedModelAliases(cacheKey);
-            let cached = modelAliasCache.get(cacheKey);
-            const stale = !cached || (Date.now() - cached.fetchedAt > MODEL_ALIAS_TTL_MS);
-            // 缓存为空（首次打开）→ 等待刷新；缓存仅过期 → 后台刷新不阻塞
-            if (!cached) {
-                await refreshModelAliases(this.baseUrl, this.apiKey, this.customHeaders);
-                cached = modelAliasCache.get(cacheKey);
-            }
-            else if (stale) {
-                refreshModelAliases(this.baseUrl, this.apiKey, this.customHeaders);
-            }
-            // 有缓存时返回网关 /models 的全量原始 ID
-            if (cached && cached.ids.length > 0)
-                return cached.ids;
-        }
-        // 无 baseUrl / 刷新超时或失败 → 回退短别名
-        const fallback = this.baseUrl ? modelAliasFallbacks.get(normalizeModelGatewayUrl(this.baseUrl)) : undefined;
-        return Object.values({ ...BOOTSTRAP_MODEL_ALIASES, ...fallback });
-    }
-    /** 将短别名解析为当前代理实际使用的完整 model ID（仅用于展示，不改变持久化值） */
+        const catalog = await this.getModelCatalog();
+        assertCatalogSelectable(catalog);
+        return catalog.models.map(m => m.id);
+    }
     resolveModelId(model) {
-        return resolveModelAlias(model, this.baseUrl);
+        return resolveCatalogModel(peekRunnerCatalog('claude', this.agentAid, this.catalogConnection()), model);
+    }
+    async getAvailableEfforts(model) {
+        return catalogEfforts(await this.getModelCatalog(), model, 'claude');
     }
     setEffort(effort) {
         this.effort = effort;
@@ -1454,8 +1329,9 @@ export class AgentRunner {
      * SDK 原始事件 → 标准 AgentEvent 转换
      * 所有 SDK 特有的事件类型引用封装在此方法内
      */
-    async *transformStream(sdkStream, sessionId, inputId, callModel, callEffort, sdkModel, isResuming = false, sandboxSettingsFile, permissionMode, turn) {
+    async *transformStream(sdkStream, sessionId, inputId, callModel, callEffort, sdkModel, isResuming = false, sandboxSettingsFile, permissionMode, turn, projectPath = process.cwd(), topicBinding = false) {
         let lastSessionId;
+        let pendingSessionId;
         let hasTurnActivity = false;
         let ignoredPreTurnResult = false;
         let waitingForBackgroundCompletion = false;
@@ -1475,19 +1351,41 @@ export class AgentRunner {
         let lastAssistantUuid;
         // 流式收集各次大模型调用（fallback：SDK iterations 为空时使用）
         const collectedCalls = [];
+        const activatePendingSession = async (waitForFile) => {
+            const candidate = pendingSessionId;
+            if (!candidate)
+                return undefined;
+            if (!isResuming && topicBinding) {
+                const ready = waitForFile
+                    ? await waitForClaudeSessionFile(projectPath, candidate)
+                    : isClaudeSessionFileReady(projectPath, candidate);
+                if (!ready)
+                    return undefined;
+            }
+            if (!await this.acceptDiscoveredSessionId(sessionId, candidate, turn)) {
+                logger.warn(`[AgentRunner] Rejected stale backend discovery: sessionId=${sessionId} backend=${candidate} turn=${turn?.turnId ?? 'legacy'}`);
+                const error = new Error('backend discovery rejected by active turn lease');
+                error.code = 'TOPIC_BACKEND_DISCOVERY_REJECTED';
+                throw error;
+            }
+            pendingSessionId = undefined;
+            return candidate;
+        };
         try {
             for await (const event of sdkStream) {
+                const activatedBeforeEvent = await activatePendingSession(false);
+                if (activatedBeforeEvent)
+                    yield { type: 'session_id', sessionId: activatedBeforeEvent };
                 // 提取 session_id（任意 SDK 事件都可能携带）
                 if (event.session_id && event.session_id !== lastSessionId) {
                     lastSessionId = event.session_id;
-                    if (await this.acceptDiscoveredSessionId(sessionId, event.session_id, turn)) {
-                        yield { type: 'session_id', sessionId: event.session_id };
+                    pendingSessionId = event.session_id;
+                    const activated = await activatePendingSession(event.type === 'result');
+                    if (activated) {
+                        yield { type: 'session_id', sessionId: activated };
                     }
-                    else {
-                        logger.warn(`[AgentRunner] Rejected stale backend discovery: sessionId=${sessionId} backend=${event.session_id} turn=${turn?.turnId ?? 'legacy'}`);
-                        const error = new Error('backend discovery rejected by active turn lease');
-                        error.code = 'TOPIC_BACKEND_DISCOVERY_REJECTED';
-                        throw error;
+                    else if (!isResuming) {
+                        logger.info(`[AgentRunner] Deferring backend activation until Claude session file is durable: sessionId=${sessionId} backend=${event.session_id}`);
                     }
                 }
                 if (event.type === 'user' && event.uuid === inputId) {
@@ -1582,7 +1480,17 @@ export class AgentRunner {
                 }
                 if (event.type === 'stream_event') {
                     const streamEvent = event.event;
-                    if (streamEvent?.type === 'message_start' && streamEvent.message?.usage) {
+                    if (streamEvent?.type === 'content_block_start'
+                        && (streamEvent.content_block?.type === 'thinking' || streamEvent.content_block?.type === 'redacted_thinking')) {
+                        hasTurnActivity = true;
+                        yield { type: 'heartbeat', source: 'reasoning', turn: turnCount || undefined };
+                    }
+                    else if (streamEvent?.type === 'content_block_delta'
+                        && streamEvent.delta?.type === 'thinking_delta') {
+                        hasTurnActivity = true;
+                        yield { type: 'heartbeat', source: 'reasoning', turn: turnCount || undefined };
+                    }
+                    else if (streamEvent?.type === 'message_start' && streamEvent.message?.usage) {
                         hasTurnActivity = true;
                         lastAssistantWasSynthetic = streamEvent.message.model === '<synthetic>';
                         lastModelCall = {
@@ -1616,6 +1524,13 @@ export class AgentRunner {
                     }
                     continue;
                 }
+                // During redacted thinking Claude may emit token estimates instead of
+                // readable thinking deltas. They still prove the model is active.
+                if (event.type === 'system' && event.subtype === 'thinking_tokens') {
+                    hasTurnActivity = true;
+                    yield { type: 'heartbeat', source: 'reasoning', turn: turnCount || undefined };
+                    continue;
+                }
                 // system: compact_boundary → compact
                 if (event.type === 'system' && event.subtype === 'compact_boundary') {
                     yield {
@@ -1686,7 +1601,11 @@ export class AgentRunner {
                     // 统计本轮 base agent 全部输出字符数（text + tool_use input）
                     let turnOutputChars = 0;
                     for (const content of event.message.content) {
-                        if (content.type === 'tool_use') {
+                        if (content.type === 'thinking' || content.type === 'redacted_thinking') {
+                            hasTurnActivity = true;
+                            yield { type: 'heartbeat', source: 'reasoning', turn: turnCount || undefined };
+                        }
+                        else if (content.type === 'tool_use') {
                             const inputStr = typeof content.input === 'string' ? content.input : JSON.stringify(content.input || '');
                             turnOutputChars += inputStr.length;
                         }
@@ -1729,6 +1648,12 @@ export class AgentRunner {
                 }
                 // result → complete（含 permission_denials 提取）
                 if (event.type === 'result') {
+                    // The SDK may announce session_id on the initial system event and omit
+                    // it from the terminal result. Give the transcript a short grace
+                    // period here before deciding that a topic backend is unavailable.
+                    const activatedAtResult = await activatePendingSession(true);
+                    if (activatedAtResult)
+                        yield { type: 'session_id', sessionId: activatedAtResult };
                     // Most SDK streams surface denials as user-message tool_result blocks.
                     // The terminal summary is only a fallback for incomplete streams.
                     if (Array.isArray(event.permission_denials)) {
@@ -1858,6 +1783,15 @@ export class AgentRunner {
                         modelCalls,
                         assistantUuid: lastAssistantUuid,
                     };
+                    // A topic binding must never outlive the provider transcript that can
+                    // resume it. If Claude reports success before its session file becomes
+                    // durable, fail this turn while leaving the topic unbound; /renew is
+                    // then available for older sessions that already contain a bad bind.
+                    if (!event.is_error && topicBinding && pendingSessionId) {
+                        const error = new Error(`bound topic backend is unavailable: ${pendingSessionId}`);
+                        error.code = 'TOPIC_BACKEND_UNAVAILABLE';
+                        throw error;
+                    }
                     // Fatal results belong to the query transport itself and must terminate
                     // even when the current input was not echoed back by the CLI.
                     if (event.is_error) {
@@ -1967,13 +1901,9 @@ export class AgentRunner {
         // 记录当前 evolcore session ID，用于 Agent ctl 环境变量注入
         // 同步用户级配置到内存
         this.syncFromUserSettings();
-        // 异步刷新模型别名缓存（fire-and-forget，不阻塞查询）
+        // Run preparation and model menus resolve aliases from the same snapshot.
+        const runCatalog = await this.getModelCatalog();
         if (this.baseUrl) {
-            const cacheKey = normalizeModelGatewayUrl(this.baseUrl);
-            const cached = modelAliasCache.get(cacheKey);
-            if (!cached || (Date.now() - cached.fetchedAt > MODEL_ALIAS_TTL_MS)) {
-                refreshModelAliases(this.baseUrl, this.apiKey, this.customHeaders);
-            }
             // 顺带预热网关价格缓存（1h TTL），让本轮结束写库时已就绪
             const pricing = gatewayPricingCache.get(this.baseUrl);
             if (!pricing || (Date.now() - pricing.fetchedAt > GATEWAY_PRICING_TTL_MS)) {
@@ -2539,7 +2469,7 @@ export class AgentRunner {
         else {
             logger.info(`[AgentRunner] systemPromptAppend: none`);
         }
-        const sdkModel = resolveSdkModel(callModel, this.baseUrl);
+        const sdkModel = applyContextWindow(resolveCatalogModel(runCatalog, callModel));
         const capabilityOptions = await this.resolveCapabilityRunOptions(projectPath);
         const managedSettings = callPermissionMode === 'fullaccess'
             ? undefined
@@ -2814,7 +2744,7 @@ export class AgentRunner {
             this.interruptFns.set(sessionId, () => sdkStream.interrupt());
         }
         // 返回标准 AgentEvent 流（重试由 MessageProcessor 层负责）
-        const transformed = this.transformStream(sdkStream, sessionId, inputId, callModel, callEffort, sdkModel, !!agentSessionId, sandboxSettingsFile, callPermissionMode, modelOverride?.turn);
+        const transformed = this.transformStream(sdkStream, sessionId, inputId, callModel, callEffort, sdkModel, !!agentSessionId, sandboxSettingsFile, callPermissionMode, modelOverride?.turn, projectPath, topicBinding);
         const self = this;
         return (async function* () {
             try {
@@ -2946,16 +2876,19 @@ export class AgentRunner {
             }
         });
     }
-    runSessionCommand(prompt, agentSessionId, projectPath, modelOverride) {
-        const callModel = modelOverride?.model || this.model;
+    async runSessionCommand(prompt, agentSessionId, projectPath, modelOverride, useModel = true) {
+        const callModel = modelOverride?.model || (useModel ? this.model : undefined);
         const callEffort = (modelOverride?.effortMode === 'model_default'
             ? undefined
-            : modelOverride?.effort ?? this.effort);
+            : modelOverride?.effort ?? (useModel ? this.effort : undefined));
+        const catalog = useModel ? await this.getModelCatalog() : undefined;
+        if (catalog)
+            assertCatalogSelectable(catalog);
         return query({
             prompt,
             options: {
                 cwd: projectPath,
-                model: resolveSdkModel(callModel, this.baseUrl),
+                ...(catalog && callModel ? { model: applyContextWindow(resolveCatalogModel(catalog, callModel)) } : {}),
                 resume: agentSessionId,
                 maxTurns: 1,
                 tools: [],
@@ -2964,9 +2897,12 @@ export class AgentRunner {
                 strictMcpConfig: true,
                 settingSources: [],
                 managedSettings: buildClaudeManagedLockdownSettings(),
-                ...(callEffort ? { effort: callEffort } : {}),
+                ...(catalog && callEffort ? { effort: callEffort } : {}),
                 permissionMode: this.toSdkPermissionMode(),
-                env: this.getAgentEnv()
+                env: this.getAgentEnv(),
+                ...(this.claudeExecutablePath
+                    ? { pathToClaudeCodeExecutable: this.claudeExecutablePath }
+                    : {})
             }
         });
     }
@@ -2979,7 +2915,7 @@ export class AgentRunner {
         let lastEvent;
         try {
             logger.info(`[AgentRunner] Compacting session: session=${sessionId} agent=${agentSessionId} project=${projectPath}`);
-            const stream = this.runSessionCommand('/compact', agentSessionId, projectPath, modelOverride);
+            const stream = await this.runSessionCommand('/compact', agentSessionId, projectPath, modelOverride);
             this.activeStreams.set(sessionId, stream);
             try {
                 let boundary;
@@ -3049,7 +2985,9 @@ export class AgentRunner {
     async clearSession(sessionId, agentSessionId, projectPath) {
         try {
             logger.info(`[AgentRunner] Clearing session via SDK: ${agentSessionId}`);
-            const stream = this.runSessionCommand('/clear', agentSessionId, projectPath);
+            // Clearing is a backend lifecycle operation. It does not depend on any
+            // Session model or model configuration/selection.
+            const stream = await this.runSessionCommand('/clear', agentSessionId, projectPath, undefined, false);
             this.activeStreams.set(sessionId, stream);
             try {
                 let cleared = false;
@@ -3216,6 +3154,7 @@ export class AgentRunner {
                 strictMcpConfig: true,
                 settingSources: [],
                 managedSettings: buildClaudeManagedLockdownSettings(),
+                ...(this.claudeExecutablePath ? { pathToClaudeCodeExecutable: this.claudeExecutablePath } : {}),
                 permissionMode: this.toSdkPermissionMode(),
                 stderr: (data) => { stderrChunks.push(data); },
                 env: this.getAgentEnv(),