minimal-agent 0.12.0 → 0.14.0

package/src/config/configService.js

@@ -1,7 +1,51 @@
 import { randomUUID } from 'node:crypto';
-import { readMinimalAgentConfig, updateMinimalAgentConfig, defaultMaxTokens, DEFAULT_SUBAGENTS_CONFIG, DEFAULT_BROWSER_CONFIG, DEFAULT_COMPUTER_USE_CONFIG, } from './configFile.js';
+import { modelRefFromLegacy, } from '../modelRef.js';
+import { fetchOnlineModels, loadTeamCredentials, resolveOnlineModel, } from '../team/auth.js';
+import { DEFAULT_ADVISOR_CONFIG, DEFAULT_BROWSER_CONFIG, DEFAULT_COMPUTER_USE_CONFIG, DEFAULT_SUBAGENTS_CONFIG, defaultMaxTokens, readMinimalAgentConfig, updateMinimalAgentConfig, } from './configFile.js';
 import { CONFIG_LIMITS, normalizeLimited } from './numericLimits.js';
 const DEFAULT_CONTEXT_WINDOW = 128_000;
+function gatewayFallbackReason(model, error) {
+    const state = model?.availability?.state;
+    if (state === 'quota_exhausted' || state === 'concurrency_exceeded')
+        return 'quota_exhausted';
+    if (state === 'model_disabled' || state === 'disabled')
+        return 'model_disabled';
+    if (state === 'device_expired')
+        return 'credential_expired';
+    if (state === 'not_authorized')
+        return 'grant_revoked';
+    if (state === 'server_offline' || state === 'offline')
+        return 'offline';
+    const message = error instanceof Error ? error.message : '';
+    if (message.includes('DEVICE_REVOKED') || message.includes('401'))
+        return 'credential_expired';
+    if (message.includes('MODEL_UNAVAILABLE') || message.includes('403'))
+        return 'grant_revoked';
+    return 'offline';
+}
+function gatewayProviderFromModel(credentials, model) {
+    return {
+        name: model.displayName || model.model,
+        source: 'gateway',
+        remoteModelId: model.id,
+        gatewayUrl: credentials.serverUrl,
+        gatewayToken: credentials.deviceToken,
+        gatewayMaxToolCategories: model.maxToolCategories,
+        gatewayDefaultToolCategories: model.defaultToolCategories,
+        // Deprecated compatibility field: before the explicit max/default/session
+        // split this field was used as the provider boundary. Keep its safe
+        // default as the server maximum; the current Session selection is applied
+        // per turn by runAgentTurn/useChat.
+        gatewayToolCategories: model.maxToolCategories,
+        model: model.model,
+        contextWindow: model.contextWindow,
+        maxTokens: model.maxTokens,
+        apiFormat: model.apiFormat,
+        supportsVision: model.supportsVision,
+        gatewayCapabilities: model.capabilities,
+        promptCache: { mode: 'disabled' },
+    };
+}
 function positiveInt(value, fallback) {
     const parsed = Number.parseInt(value ?? '', 10);
     return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
@@ -26,14 +70,20 @@ function configFromEnv() {
         return null;
     const tools = {};
     if (process.env.TAVILY_API_KEY)
-        tools.webSearch = { provider: 'tavily', apiKey: process.env.TAVILY_API_KEY };
-    if (process.env.OPENAI_IMAGE_BASE_URL && process.env.OPENAI_IMAGE_API_KEY && process.env.OPENAI_IMAGE_MODEL) {
+        tools.webSearch = {
+            provider: 'tavily',
+            apiKey: process.env.TAVILY_API_KEY,
+        };
+    if (process.env.OPENAI_IMAGE_BASE_URL &&
+        process.env.OPENAI_IMAGE_API_KEY &&
+        process.env.OPENAI_IMAGE_MODEL) {
         tools.imageGeneration = {
             provider: process.env.OPENAI_IMAGE_PROVIDER ?? 'openai',
             baseURL: process.env.OPENAI_IMAGE_BASE_URL,
             apiKey: process.env.OPENAI_IMAGE_API_KEY,
             model: process.env.OPENAI_IMAGE_MODEL,
-            protocol: process.env.OPENAI_IMAGE_PROTOCOL === 'chat' || process.env.OPENAI_IMAGE_PROTOCOL === 'images'
+            protocol: process.env.OPENAI_IMAGE_PROTOCOL === 'chat' ||
+                process.env.OPENAI_IMAGE_PROTOCOL === 'images'
                 ? process.env.OPENAI_IMAGE_PROTOCOL
                 : 'auto',
         };
@@ -41,7 +91,11 @@ function configFromEnv() {
     if (process.env.OPENROUTER_API_KEY)
         tools.openRouter = { apiKey: process.env.OPENROUTER_API_KEY };
     if (process.env.MINIMAX_API_KEY && process.env.MINIMAX_GROUP_ID) {
-        tools.textToSpeech = { provider: 'minimax', apiKey: process.env.MINIMAX_API_KEY, groupId: process.env.MINIMAX_GROUP_ID };
+        tools.textToSpeech = {
+            provider: 'minimax',
+            apiKey: process.env.MINIMAX_API_KEY,
+            groupId: process.env.MINIMAX_GROUP_ID,
+        };
     }
     const compactRatio = Number(process.env.MINIMAL_AGENT_COMPACT_RATIO);
     const name = process.env.MINIMAL_AGENT_PROVIDER ?? 'env';
@@ -70,13 +124,14 @@ function configFromEnv() {
         version: 4,
         models: [envModel],
         baseModelId: envModel.id,
+        teamServerUrl: process.env.KAKADEAI_SOCIAL_SERVER_URL?.trim() || null,
         ...(compactRatio > 0 && compactRatio <= 1 ? { compactRatio } : {}),
         subagents: {
             ...DEFAULT_SUBAGENTS_CONFIG,
             maxCallsPerTurn: positiveInt(process.env.AGENT_TOOL_MAX_CALLS_PER_TURN, 6),
             maxConcurrent: positiveInt(process.env.AGENT_TOOL_MAX_CONCURRENT, 3),
             timeoutMs: positiveInt(process.env.AGENT_TOOL_TIMEOUT_MS, 1_800_000),
-            exploreMaxTurns: positiveInt(process.env.AGENT_TOOL_EXPLORE_MAX_TURNS, 50),
+            exploreMaxTurns: positiveInt(process.env.AGENT_TOOL_EXPLORE_MAX_TURNS, 200),
             generalMaxTurns: positiveInt(process.env.AGENT_TOOL_GENERAL_MAX_TURNS, 100),
         },
         browser: DEFAULT_BROWSER_CONFIG,
@@ -92,6 +147,7 @@ function configFromEnv() {
 }
 function resolveProvider(entry, compactRatio) {
     return {
+        source: 'local',
         name: entry.displayName ?? entry.model,
         baseURL: entry.baseURL,
         apiKey: entry.apiKey,
@@ -100,15 +156,26 @@ function resolveProvider(entry, compactRatio) {
         maxTokens: entry.maxTokens ?? defaultMaxTokens(entry.contextWindow),
         apiFormat: entry.apiFormat,
         supportsVision: entry.supportsVision !== false,
+        ...(entry.supportsJsonSchema !== undefined
+            ? { supportsJsonSchema: entry.supportsJsonSchema }
+            : {}),
         promptCache: entry.promptCache ?? { mode: 'auto' },
         ...(compactRatio !== undefined ? { compactRatio } : {}),
+        // cache_edits 式回收：仅 Anthropic 格式 + 显式 env 开启时生效（非公开协议，
+        // 依赖支持该扩展的网关端点；语义与默认值说明见 types.ts Provider.cacheEdits）
+        ...(entry.apiFormat === 'anthropic' &&
+            process.env.MINIMAL_AGENT_CACHE_EDITS === '1'
+            ? { cacheEdits: true }
+            : {}),
     };
 }
 function mergeRecord(base, patch) {
     const out = { ...(base ?? {}) };
     for (const [key, value] of Object.entries(patch)) {
         if (value && typeof value === 'object' && !Array.isArray(value)) {
-            out[key] = mergeRecord(out[key] && typeof out[key] === 'object' && !Array.isArray(out[key]) ? out[key] : undefined, value);
+            out[key] = mergeRecord(out[key] && typeof out[key] === 'object' && !Array.isArray(out[key])
+                ? out[key]
+                : undefined, value);
         }
         else if (value !== undefined)
             out[key] = value;
@@ -118,6 +185,13 @@ function mergeRecord(base, patch) {
 function hasEntries(value) {
     return !!value && Object.keys(value).length > 0;
 }
+/** Remove an optional config key while keeping the persisted object sparse. */
+function omitKey(value, key) {
+    if (!value)
+        return value;
+    const { [key]: _removed, ...rest } = value;
+    return rest;
+}
 function applyModelsPatch(models, ops) {
     let out = [...models];
     const now = Date.now();
@@ -137,9 +211,14 @@ function applyModelsPatch(models, ops) {
                 baseURL,
                 apiKey,
                 model: modelId,
-                contextWindow: m.contextWindow && m.contextWindow > 0 ? m.contextWindow : DEFAULT_CONTEXT_WINDOW,
+                contextWindow: m.contextWindow && m.contextWindow > 0
+                    ? m.contextWindow
+                    : DEFAULT_CONTEXT_WINDOW,
                 ...(m.maxTokens ? { maxTokens: m.maxTokens } : {}),
                 supportsVision: m.supportsVision !== false,
+                ...(m.supportsJsonSchema !== undefined
+                    ? { supportsJsonSchema: m.supportsJsonSchema }
+                    : {}),
                 promptCache: m.promptCache ?? { mode: 'auto' },
                 enabled: m.enabled ?? true,
                 createdAt: now,
@@ -154,13 +233,26 @@ function applyModelsPatch(models, ops) {
             const patch = item.patch;
             const next = {
                 ...existing,
-                ...(patch.apiFormat ? { apiFormat: patch.apiFormat === 'anthropic' ? 'anthropic' : 'openai' } : {}),
-                ...(patch.displayName !== undefined ? { displayName: patch.displayName.trim() || undefined } : {}),
+                ...(patch.apiFormat
+                    ? {
+                        apiFormat: patch.apiFormat === 'anthropic' ? 'anthropic' : 'openai',
+                    }
+                    : {}),
+                ...(patch.displayName !== undefined
+                    ? { displayName: patch.displayName.trim() || undefined }
+                    : {}),
                 ...(patch.baseURL?.trim() ? { baseURL: patch.baseURL.trim() } : {}),
                 ...(patch.model?.trim() ? { model: patch.model.trim() } : {}),
                 ...(patch.contextWindow ? { contextWindow: patch.contextWindow } : {}),
-                ...(patch.maxTokens !== undefined ? { maxTokens: patch.maxTokens || undefined } : {}),
-                ...(patch.supportsVision !== undefined ? { supportsVision: patch.supportsVision !== false } : {}),
+                ...(patch.maxTokens !== undefined
+                    ? { maxTokens: patch.maxTokens || undefined }
+                    : {}),
+                ...(patch.supportsVision !== undefined
+                    ? { supportsVision: patch.supportsVision !== false }
+                    : {}),
+                ...(patch.supportsJsonSchema !== undefined
+                    ? { supportsJsonSchema: patch.supportsJsonSchema }
+                    : {}),
                 ...(patch.promptCache ? { promptCache: patch.promptCache } : {}),
                 ...(patch.enabled !== undefined ? { enabled: patch.enabled } : {}),
                 updatedAt: now,
@@ -187,7 +279,8 @@ function applyConfigPatch(base, patch) {
     if (wasEmpty && baseModelId === null && models.length > 0)
         baseModelId = models[0].id;
     if (patch.baseModelId !== undefined) {
-        if (patch.baseModelId !== null && !models.some((entry) => entry.id === patch.baseModelId)) {
+        if (patch.baseModelId !== null &&
+            !models.some((entry) => entry.id === patch.baseModelId)) {
             throw new Error('要设为基座的模型不存在');
         }
         baseModelId = patch.baseModelId;
@@ -200,6 +293,11 @@ function applyConfigPatch(base, patch) {
         if (baseEntry.enabled === false)
             throw new Error('不能禁用当前基座模型，请先设置其他模型为基座');
     }
+    // 团队服务器地址：不像 baseModelId 那样要交叉校验（不引用 models[]），一个裸字符串。
+    let teamServerUrl = base?.teamServerUrl ?? null;
+    if (patch.teamServerUrl !== undefined) {
+        teamServerUrl = patch.teamServerUrl?.trim() || null;
+    }
     let advisor = base?.advisor;
     if (patch.advisor) {
         if (patch.advisor.clear) {
@@ -207,85 +305,113 @@ function applyConfigPatch(base, patch) {
         }
         else {
             advisor = {
-                enabled: patch.advisor.enabled ?? advisor?.enabled ?? true,
+                enabled: patch.advisor.enabled ?? advisor?.enabled ?? DEFAULT_ADVISOR_CONFIG.enabled,
                 mode: patch.advisor.mode ?? advisor?.mode ?? 'auto',
-                modelId: patch.advisor.modelId !== undefined ? patch.advisor.modelId : (advisor?.modelId ?? null),
+                modelId: patch.advisor.modelId !== undefined
+                    ? patch.advisor.modelId
+                    : (advisor?.modelId ?? null),
                 contextPolicy: 'full-relevant',
                 shareSensitive: patch.advisor.shareSensitive ?? advisor?.shareSensitive ?? false,
-                inputTokenBudget: normalizeLimited(patch.advisor.inputTokenBudget ?? advisor?.inputTokenBudget, CONFIG_LIMITS.advisorInputTokenBudget, 128_000),
-                timeoutMs: normalizeLimited(patch.advisor.timeoutMs ?? advisor?.timeoutMs, CONFIG_LIMITS.advisorTimeoutMs, 180_000),
+                inputTokenBudget: normalizeLimited(patch.advisor.inputTokenBudget ?? advisor?.inputTokenBudget, CONFIG_LIMITS.advisorInputTokenBudget, DEFAULT_ADVISOR_CONFIG.inputTokenBudget),
+                timeoutMs: normalizeLimited(patch.advisor.timeoutMs ?? advisor?.timeoutMs, CONFIG_LIMITS.advisorTimeoutMs, DEFAULT_ADVISOR_CONFIG.timeoutMs),
             };
         }
     }
     // 顾问引用的模型若已被删除或禁用，级联置空（软失联——解析层已把 null/悬空 id 当
     // 「未配置」优雅处理，不留死链接；这与基座模型的硬阻止是刻意的不对称：顾问本来就是
     // 可降级的第二意见，不像基座那样「没有就整个应用跑不起来」）。
-    if (advisor?.modelId) {
+    if (advisor?.modelId && !advisor.modelId.startsWith('online:')) {
         const referenced = models.find((entry) => entry.id === advisor.modelId);
         if (!referenced || referenced.enabled === false)
             advisor = { ...advisor, modelId: null };
     }
+    const workflowModels = {
+        ...(base?.workflowModels ?? {}),
+    };
+    for (const [role, modelId] of Object.entries(patch.workflowModels ?? {})) {
+        if (modelId)
+            workflowModels[role] = modelId;
+        else
+            delete workflowModels[role];
+    }
+    for (const role of Object.keys(workflowModels)) {
+        const modelId = workflowModels[role];
+        const configured = models.find((entry) => entry.id === modelId);
+        if (!configured || configured.enabled === false)
+            delete workflowModels[role];
+    }
     // 比例类：保留 4 位小数（= 百分比 2 位），否则 UI 上下箭头按 0.01 步进会累加出
     // `0.8500000000000001` 这种浮点脏值直接写进 config.json。
     const compactRatio = patch.compactRatio !== undefined
-        ? (patch.compactRatio > 0 && patch.compactRatio <= 1
+        ? patch.compactRatio > 0 && patch.compactRatio <= 1
             ? normalizeLimited(patch.compactRatio, CONFIG_LIMITS.compactRatio, CONFIG_LIMITS.compactRatio.max)
-            : undefined)
+            : undefined
         : base?.compactRatio;
-    const tools = { ...(base?.tools ?? {}) };
+    let tools = { ...(base?.tools ?? {}) };
     const drafts = structuredClone(base?.drafts ?? {});
     const toolPatch = patch.tools;
     if (toolPatch?.webSearch) {
         if (toolPatch.webSearch.clear) {
-            delete tools.webSearch;
-            delete drafts.tools?.webSearch;
+            tools = omitKey(tools, 'webSearch') ?? {};
+            if (drafts.tools)
+                drafts.tools = omitKey(drafts.tools, 'webSearch');
         }
         else
-            tools.webSearch = mergeRecord(tools.webSearch, { provider: 'tavily', ...toolPatch.webSearch });
+            tools.webSearch = mergeRecord(tools.webSearch, {
+                provider: 'tavily',
+                ...toolPatch.webSearch,
+            });
     }
     if (toolPatch?.imageGeneration) {
         if (toolPatch.imageGeneration.clear) {
-            delete tools.imageGeneration;
-            delete drafts.tools?.imageGeneration;
+            tools = omitKey(tools, 'imageGeneration') ?? {};
+            if (drafts.tools)
+                drafts.tools = omitKey(drafts.tools, 'imageGeneration');
         }
         else {
             const next = mergeRecord(tools.imageGeneration, toolPatch.imageGeneration);
             if (toolPatch.imageGeneration.clearApiKey)
                 next.apiKey = '';
-            delete next.clear;
-            delete next.clearApiKey;
-            if (!next.baseURL || !next.apiKey || !next.model)
+            const cleanNext = omitKey(omitKey(next, 'clear'), 'clearApiKey');
+            if (!cleanNext.baseURL || !cleanNext.apiKey || !cleanNext.model)
                 throw new Error('图片生成缺少 Base URL、API Key 或模型名称');
-            tools.imageGeneration = next;
+            tools.imageGeneration = cleanNext;
         }
     }
     if (toolPatch?.openRouter) {
         if (toolPatch.openRouter.clear) {
-            delete tools.openRouter;
-            delete drafts.tools?.openRouter;
+            tools = omitKey(tools, 'openRouter') ?? {};
+            if (drafts.tools)
+                drafts.tools = omitKey(drafts.tools, 'openRouter');
         }
         else
             tools.openRouter = mergeRecord(tools.openRouter, toolPatch.openRouter);
     }
     if (toolPatch?.textToSpeech) {
         if (toolPatch.textToSpeech.clear) {
-            delete tools.textToSpeech;
-            delete drafts.tools?.textToSpeech;
+            tools = omitKey(tools, 'textToSpeech') ?? {};
+            if (drafts.tools)
+                drafts.tools = omitKey(drafts.tools, 'textToSpeech');
         }
         else {
-            const next = mergeRecord(tools.textToSpeech, { provider: 'minimax', ...toolPatch.textToSpeech });
+            const next = mergeRecord(tools.textToSpeech, {
+                provider: 'minimax',
+                ...toolPatch.textToSpeech,
+            });
             if (toolPatch.textToSpeech.clearApiKey)
                 next.apiKey = '';
-            delete next.clear;
-            delete next.clearApiKey;
-            if (!next.apiKey || !next.groupId)
+            const cleanNext = omitKey(omitKey(next, 'clear'), 'clearApiKey');
+            if (!cleanNext.apiKey || !cleanNext.groupId)
                 throw new Error('MiniMax 语音缺少 API Key 或 Group ID');
-            tools.textToSpeech = next;
+            tools.textToSpeech = cleanNext;
         }
     }
     // 数字字段必须在**写入时**就按同一份边界规整——此前这里是裸 spread，读回时才被
     // parseSubagents 的边界收窄，于是「存进去 300、读出来 100」，UI 表现成静默变回原值。
-    const mergedSubagents = { ...(base?.subagents ?? DEFAULT_SUBAGENTS_CONFIG), ...(patch.subagents ?? {}) };
+    const mergedSubagents = {
+        ...(base?.subagents ?? DEFAULT_SUBAGENTS_CONFIG),
+        ...(patch.subagents ?? {}),
+    };
     const subagents = {
         ...mergedSubagents,
         maxCallsPerTurn: normalizeLimited(mergedSubagents.maxCallsPerTurn, CONFIG_LIMITS.subagentMaxCallsPerTurn, DEFAULT_SUBAGENTS_CONFIG.maxCallsPerTurn),
@@ -294,7 +420,11 @@ function applyConfigPatch(base, patch) {
         exploreMaxTurns: normalizeLimited(mergedSubagents.exploreMaxTurns, CONFIG_LIMITS.subagentExploreMaxTurns, DEFAULT_SUBAGENTS_CONFIG.exploreMaxTurns),
         generalMaxTurns: normalizeLimited(mergedSubagents.generalMaxTurns, CONFIG_LIMITS.subagentGeneralMaxTurns, DEFAULT_SUBAGENTS_CONFIG.generalMaxTurns),
     };
-    const browser = { ...(base?.browser ?? DEFAULT_BROWSER_CONFIG), ...(patch.browser ?? {}), profileId: 'default' };
+    const browser = {
+        ...(base?.browser ?? DEFAULT_BROWSER_CONFIG),
+        ...(patch.browser ?? {}),
+        profileId: 'default',
+    };
     const computerUse = {
         ...(base?.computerUse ?? DEFAULT_COMPUTER_USE_CONFIG),
         ...(patch.computerUse ?? {}),
@@ -302,12 +432,34 @@ function applyConfigPatch(base, patch) {
     computerUse.observationFrames = 1;
     computerUse.maxImagePixels = normalizeLimited(computerUse.maxImagePixels, CONFIG_LIMITS.computerUseMaxImagePixels, DEFAULT_COMPUTER_USE_CONFIG.maxImagePixels);
     if (!hasEntries(drafts.tools))
-        delete drafts.tools;
-    return { models, baseModelId, ...(compactRatio !== undefined ? { compactRatio } : {}), advisor, subagents, browser, computerUse, tools, ...(hasEntries(drafts) ? { drafts } : {}) };
+        drafts.tools = undefined;
+    return {
+        models,
+        baseModelId,
+        teamServerUrl,
+        ...(compactRatio !== undefined ? { compactRatio } : {}),
+        advisor,
+        // Preserve an explicit empty object through updateMinimalAgentConfig so
+        // removing the final role is distinguishable from an unrelated mutator
+        // that omitted this optional field.
+        workflowModels,
+        subagents,
+        browser,
+        computerUse,
+        tools,
+        ...(hasEntries(drafts) ? { drafts } : {}),
+    };
 }
 export class ConfigService {
-    snapshot = { source: 'none', readOnly: false, config: null, revision: 0 };
-    get revision() { return this.snapshot.revision; }
+    snapshot = {
+        source: 'none',
+        readOnly: false,
+        config: null,
+        revision: 0,
+    };
+    get revision() {
+        return this.snapshot.revision;
+    }
     async reload() {
         const envOnly = process.env.MINIMAL_AGENT_CONFIG_MODE === 'env';
         const json = envOnly ? null : await readMinimalAgentConfig();
@@ -317,11 +469,14 @@ export class ConfigService {
             readOnly: envOnly,
             config: json ?? env,
         };
-        const changed = this.snapshot.revision === 0
-            || this.snapshot.source !== next.source
-            || this.snapshot.readOnly !== next.readOnly
-            || JSON.stringify(this.snapshot.config) !== JSON.stringify(next.config);
-        this.snapshot = { ...next, revision: changed ? this.snapshot.revision + 1 : this.snapshot.revision };
+        const changed = this.snapshot.revision === 0 ||
+            this.snapshot.source !== next.source ||
+            this.snapshot.readOnly !== next.readOnly ||
+            JSON.stringify(this.snapshot.config) !== JSON.stringify(next.config);
+        this.snapshot = {
+            ...next,
+            revision: changed ? this.snapshot.revision + 1 : this.snapshot.revision,
+        };
         return this.getSnapshot();
     }
     async getSnapshot() {
@@ -336,21 +491,149 @@ export class ConfigService {
             return null;
         return resolveProvider(entry, config?.compactRatio);
     }
+    /**
+     * 团队登录服务器的默认地址：env 优先于 config.json，跟随 minimal-desktop 的
+     * `resolve_social_server()`（`src-tauri/src/lib.rs`）已验证的同一优先级——这两个
+     * 项目共享 `KAKADEAI_SOCIAL_SERVER_URL` 这一个环境变量名，语义必须一致，不能
+     * minimal-agent 这边搞成 config 优先。
+     *
+     * ⚠️ 不能简单读 `getSnapshot().config?.teamServerUrl`：那个 snapshot 在存在
+     * config.json 时完全不看 env（`reload()` 里 `config: json ?? env`，env 只在
+     * **没有** config.json 时才整体生效），会让"config.json 存在但没配地址、同时设了
+     * env"这种常见场景里 env 被错误地忽略。这里必须独立读 `process.env`。
+     *
+     * 返回值带 `source`，供诊断和私有部署使用；正式用户不需要接触服务器地址。
+     */
+    async resolveTeamServerUrl() {
+        const rawEnvValue = process.env.KAKADEAI_SOCIAL_SERVER_URL;
+        if (rawEnvValue !== undefined)
+            return {
+                value: rawEnvValue.trim() || null,
+                source: 'env',
+            };
+        const { config } = await this.getSnapshot();
+        const configValue = config?.teamServerUrl ?? null;
+        return configValue
+            ? { value: configValue, source: 'config' }
+            : { value: 'https://kakadeai.com', source: 'default' };
+    }
     async providerForModel(modelId) {
         if (!modelId)
             return this.provider();
+        const ref = modelRefFromLegacy(modelId);
+        if (ref.source === 'gateway') {
+            const resolved = await this.providerForRef(ref);
+            return resolved;
+        }
         const { config } = await this.getSnapshot();
         const entry = config?.models.find((m) => m.id === modelId);
         if (!entry?.apiKey)
             return null;
         return resolveProvider(entry, config?.compactRatio);
     }
+    /** Resolve a portable workflow role from fresh cross-process config. */
+    async providerForWorkflowRole(role) {
+        const { config } = await this.reload();
+        const modelId = config?.workflowModels?.[role];
+        return modelId ? this.providerForModel(modelId) : null;
+    }
+    async providerForGatewayModel(modelId) {
+        // A remembered gateway model must not make standalone mode inspect the
+        // team credential file or attempt a network request.  The configured
+        // server is the explicit opt-in boundary; credentials are read only after
+        // it is present.
+        const configured = await this.resolveTeamServerUrl();
+        if (!configured.value)
+            return null;
+        const resolved = await resolveOnlineModel(modelId, configured.value ?? undefined).catch(() => null);
+        if (!resolved)
+            return null;
+        const { credentials, model } = resolved;
+        if (model.availability && model.availability.state !== 'available')
+            return null;
+        return gatewayProviderFromModel(credentials, model);
+    }
+    /** Resolve the persisted source-aware identity without making callers encode
+     * gateway selections as the legacy `online:<id>` string. */
+    async providerForRef(ref) {
+        if (!ref)
+            return this.provider();
+        return ref.source === 'gateway'
+            ? this.providerForGatewayModel(ref.modelId)
+            : this.providerForModel(ref.modelId);
+    }
+    /**
+     * Resolve a persisted model reference and retain the reason when a gateway
+     * model cannot be used.  The reason is intentionally kept at the local
+     * session boundary: it is UI/selection state, not a server-side session or
+     * prompt record.
+     */
+    async resolveModelRef(ref) {
+        if (!ref)
+            return {
+                provider: await this.providerForModel(null),
+                fallbackReason: null,
+            };
+        if (ref.source === 'local')
+            return {
+                provider: await this.providerForRef(ref),
+                fallbackReason: null,
+            };
+        const configured = await this.resolveTeamServerUrl();
+        if (!configured.value)
+            return { provider: null, fallbackReason: 'logged_out' };
+        const credentials = await loadTeamCredentials(configured.value);
+        if (!credentials)
+            return { provider: null, fallbackReason: 'logged_out' };
+        try {
+            const models = await fetchOnlineModels(credentials);
+            const model = models.find((item) => item.id === ref.modelId);
+            if (!model)
+                return { provider: null, fallbackReason: 'grant_revoked' };
+            if (model.availability?.state !== undefined &&
+                model.availability.state !== 'available')
+                return {
+                    provider: null,
+                    fallbackReason: gatewayFallbackReason(model),
+                };
+            return {
+                provider: gatewayProviderFromModel(credentials, model),
+                fallbackReason: null,
+            };
+        }
+        catch (error) {
+            return {
+                provider: null,
+                fallbackReason: gatewayFallbackReason(undefined, error),
+            };
+        }
+    }
+    /** Online defaults are server-owned and fetched only when team credentials
+     * exist.  No standalone launch calls this path. */
+    async onlineDefaultProvider() {
+        const configured = await this.resolveTeamServerUrl();
+        if (!configured.value)
+            return null;
+        const credentials = await import('../team/auth.js')
+            .then((module) => module.loadTeamCredentials(configured.value ?? undefined))
+            .catch(() => null);
+        if (!credentials)
+            return null;
+        const models = await import('../team/auth.js')
+            .then((module) => module.fetchOnlineModels(credentials))
+            .catch(() => []);
+        const model = models.find((item) => item.isDefault &&
+            (!item.availability || item.availability.state === 'available'));
+        if (!model)
+            return null;
+        return gatewayProviderFromModel(credentials, model);
+    }
     /** 带 apiKey 的原始列表——仅服务端内部消费（桌面端 store.ts 的 readConfig() 会脱敏成 ModelView）。 */
     async models() {
         return (await this.getSnapshot()).config?.models ?? [];
     }
     async model(id) {
-        return (await this.getSnapshot()).config?.models.find((entry) => entry.id === id) ?? null;
+        return ((await this.getSnapshot()).config?.models.find((entry) => entry.id === id) ?? null);
     }
     /**
      * 保留「未启用但已配置」和「完全未配置」两种返回值的区分——advisor.ts 的两条不同报错
@@ -368,10 +651,57 @@ export class ConfigService {
         const advisor = config?.advisor;
         if (!advisor?.modelId)
             return null;
+        const advisorRef = modelRefFromLegacy(advisor.modelId);
+        if (advisorRef.source === 'gateway') {
+            const provider = await this.providerForRef(advisorRef);
+            return provider
+                ? {
+                    ...advisor,
+                    provider,
+                    supportsVision: provider.supportsVision !== false,
+                }
+                : null;
+        }
         const entry = config.models.find((m) => m.id === advisor.modelId);
         if (!entry?.apiKey)
             return null;
-        return { ...advisor, provider: resolveProvider(entry), supportsVision: entry.supportsVision !== false };
+        return {
+            ...advisor,
+            provider: resolveProvider(entry),
+            supportsVision: entry.supportsVision !== false,
+        };
+    }
+    /**
+     * 同步版 advisor 可用性探测——仅用于 resolveAvailability 这类工具列表探测场景。
+     * 读当前内存快照（可能略滞后于磁盘最新值），但调用频率高、对实时性要求不高，
+     * 下一轮 LLM 请求前 configService.reload() 会刷新。
+     *
+     * 为什么不用 advisor() 的 fresh reload：
+     * resolveAvailability 是在主循环构造工具集时同步调用的，不能 await；
+     * 而且每次工具集构造都读盘的话开销太大（主循环每轮都可能构造一次）。
+     */
+    advisorAvailabilitySync() {
+        const config = this.snapshot.config;
+        const advisor = config?.advisor;
+        if (!advisor?.modelId)
+            return { enabled: false, mode: 'auto', modelId: null, configured: false };
+        if (modelRefFromLegacy(advisor.modelId).source === 'gateway') {
+            return {
+                enabled: advisor.enabled !== false,
+                mode: advisor.mode === 'manual' ? 'manual' : 'auto',
+                modelId: advisor.modelId,
+                configured: true,
+            };
+        }
+        const entry = config?.models?.find((m) => m.id === advisor.modelId);
+        if (!entry?.apiKey)
+            return { enabled: false, mode: 'auto', modelId: null, configured: false };
+        return {
+            enabled: advisor.enabled !== false,
+            mode: advisor.mode === 'manual' ? 'manual' : 'auto',
+            modelId: advisor.modelId,
+            configured: true,
+        };
     }
     async subagents() {
         return (await this.reload()).config?.subagents ?? DEFAULT_SUBAGENTS_CONFIG;
@@ -380,7 +710,7 @@ export class ConfigService {
         return (await this.reload()).config?.browser ?? DEFAULT_BROWSER_CONFIG;
     }
     async computerUse() {
-        return (await this.reload()).config?.computerUse ?? DEFAULT_COMPUTER_USE_CONFIG;
+        return ((await this.reload()).config?.computerUse ?? DEFAULT_COMPUTER_USE_CONFIG);
     }
     async tool(key) {
         return (await this.reload()).config?.tools[key];
@@ -388,10 +718,22 @@ export class ConfigService {
     async toolStatus() {
         const tools = (await this.reload()).config?.tools ?? {};
         return {
-            webSearch: { state: tools.webSearch ? 'configured' : 'unconfigured', configured: !!tools.webSearch },
-            imageGeneration: { state: tools.imageGeneration ? 'configured' : 'unconfigured', configured: !!tools.imageGeneration },
-            openRouter: { state: tools.openRouter ? 'configured' : 'unconfigured', configured: !!tools.openRouter },
-            textToSpeech: { state: tools.textToSpeech ? 'configured' : 'unconfigured', configured: !!tools.textToSpeech },
+            webSearch: {
+                state: tools.webSearch ? 'configured' : 'unconfigured',
+                configured: !!tools.webSearch,
+            },
+            imageGeneration: {
+                state: tools.imageGeneration ? 'configured' : 'unconfigured',
+                configured: !!tools.imageGeneration,
+            },
+            openRouter: {
+                state: tools.openRouter ? 'configured' : 'unconfigured',
+                configured: !!tools.openRouter,
+            },
+            textToSpeech: {
+                state: tools.textToSpeech ? 'configured' : 'unconfigured',
+                configured: !!tools.textToSpeech,
+            },
         };
     }
     async savePatch(patch) {
@@ -414,33 +756,55 @@ export class ConfigService {
         await updateMinimalAgentConfig((latest) => {
             let active = latest ?? current.config;
             if (patch.subagents)
-                active = { version: 4, ...applyConfigPatch(active, { subagents: patch.subagents }), savedAt: active.savedAt };
+                active = {
+                    version: 4,
+                    ...applyConfigPatch(active, { subagents: patch.subagents }),
+                    savedAt: active.savedAt,
+                };
             if (patch.computerUse)
-                active = { version: 4, ...applyConfigPatch(active, { computerUse: patch.computerUse }), savedAt: active.savedAt };
+                active = {
+                    version: 4,
+                    ...applyConfigPatch(active, { computerUse: patch.computerUse }),
+                    savedAt: active.savedAt,
+                };
             const drafts = structuredClone(active.drafts ?? {});
             for (const key of Object.keys(patch.tools ?? {})) {
                 const rawPiece = patch.tools[key];
                 if (!rawPiece)
                     continue;
-                const previous = (drafts.tools ?? {})[key];
+                const previous = drafts.tools?.[key];
                 const merged = mergeRecord(previous, rawPiece);
                 try {
-                    active = { version: 4, ...applyConfigPatch(active, { tools: { [key]: merged } }), savedAt: active.savedAt };
-                    delete drafts.tools?.[key];
+                    active = {
+                        version: 4,
+                        ...applyConfigPatch(active, {
+                            tools: { [key]: merged },
+                        }),
+                        savedAt: active.savedAt,
+                    };
+                    drafts.tools = omitKey(drafts.tools, key);
                 }
                 catch {
                     state = 'draft';
                     draftFields.push(key);
-                    (drafts.tools ??= {})[key] = merged;
+                    const toolDrafts = drafts.tools ?? {};
+                    toolDrafts[key] = merged;
+                    drafts.tools = toolDrafts;
                 }
             }
             if (!hasEntries(drafts.tools))
-                delete drafts.tools;
+                drafts.tools = undefined;
             return {
-                models: active.models, baseModelId: active.baseModelId,
-                ...(active.compactRatio !== undefined ? { compactRatio: active.compactRatio } : {}),
-                advisor: active.advisor, subagents: active.subagents, browser: active.browser,
-                computerUse: active.computerUse, tools: active.tools,
+                models: active.models,
+                baseModelId: active.baseModelId,
+                ...(active.compactRatio !== undefined
+                    ? { compactRatio: active.compactRatio }
+                    : {}),
+                advisor: active.advisor,
+                subagents: active.subagents,
+                browser: active.browser,
+                computerUse: active.computerUse,
+                tools: active.tools,
                 ...(hasEntries(drafts) ? { drafts } : {}),
             };
         });
@@ -449,14 +813,19 @@ export class ConfigService {
 }
 export const configService = new ConfigService();
 export const SENSITIVE_ENV_KEYS = new Set([
-    'MINIMAL_AGENT_API_KEY', 'TAVILY_API_KEY', 'OPENAI_IMAGE_API_KEY',
-    'OPENROUTER_API_KEY', 'MINIMAX_API_KEY', 'MINIMAX_GROUP_ID',
+    'MINIMAL_AGENT_API_KEY',
+    'TAVILY_API_KEY',
+    'OPENAI_IMAGE_API_KEY',
+    'OPENROUTER_API_KEY',
+    'MINIMAX_API_KEY',
+    'MINIMAX_GROUP_ID',
 ]);
 /** Child processes inherit normal runtime variables, never model or tool credentials. */
 export function sanitizeCredentialEnv(source = process.env) {
-    const env = { ...source };
-    for (const key of SENSITIVE_ENV_KEYS)
-        delete env[key];
+    let env = { ...source };
+    for (const key of SENSITIVE_ENV_KEYS) {
+        env = omitKey(env, key) ?? {};
+    }
     return env;
 }
 export async function trustedToolEnv(kind, service = configService) {
@@ -482,7 +851,7 @@ export async function trustedToolEnv(kind, service = configService) {
             if (cfg.protocol && cfg.protocol !== 'auto')
                 env.OPENAI_IMAGE_PROTOCOL = cfg.protocol;
             else
-                delete env.OPENAI_IMAGE_PROTOCOL;
+                env.OPENAI_IMAGE_PROTOCOL = undefined;
         }
     }
     else if (kind === 'openRouter') {