@ai-agent-forge/agent-forge 0.86.3 → 0.86.5

package/dist/core/sdk.js

@@ -2,7 +2,7 @@ import { existsSync, realpathSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { Agent, setDefaultStreamFn, } from "@agent-forge/agent-core";
-import { clampThinkingLevel, streamSimple } from "@agent-forge/ai/compat";
+import { clampThinkingLevel, streamSimple, } from "@agent-forge/ai/compat";
 import { createSubagentMailbox } from "@agent-forge/protocol/subagent";
 import { satisfies } from "semver";
 import { BUILTIN_CAPABILITY_PACKAGE_IDS } from "../capabilities/builtin.js";
@@ -20,6 +20,7 @@ import { formatNoModelsAvailableMessage } from "./auth-guidance.js";
 import { DEFAULT_THINKING_LEVEL } from "./defaults.js";
 import { discoverCapabilityPluginManifests, parseCapabilityPluginManifest } from "./extensions/capability-plugin.js";
 import { resolvePluginCapabilityOrder } from "./extensions/capability-runtime.js";
+import { installProviderFailoverPlugin, readProviderFailoverSettingsNode } from "./extensions/provider-failover.js";
 import { createCodingAgentFacade } from "./facade/coding-agent-facade.js";
 import { createCodingAgentRuntimeFacade, } from "./facade/coding-agent-runtime-facade.js";
 import { convertToLlm } from "./messages.js";
@@ -118,6 +119,18 @@ const SUBAGENT_DELEGATE_PACKAGE_ID = "agent-forge.plugin.subagent-delegate";
  * membership set entirely (禁用 = 不装配, plus one startup diagnostic).
  */
 const MEMORY_PACKAGE_ID = "agent-forge.plugin.memory";
+/**
+ * Plugin id of the standalone image-generation package (供应商能力槽位设计
+ * §3.3 装配注入): at load the assembler overrides its manifest config with the
+ * settings slot (`capabilities.imageGeneration`, validated fail-closed by
+ * `SettingsManager.getCapabilitiesSettings()`) plus the models.json image-model
+ * catalog snapshot (`imageModelCatalog`, projected by
+ * `ModelRuntime.getImageModelCatalog()`) — the exact config keys the package's
+ * capability reads (`api.config.imageGeneration` / `api.config.imageModelCatalog`).
+ * The agent-dir config file still merges over it inside the plugin entry, so
+ * users keep the final say.
+ */
+const IMAGE_GENERATION_PACKAGE_ID = "agent-forge.plugin.image-generation";
 const isMemoryModeV1 = (value) => value === "off" || value === "light" || value === "full";
 function resolveSdkMemoryMode(explicitMode, env, settingsMode) {
     if (explicitMode !== undefined) {
@@ -594,31 +607,53 @@ export async function createAgentSession(options = {}) {
                 const effectiveTimeoutMs = httpIdleTimeoutMs === 0 ? 2147483647 : httpIdleTimeoutMs;
                 const timeoutMs = options?.timeoutMs ?? providerRetrySettings.timeoutMs ?? effectiveTimeoutMs;
                 const websocketConnectTimeoutMs = options?.websocketConnectTimeoutMs ?? settingsManager.getWebSocketConnectTimeoutMs();
-                try {
-                    return modelRuntime.streamSimple(model, context, {
-                        ...options,
-                        timeoutMs,
-                        websocketConnectTimeoutMs,
-                        maxRetries: options?.maxRetries ?? providerRetrySettings.maxRetries,
-                        maxRetryDelayMs: options?.maxRetryDelayMs ?? providerRetrySettings.maxRetryDelayMs,
-                        transformHeaders: async (requestHeaders) => {
-                            const session = agentSessionRef.current;
-                            // v8 ignore next -- 流式请求仅在会话初始化后发生，session 恒已赋值
-                            if (!session)
-                                throw new Error("Capability runtime is not initialized for provider request");
-                            return session.getCapabilityRuntime().transformProviderHeaders({
-                                model,
-                                ...(options?.sessionId === undefined ? {} : { sessionId: options.sessionId }),
-                                headers: requestHeaders,
-                            });
-                        },
+                // 默认闭包：底层 streamSimple 调用（请求预算/超时按本次调用捕获；header
+                // 变换闭包绑定请求模型参数，使换道重放后的备用模型也走各自变换）。
+                const baseStreamFn = (requestModel, requestContext, requestOptions) => {
+                    try {
+                        return modelRuntime.streamSimple(requestModel, requestContext, {
+                            ...requestOptions,
+                            timeoutMs,
+                            websocketConnectTimeoutMs,
+                            maxRetries: requestOptions?.maxRetries ?? providerRetrySettings.maxRetries,
+                            maxRetryDelayMs: requestOptions?.maxRetryDelayMs ?? providerRetrySettings.maxRetryDelayMs,
+                            transformHeaders: async (requestHeaders) => {
+                                const session = agentSessionRef.current;
+                                // v8 ignore next -- 流式请求仅在会话初始化后发生，session 恒已赋值
+                                if (!session)
+                                    throw new Error("Capability runtime is not initialized for provider request");
+                                return session.getCapabilityRuntime().transformProviderHeaders({
+                                    model: requestModel,
+                                    ...(requestOptions?.sessionId === undefined
+                                        ? {}
+                                        : { sessionId: requestOptions.sessionId }),
+                                    headers: requestHeaders,
+                                });
+                            },
+                        });
+                    }
+                    catch (error) {
+                        // streamFn 错误路径打点（设计 §5.2）：保留原始错误向上传播。
+                        hostLogger?.error("sdk", "provider stream failed", { cause: error });
+                        throw error;
+                    }
+                };
+                // streamFn wrapper 链（provider-failover 家族注册面，设计 供应商能力槽位
+                // 与主备切换 §4.8）：注册的 wrapper 按注册序包在默认闭包外层（先注册者最
+                // 外层），wrapper 拿到的 next 即链上下一个直至底层默认调用。每次请求时从
+                // 会话 capability runtime 读取，使嵌入式 failover 插件（会话构造后装配）与
+                // 后续加载的第三方 wrapper 都进入链中。调用方显式传 options.streamFn 的会话
+                // 整体绕过本装配（含 wrapper），不参与 failover——已知边界。
+                const wrappers = agentSessionRef.current?.getCapabilityRuntime().getStreamFnWrappers() ?? [];
+                let chain = baseStreamFn;
+                for (let index = wrappers.length - 1; index >= 0; index -= 1) {
+                    const wrapper = wrappers[index];
+                    const inner = chain;
+                    chain = (requestModel, requestContext, requestOptions) => wrapper(requestModel, requestContext, requestOptions, (nextModel, nextContext, nextOptions) => inner(nextModel, nextContext, nextOptions), {
+                        resolveModel: (provider, modelId) => modelRuntime.getModel(provider, modelId),
                     });
                 }
-                catch (error) {
-                    // streamFn 错误路径打点（设计 §5.2）：保留原始错误向上传播。
-                    hostLogger?.error("sdk", "provider stream failed", { cause: error });
-                    throw error;
-                }
+                return chain(model, context, options);
             },
         onPayload: async (payload, model) => {
             // 轨迹快照（设计 §4.2 llm.request）：最终 payload 转发给装配域收集器；
@@ -784,6 +819,28 @@ export async function createAgentSession(options = {}) {
         ...(capabilitySkillsFilter === undefined ? {} : { capabilitySkillsFilter }),
     });
     agentSessionRef.current = session;
+    // provider-failover 装配（设计 供应商能力槽位与主备切换 §4.8）：嵌入式第一方
+    // 插件经公共 registerStreamFnWrapper 注册面挂进上方默认 streamFn 装配（此处早于
+    // 下方外部插件装载，故 failover wrapper 位于链最外层，观察到的是其余 wrapper 与
+    // 默认闭包之后的最终流）。熔断状态是模块级单例，随进程生命周期跨会话共享（§4.2）。
+    // 配置从 settings `failover` 节原始读出（未配置 / enabled:false / 配置错误则不装配）；
+    // 装配失败只警告——可靠性能力不得阻断会话构造。装载预检（§4.6）随装配同步执行：
+    // 检查面全部为 modelRuntime 静态读取（目录解析/provider 存在/凭据条目快照），
+    // 零网络请求、不触发 OAuth 刷新。
+    try {
+        installProviderFailoverPlugin(session.getCapabilityRuntime(), {
+            failoverSettings: readProviderFailoverSettingsNode(settingsManager),
+            preflight: {
+                resolveModel: (provider, modelId) => modelRuntime.getModel(provider, modelId),
+                hasProvider: (providerId) => modelRuntime.getProvider(providerId) !== undefined,
+                hasConfiguredAuth: (providerId) => modelRuntime.hasConfiguredAuth(providerId),
+            },
+            hostLogger,
+        });
+    }
+    catch (error) {
+        hostLogger?.warn("sdk", "provider failover plugin load failed", { cause: error });
+    }
     // Session-suite binding (设计 §10.1): record the suite as session protocol
     // data via the existing custom-entry extension point. New sessions only;
     // resumed sessions keep their original binding.
@@ -1014,6 +1071,11 @@ export async function createAgentSession(options = {}) {
             }
         }
         const pathByManifest = new Map([...survivors].map((entry) => [entry.manifest, entry.path]));
+        // 生图槽位注入供料（供应商能力槽位设计 §3.3）：settings 槽位经 settings-manager
+        // 校验后的读面取（非法形状已 fail-closed 丢弃并记 warning），目录快照经
+        // ModelRuntime 投影 models.json 登记项（装配期静态数据）。
+        const imageGenerationSlot = settingsManager.getCapabilitiesSettings()?.imageGeneration;
+        const imageModelCatalog = modelRuntime.getImageModelCatalog();
         for (const manifest of resolvePluginCapabilityOrder([...survivors].map((entry) => entry.manifest))) {
             const manifestPath = pathByManifest.get(manifest);
             // v8 ignore next -- 顺序解析返回的 manifest 均来自同一 survivors 集合，路径恒存在
@@ -1042,6 +1104,27 @@ export async function createAgentSession(options = {}) {
                             },
                         }
                         : {}),
+                    // 生图槽位注入（供应商能力槽位设计 §3.3）：settings 槽位（provider/model，
+                    // model 可省）与 models.json 生图目录快照经公共 configOverride 通道注入
+                    // image-generation 插件包；插件按六层取值链消费（设计 §3.2）。槽位缺省时
+                    // 只注入快照——插件回落到 env/主推断/唯一候选推断。
+                    ...(manifest.id === IMAGE_GENERATION_PACKAGE_ID
+                        ? {
+                            configOverride: {
+                                ...(imageGenerationSlot === undefined
+                                    ? {}
+                                    : {
+                                        imageGeneration: {
+                                            provider: imageGenerationSlot.provider,
+                                            ...(imageGenerationSlot.model === undefined
+                                                ? {}
+                                                : { model: imageGenerationSlot.model }),
+                                        },
+                                    }),
+                                imageModelCatalog,
+                            },
+                        }
+                        : {}),
                 });
             }
             catch (error) {