@ai-agent-forge/plugin-provider-failover 0.88.1

package/dist/provider-failover.js

@@ -0,0 +1,780 @@
+/**
+ * 第一方 provider 主备切换插件（设计：docs/design/供应商能力槽位与主备切换设计.md §4；
+ * D-082 批 3b 自内核内嵌实现逐字迁出为独立插件包）。
+ *
+ * 形态与 bootstrap-retry 同族——经公共 `api.registerStreamFnWrapper` 注册面挂进
+ * 宿主默认 stream 装配，`{ priority: -100 }` 固定链最外层（与装载顺序无关）——但
+ * 熔断状态是**模块级单例**（设计 §4.2）：进程内所有会话与 subagent 共享同一份，
+ * 不随会话 dispose，不持久化（重启后全部 CLOSED）。
+ *
+ * 判定哲学（设计 §2）：只看流终态 done/error/aborted 与"是否已向上层释放内容
+ * 增量"两个本地事实，不解读错误类型/错误码语义；原始 errorMessage 照透传保留，
+ * 只用于事件归因与 diagnostics，不参与机器判定分支。aborted 不计数、不换道、
+ * 状态不变。换道从第一次失败即发生；`failureThreshold` 只控制"是否继续先撞主"
+ * （连续 N 次后熔断打开，请求直接落备用，冷却期满后以真实请求试探回主）。
+ *
+ * 与内嵌装配的公共面差异（迁移登记，行为等价）：
+ * - 配置不再经 SettingsManager 读取：宿主经 manifest config 通道注入
+ *   `{ version: 1, failover: <settings failover 节原样> }`；`api.config` 无
+ *   failover 节 = 未配置，工厂直接 return（不注册任何面）。
+ * - 装载预检检查面改从 `api.host.modelCatalog`（plugin-sdk `ModelCatalogV1`）
+ *   结构获取；配置了 failover 而宿主未注入 modelCatalog 时 fail-loud 抛错
+ *   （与"settings 有 failover 但宿主不支持"同态，不静默降级）。
+ * - 插件面 `LifecycleAPI` 无 hasLifecycleEvent/dispatchLifecycle（与原内嵌第一参
+ *   `CapabilityRuntime` 的同名方法不同构）：目录 gate 以 `api.lifecycle.get` 的
+ *   抛错/命中等价实现（宿主未定义该事件 = 零派发）；派发走公共 `api.publish`
+ *   事件总线（source 由运行时归属插件 manifest id；Envelope 无 phase 字段——
+ *   本插件的可见性事件全部是 committed 相位）。
+ * - 进程日志走 `api.logger`（plugin-sdk `LoggerAPI`）或工厂注入的同形 deps；
+ *   warn 文案逐字保留。
+ */
+import { createAssistantMessageEventStream } from "@agent-forge/ai/compat";
+/** plugin.json 的 manifest id（原内嵌形态的 `agent-forge.provider-failover` 随内嵌装配退役）。 */
+export const PROVIDER_FAILOVER_PLUGIN_ID = "agent-forge.plugin.provider-failover";
+export const PROVIDER_FAILOVER_WRAPPER_NAME = "provider-failover";
+/**
+ * 可见性事件的 id/version：与宿主 lifecycle-catalog.ts 的 provider.failover.*
+ * 常量逐字同值。插件包不可 import 宿主内部模块（D-075 §0 边界白名单），此处
+ * 本地声明；宿主未在 lifecycle 目录定义同名事件时 `api.lifecycle.get` 抛错，
+ * gate 关闭、零派发（值漂移因此被发现而不是静默错投）。
+ */
+export const PROVIDER_FAILOVER_SWITCHED_EVENT_ID = "provider.failover.switched";
+export const PROVIDER_FAILOVER_SWITCHED_EVENT_VERSION = 1;
+export const PROVIDER_FAILOVER_RECOVERED_EVENT_ID = "provider.failover.recovered";
+export const PROVIDER_FAILOVER_RECOVERED_EVENT_VERSION = 1;
+export const PROVIDER_FAILOVER_PROBE_FAILED_EVENT_ID = "provider.failover.probe.failed";
+export const PROVIDER_FAILOVER_PROBE_FAILED_EVENT_VERSION = 1;
+/**
+ * 会话日志快照通道的 customType（设计 §4.7 Phase 3）：插件经公共
+ * `api.session.appendEntry` 在状态转移点写入快照，footer 每帧取最后一条渲染
+ * 摘要行——与 goal.state / todo.state / workflow.state 同构，零新公共面。
+ */
+export const PROVIDER_FAILOVER_STATE_ENTRY_TYPE = "provider.failover.state";
+/** 链默认阈值/冷却（设计 §4.1：默认值全部可省）。 */
+const DEFAULT_FAILURE_THRESHOLD = 2;
+const DEFAULT_COOLDOWN_INITIAL_MS = 60_000;
+const DEFAULT_COOLDOWN_MAX_MS = 15 * 60_000;
+/** 事件负载与 diagnostics 里的原始错误文本截断上限（只影响展示，不影响判定）。 */
+const RAW_ERROR_MAX_LENGTH = 500;
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function parseModelReference(reference) {
+    const separator = reference.indexOf("/");
+    if (separator <= 0 || separator === reference.length - 1)
+        return undefined;
+    return { provider: reference.slice(0, separator), modelId: reference.slice(separator + 1) };
+}
+function parseModelReferenceList(value, label, warn) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        warn(`failover ${label} must be an array of "provider/modelId" strings; ignoring it`);
+        return undefined;
+    }
+    const references = [];
+    for (const entry of value) {
+        if (typeof entry !== "string" || parseModelReference(entry) === undefined) {
+            warn(`failover ${label} contains a non-"provider/modelId" entry; skipping it`);
+            continue;
+        }
+        references.push(entry);
+    }
+    return references;
+}
+/** `backupProviders` 是纯 provider id 列表（设计 §4.1：`["proxy-a", "proxy-b"]`），匹配运行时做。 */
+function parseProviderIdList(value, warn) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        warn("failover.backupProviders must be an array of provider id strings; ignoring it");
+        return undefined;
+    }
+    const providerIds = [];
+    for (const entry of value) {
+        if (typeof entry !== "string" || entry.trim() === "") {
+            warn("failover.backupProviders contains a non-string entry; skipping it");
+            continue;
+        }
+        providerIds.push(entry);
+    }
+    return providerIds;
+}
+/**
+ * 解析 settings `failover` 节。返回 undefined = 无 failover（未配置 / 无有效
+ * backupProviders 与 chains / 配置错误拒绝加载——后者附带一条警告，设计 §4.1
+ * "重复 primary 拒绝加载并警告"）。`failover.enabled` 开关已移除（2026-10-03
+ * D-079）：节点存在即装配，残留 `enabled` 键只警告并忽略，按其余字段正常解析。
+ */
+export function parseProviderFailoverConfig(raw, warn) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!isPlainObject(raw)) {
+        warn("failover settings must be an object; provider failover stays disabled");
+        return undefined;
+    }
+    if (raw.enabled !== undefined) {
+        warn("failover.enabled was removed (2026-10-03): the failover node installs whenever configured; remove the key");
+    }
+    let failureThreshold = DEFAULT_FAILURE_THRESHOLD;
+    if (raw.failureThreshold !== undefined) {
+        if (typeof raw.failureThreshold !== "number" ||
+            !Number.isSafeInteger(raw.failureThreshold) ||
+            raw.failureThreshold < 1) {
+            warn("failover.failureThreshold must be a positive integer; using the default (2)");
+        }
+        else {
+            failureThreshold = raw.failureThreshold;
+        }
+    }
+    let cooldownInitialMs = DEFAULT_COOLDOWN_INITIAL_MS;
+    let cooldownMaxMs = DEFAULT_COOLDOWN_MAX_MS;
+    if (raw.cooldown !== undefined) {
+        if (!isPlainObject(raw.cooldown)) {
+            warn("failover.cooldown must be an object { initialMs?, maxMs? }; using the defaults");
+        }
+        else {
+            const initialMs = raw.cooldown.initialMs;
+            const maxMs = raw.cooldown.maxMs;
+            if (initialMs !== undefined &&
+                (typeof initialMs !== "number" || !Number.isSafeInteger(initialMs) || initialMs < 1)) {
+                warn("failover.cooldown.initialMs must be a positive integer; using the default (60000)");
+            }
+            else if (initialMs !== undefined) {
+                cooldownInitialMs = initialMs;
+            }
+            if (maxMs !== undefined && (typeof maxMs !== "number" || !Number.isSafeInteger(maxMs) || maxMs < 1)) {
+                warn("failover.cooldown.maxMs must be a positive integer; using the default (900000)");
+            }
+            else if (maxMs !== undefined) {
+                cooldownMaxMs = maxMs;
+            }
+        }
+    }
+    if (cooldownMaxMs < cooldownInitialMs) {
+        warn("failover.cooldown.maxMs is below initialMs; clamping maxMs to initialMs");
+        cooldownMaxMs = cooldownInitialMs;
+    }
+    const backupProviders = parseProviderIdList(raw.backupProviders, warn) ?? [];
+    const chains = [];
+    if (raw.chains !== undefined) {
+        if (!Array.isArray(raw.chains)) {
+            warn("failover.chains must be an array; ignoring explicit chains");
+        }
+        else {
+            const seenPrimaries = new Set();
+            for (const entry of raw.chains) {
+                if (!isPlainObject(entry)) {
+                    warn("failover.chains entries must be objects; skipping one");
+                    continue;
+                }
+                if (typeof entry.primary !== "string" || parseModelReference(entry.primary) === undefined) {
+                    warn('failover.chains entry is missing a valid "provider/modelId" primary; skipping it');
+                    continue;
+                }
+                const backups = parseModelReferenceList(entry.backups, `chains[${entry.primary}].backups`, warn) ?? [];
+                if (seenPrimaries.has(entry.primary)) {
+                    // 设计 §4.1：同一 primary 出现在多条显式链 → 配置错误拒绝加载。
+                    warn(`failover.chains declares primary "${entry.primary}" more than once; provider failover stays disabled`);
+                    return undefined;
+                }
+                seenPrimaries.add(entry.primary);
+                if (backups.length > 2) {
+                    warn(`failover chain "${entry.primary}" declares ${backups.length} backups; the worst-case retry budget grows with chain length (recommended: at most 2)`);
+                }
+                chains.push({ primary: entry.primary, backups });
+            }
+        }
+    }
+    if (backupProviders.length === 0 && chains.length === 0)
+        return undefined;
+    return { cooldownInitialMs, cooldownMaxMs, failureThreshold, backupProviders, chains };
+}
+const providerBreakerRegistry = new Map();
+/** 预检警告去重集（设计 §4.6：每进程至多一次，与会话重复装载解耦）。 */
+const preflightWarnedMessages = new Set();
+/** 测试隔离钩子：清空模块级熔断单例与预检警告去重集（仅测试使用）。 */
+export function resetProviderFailoverStateForTests() {
+    providerBreakerRegistry.clear();
+    preflightWarnedMessages.clear();
+}
+function getBreaker(chainId, config) {
+    let breaker = providerBreakerRegistry.get(chainId);
+    if (breaker === undefined) {
+        breaker = {
+            status: "closed",
+            consecutiveFailures: 0,
+            cooldownMs: config.cooldownInitialMs,
+            openedAtMs: 0,
+        };
+        providerBreakerRegistry.set(chainId, breaker);
+    }
+    return breaker;
+}
+const isCommittedDelta = (event) => event.type === "text_delta" || event.type === "thinking_delta" || event.type === "toolcall_delta";
+function truncateRawError(text) {
+    const value = text === undefined || text === "" ? "unknown error" : text;
+    return value.length > RAW_ERROR_MAX_LENGTH ? `${value.slice(0, RAW_ERROR_MAX_LENGTH)}…[truncated]` : value;
+}
+function createThrownErrorMessage(model, error, nowMs) {
+    return {
+        role: "assistant",
+        content: [],
+        api: model.api,
+        provider: model.provider,
+        model: model.id,
+        usage: {
+            input: 0,
+            output: 0,
+            cacheRead: 0,
+            cacheWrite: 0,
+            totalTokens: 0,
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+        },
+        stopReason: "error",
+        errorMessage: error instanceof Error ? error.message : String(error),
+        timestamp: nowMs,
+    };
+}
+/**
+ * 换道重放的凭据剔除（设计 §4.4）：apiKey/headers/env 是主 provider 的预解析
+ * 凭据，照抄重放会把主的 key 发给备用 provider——剔除后由目标 provider 经
+ * 宿主 auth 解析重新注入。其余 options（signal、预算、缓存策略等）原样保留。
+ */
+function stripCredentialOptions(options) {
+    if (options === undefined)
+        return undefined;
+    const { apiKey: _apiKey, headers: _headers, env: _env, ...rest } = options;
+    return rest;
+}
+/** 候选序列解析（设计 §4.1）：显式链优先，否则 backupProviders 按声明顺序同 id 匹配。 */
+function resolveFailoverCandidates(model, config, resolveModel) {
+    const reference = `${model.provider}/${model.id}`;
+    const chain = config.chains.find((entry) => entry.primary === reference);
+    if (chain !== undefined) {
+        const candidates = [];
+        for (const backup of chain.backups) {
+            const parsed = parseModelReference(backup);
+            const resolved = parsed === undefined ? undefined : resolveModel(parsed.provider, parsed.modelId);
+            if (resolved === undefined)
+                continue;
+            if (resolved.provider === model.provider && resolved.id === model.id)
+                continue;
+            candidates.push(resolved);
+        }
+        return candidates;
+    }
+    const candidates = [];
+    for (const providerId of config.backupProviders) {
+        // 含主 provider 自身 → 忽略该项（设计 §4.1）。
+        if (providerId === model.provider)
+            continue;
+        const resolved = resolveModel(providerId, model.id);
+        if (resolved !== undefined)
+            candidates.push(resolved);
+    }
+    return candidates;
+}
+/**
+ * 写一条熔断状态快照进会话日志（设计 §4.7 Phase 3）。尽力通道：失败不打断
+ * 换道判定，但经进程日志警告保持失败可见。
+ */
+function writeStateSnapshot(deps, snapshot) {
+    if (deps.session === undefined)
+        return;
+    try {
+        deps.session.appendEntry(PROVIDER_FAILOVER_STATE_ENTRY_TYPE, snapshot);
+    }
+    catch (error) {
+        deps.hostLogger?.warn("failover state snapshot append failed", { cause: error });
+    }
+}
+/** OPEN 转移点（阈值打开 / 试探失败重开）共用的 open 快照。 */
+function writeOpenStateSnapshot(deps, chainId, breaker, backupReference) {
+    writeStateSnapshot(deps, {
+        version: 1,
+        chainId,
+        status: "open",
+        ...(backupReference === undefined ? {} : { backupProvider: backupReference }),
+        probeAtMs: breaker.openedAtMs + breaker.cooldownMs,
+        now: breaker.openedAtMs,
+    });
+}
+function dispatchFailoverEvent(deps, request) {
+    try {
+        if (!deps.hasLifecycleEvent(request.type, request.version))
+            return;
+        deps.dispatchLifecycleEvent(request);
+    }
+    catch {
+        // 同上：派发入口同步抛错也不影响请求路径。
+    }
+}
+function createFailoverWrapper(deps) {
+    return (modelArgument, contextArgument, optionsArgument, next, host) => {
+        const model = modelArgument;
+        const context = contextArgument;
+        const options = optionsArgument;
+        const outer = createAssistantMessageEventStream();
+        const resolveModel = (provider, modelId) => host.resolveModel(provider, modelId);
+        void driveFailoverStream(deps, outer, model, context, options, next, resolveModel);
+        return outer;
+    };
+}
+async function driveFailoverStream(deps, outer, model, context, options, next, resolveModel) {
+    const { config } = deps;
+    const nowMs = deps.now();
+    const chainId = `${model.provider}/${model.id}`;
+    const breaker = getBreaker(chainId, config);
+    // 入场判定（设计 §4.3 判定表）：CLOSED/HALF_OPEN 撞主，OPEN 且冷却未满落备用。
+    let attemptPrimary = true;
+    let isProbe = false;
+    if (breaker.status === "open") {
+        if (nowMs - breaker.openedAtMs >= breaker.cooldownMs) {
+            // 冷却期满：下一个真实请求改道回主作试探（HALF_OPEN 并发放行）。
+            breaker.status = "half-open";
+            isProbe = true;
+        }
+        else {
+            attemptPrimary = false;
+        }
+    }
+    else if (breaker.status === "half-open") {
+        isProbe = true;
+    }
+    const candidates = resolveFailoverCandidates(model, config, resolveModel);
+    // OPEN 期请求从链头重走（设计 §4.3），快照披露的换道目标 = 链头候选。
+    const backupReference = candidates[0] === undefined ? undefined : `${candidates[0].provider}/${candidates[0].id}`;
+    const attempts = [];
+    if (attemptPrimary)
+        attempts.push({ model, role: "primary" });
+    for (const candidate of candidates)
+        attempts.push({ model: candidate, role: "backup" });
+    if (attempts.length === 0) {
+        // OPEN 且候选为空：无别处可去，直发主（按普通主请求计账，不作试探）。
+        attempts.push({ model, role: "primary" });
+    }
+    const failures = [];
+    let switchOrdinal = 0;
+    for (let index = 0; index < attempts.length; index++) {
+        const attempt = attempts[index];
+        const attemptOptions = attempt.role === "backup" ? stripCredentialOptions(options) : options;
+        const result = await runFailoverAttempt(outer, next, attempt.model, context, attemptOptions, deps.now);
+        if (result.outcome === "done") {
+            if (attempt.role === "primary") {
+                breaker.status = "closed";
+                breaker.consecutiveFailures = 0;
+                breaker.cooldownMs = config.cooldownInitialMs;
+                if (isProbe) {
+                    dispatchFailoverEvent(deps, {
+                        type: PROVIDER_FAILOVER_RECOVERED_EVENT_ID,
+                        version: PROVIDER_FAILOVER_RECOVERED_EVENT_VERSION,
+                        phase: "committed",
+                        source: PROVIDER_FAILOVER_PLUGIN_ID,
+                        // 事件总线 correlationId 取链引用（workflow.changed 同款领域键模式）。
+                        correlationId: chainId,
+                        data: { version: 1, chainId, provider: model.provider },
+                    });
+                    // HALF_OPEN → CLOSED 转移点：footer 摘要行随最后一条 closed 快照消失。
+                    writeStateSnapshot(deps, {
+                        version: 1,
+                        chainId,
+                        status: "closed",
+                        probeAtMs: 0,
+                        now: deps.now(),
+                    });
+                }
+            }
+            // 备用成败不影响 primary 熔断状态（设计 §4.2）。
+            return;
+        }
+        if (result.outcome === "aborted") {
+            // 用户本地取消：不计数、不换道、状态不变（设计 §2/§4.3）。
+            return;
+        }
+        if (result.outcome === "failed-forwarded") {
+            // 已过提交边界：不可重放，交回合级重试；主失败照常计数。
+            if (attempt.role === "primary") {
+                recordPrimaryFailure(deps, breaker, config, chainId, result.message, isProbe, backupReference);
+            }
+            return;
+        }
+        // failed-switchable：无可见内容，可换道重放。
+        failures.push(result.failure);
+        if (attempt.role === "primary") {
+            recordPrimaryFailure(deps, breaker, config, chainId, result.failure.message, isProbe, backupReference);
+        }
+        if (index + 1 < attempts.length) {
+            switchOrdinal += 1;
+            const target = attempts[index + 1];
+            dispatchFailoverEvent(deps, {
+                type: PROVIDER_FAILOVER_SWITCHED_EVENT_ID,
+                version: PROVIDER_FAILOVER_SWITCHED_EVENT_VERSION,
+                phase: "committed",
+                source: PROVIDER_FAILOVER_PLUGIN_ID,
+                // 事件总线 correlationId 取链引用（workflow.changed 同款领域键模式）。
+                correlationId: chainId,
+                data: {
+                    version: 1,
+                    chainId,
+                    from: `${attempt.model.provider}/${attempt.model.id}`,
+                    to: `${target.model.provider}/${target.model.id}`,
+                    attempt: switchOrdinal,
+                    rawError: truncateRawError(result.failure.message.errorMessage),
+                },
+            });
+            continue;
+        }
+        break;
+    }
+    // 全链尽：报链内最后一次实际失败的原始错误 + 整链摘要进 diagnostics（设计 §4.3）。
+    const lastFailure = failures[failures.length - 1];
+    if (lastFailure === undefined) {
+        // 不可达（至少一次 failed-switchable 才会走到这里）；保守以合成错误收尾。
+        const message = createThrownErrorMessage(model, new Error("provider failover exhausted the chain"), deps.now());
+        outer.push({ type: "error", reason: "error", error: message });
+        outer.end();
+        return;
+    }
+    const diagnostic = {
+        type: "provider-failover",
+        timestamp: deps.now(),
+        details: {
+            chainId,
+            attempts: failures.map((failure) => ({
+                provider: failure.model.provider,
+                model: failure.model.id,
+                error: truncateRawError(failure.message.errorMessage),
+            })),
+        },
+    };
+    const finalMessage = {
+        ...lastFailure.message,
+        diagnostics: [...(lastFailure.message.diagnostics ?? []), diagnostic],
+    };
+    outer.push({ type: "error", reason: "error", error: finalMessage });
+    outer.end();
+}
+/**
+ * 主失败计账（设计 §4.2/§4.3）：CLOSED 期连续 N 次达到阈值 → OPEN（冷却取
+ * initialMs）；HALF_OPEN 试探失败 → OPEN 且冷却 ×2 封顶 maxMs（经 probe.failed
+ * 事件可见）。backup 的成败永远不进这里。
+ */
+function recordPrimaryFailure(deps, breaker, config, chainId, message, isProbe, backupReference) {
+    if (isProbe) {
+        openAfterFailedProbe(deps, breaker, config, chainId, message, backupReference);
+        return;
+    }
+    breaker.consecutiveFailures += 1;
+    if (breaker.consecutiveFailures >= config.failureThreshold) {
+        breaker.status = "open";
+        breaker.cooldownMs = config.cooldownInitialMs;
+        breaker.openedAtMs = deps.now();
+        writeOpenStateSnapshot(deps, chainId, breaker, backupReference);
+    }
+}
+/** HALF_OPEN 试探失败：回 OPEN，冷却 ×2 封顶 maxMs，并派发 probe.failed（设计 §4.2）。 */
+function openAfterFailedProbe(deps, breaker, config, chainId, message, backupReference) {
+    breaker.status = "open";
+    breaker.cooldownMs = Math.min(breaker.cooldownMs * 2, config.cooldownMaxMs);
+    breaker.openedAtMs = deps.now();
+    dispatchFailoverEvent(deps, {
+        type: PROVIDER_FAILOVER_PROBE_FAILED_EVENT_ID,
+        version: PROVIDER_FAILOVER_PROBE_FAILED_EVENT_VERSION,
+        phase: "committed",
+        source: PROVIDER_FAILOVER_PLUGIN_ID,
+        // 事件总线 correlationId 取链引用（workflow.changed 同款领域键模式）。
+        correlationId: chainId,
+        data: {
+            version: 1,
+            chainId,
+            provider: message.provider,
+            rawError: truncateRawError(message.errorMessage),
+            nextCooldownMs: breaker.cooldownMs,
+        },
+    });
+    writeOpenStateSnapshot(deps, chainId, breaker, backupReference);
+}
+async function runFailoverAttempt(outer, next, attemptModel, context, options, now) {
+    let inner;
+    try {
+        inner = (await next(attemptModel, context, options));
+    }
+    catch (error) {
+        const message = createThrownErrorMessage(attemptModel, error, now());
+        return { outcome: "failed-switchable", failure: { model: attemptModel, message } };
+    }
+    // 前奏事件缓冲（设计 §4.4）：提交边界（首个内容增量）或正常完成前不释放，
+    // 使"无可见内容"的失败可以整段丢弃后无感重放。非增量、非终态事件（start、
+    // *_start、*_end 及未知扩展事件）一律入缓冲——保守归入前奏，重放安全性优先。
+    const buffered = [];
+    let committed = false;
+    const flushBuffer = () => {
+        for (const event of buffered)
+            outer.push(event);
+        buffered.length = 0;
+    };
+    try {
+        for await (const event of inner) {
+            if (event.type === "done") {
+                flushBuffer();
+                outer.push(event);
+                outer.end();
+                return { outcome: "done", message: event.message };
+            }
+            if (event.type === "error") {
+                if (event.reason === "aborted") {
+                    // 不重放的终态：丢弃缓冲只发终态，避免上层收到孤立 start。
+                    outer.push(event);
+                    outer.end();
+                    return { outcome: "aborted", message: event.error };
+                }
+                if (committed) {
+                    outer.push(event);
+                    outer.end();
+                    return { outcome: "failed-forwarded", message: event.error };
+                }
+                return { outcome: "failed-switchable", failure: { model: attemptModel, message: event.error } };
+            }
+            if (isCommittedDelta(event)) {
+                if (!committed) {
+                    committed = true;
+                    flushBuffer();
+                }
+                outer.push(event);
+                continue;
+            }
+            if (committed)
+                outer.push(event);
+            else
+                buffered.push(event);
+        }
+    }
+    catch (error) {
+        const message = createThrownErrorMessage(attemptModel, error, now());
+        if (committed) {
+            const errorEvent = { type: "error", reason: "error", error: message };
+            outer.push(errorEvent);
+            outer.end();
+            return { outcome: "failed-forwarded", message };
+        }
+        return { outcome: "failed-switchable", failure: { model: attemptModel, message } };
+    }
+    // 流自然结束但没有终止信号：按设计 §2 的归一哲学视作 error 终态。
+    const message = createThrownErrorMessage(attemptModel, new Error("stream ended without a terminal event"), now());
+    if (committed) {
+        outer.push({ type: "error", reason: "error", error: message });
+        outer.end();
+        return { outcome: "failed-forwarded", message };
+    }
+    return { outcome: "failed-switchable", failure: { model: attemptModel, message } };
+}
+/**
+ * 稳定序列化（键排序、剔除 undefined）：compat/thinkingLevelMap 的派生差异按
+ * 值比较，不依赖对象键序。
+ */
+function stableStringify(value) {
+    if (value === undefined)
+        return "∅";
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? String(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    const entries = Object.entries(value)
+        .filter(([, entryValue]) => entryValue !== undefined)
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+    return `{${entries.map(([key, entryValue]) => `${JSON.stringify(key)}:${stableStringify(entryValue)}`).join(",")}}`;
+}
+/**
+ * 显式链全量预检（设计 §4.6）：每个 backup 逐一检查，失败条目从链中剔除并
+ * 警告；主不可解析 → 整链跳过。contextWindow/compat/thinkingLevelMap/maxTokens
+ * 差异只进警告清单、不硬拦——实施裁量：contextWindow 低于主的备用对小上下文
+ * 请求仍可成功，剔除条目会静默损失兜底；只有上下文逼近主窗口的请求才必失败，
+ * 该情形运行时走链内下一候选，有界。
+ */
+function preflightExplicitChain(chain, checks, warn) {
+    const parsedPrimary = parseModelReference(chain.primary);
+    const primaryModel = parsedPrimary === undefined ? undefined : checks.resolveModel(parsedPrimary.provider, parsedPrimary.modelId);
+    if (parsedPrimary === undefined || primaryModel === undefined) {
+        warn(`failover chain "${chain.primary}" primary does not resolve in the model catalog; skipping the chain`);
+        return undefined;
+    }
+    const backups = [];
+    for (const backup of chain.backups) {
+        const parsed = parseModelReference(backup);
+        const backupModel = parsed === undefined ? undefined : checks.resolveModel(parsed.provider, parsed.modelId);
+        if (parsed === undefined || backupModel === undefined) {
+            warn(`failover chain "${chain.primary}" backup "${backup}" does not resolve in the model catalog; skipping it`);
+            continue;
+        }
+        if (!checks.hasConfiguredAuth(backupModel.provider)) {
+            warn(`failover chain "${chain.primary}" backup provider "${backupModel.provider}" has no configured credentials; skipping "${backup}"`);
+            continue;
+        }
+        if (backupModel.contextWindow < primaryModel.contextWindow) {
+            warn(`failover chain "${chain.primary}" backup "${backup}" context window (${backupModel.contextWindow}) is below the primary's (${primaryModel.contextWindow}); contexts sized for the primary may fail on this backup (entry kept)`);
+        }
+        if (backupModel.maxTokens !== primaryModel.maxTokens) {
+            warn(`failover chain "${chain.primary}" backup "${backup}" maxTokens (${backupModel.maxTokens}) differs from the primary's (${primaryModel.maxTokens}); output budget may change after switching`);
+        }
+        if (stableStringify(backupModel.compat) !== stableStringify(primaryModel.compat)) {
+            warn(`failover chain "${chain.primary}" backup "${backup}" compat differs from the primary's; request derivation may change after switching`);
+        }
+        if (stableStringify(backupModel.thinkingLevelMap) !== stableStringify(primaryModel.thinkingLevelMap)) {
+            warn(`failover chain "${chain.primary}" backup "${backup}" thinkingLevelMap differs from the primary's; reasoning level mapping may change after switching`);
+        }
+        backups.push(backup);
+    }
+    if (backups.length === 0 && chain.backups.length > 0) {
+        warn(`failover chain "${chain.primary}" has no usable backups left after preflight; the primary keeps no failover candidates from this chain`);
+    }
+    return { primary: chain.primary, backups };
+}
+/**
+ * backupProviders 层预检（设计 §4.6）：仅检 provider 存在 + 凭据条目；模型匹配
+ * 留运行时（目录同 id 匹配不到时静默跳过，不算失败）。
+ */
+function preflightBackupProviders(providerIds, checks, warn) {
+    const retained = [];
+    for (const providerId of providerIds) {
+        if (!checks.hasProvider(providerId)) {
+            warn(`failover.backupProviders entry "${providerId}" is not a known provider; skipping it`);
+            continue;
+        }
+        if (!checks.hasConfiguredAuth(providerId)) {
+            warn(`failover.backupProviders entry "${providerId}" has no configured credentials; skipping it`);
+            continue;
+        }
+        retained.push(providerId);
+    }
+    return retained;
+}
+/**
+ * 装载预检主体：返回过滤后的派生配置（预检失败条目已从候选源剔除）。不改变
+ * 运行时候选解析逻辑——过滤只发生在装载期，运行时候选解析逻辑不变。
+ */
+function runProviderFailoverPreflight(config, checks, warn) {
+    const backupProviders = preflightBackupProviders(config.backupProviders, checks, warn);
+    const chains = [];
+    for (const chain of config.chains) {
+        const preflighted = preflightExplicitChain(chain, checks, warn);
+        if (preflighted !== undefined)
+            chains.push(preflighted);
+    }
+    return { ...config, backupProviders, chains };
+}
+/** wrapper 注册优先级：低值更外层；-100 保证 failover 恒在链最外层（与装载顺序无关）。 */
+const PROVIDER_FAILOVER_WRAPPER_PRIORITY = -100;
+/** 适配 `api.logger`（plugin-sdk LoggerAPI）为插件的进程日志警告面；未声明 logger-v1 时缺席。 */
+function hostLoggerFromApi(api) {
+    const logger = api.logger;
+    if (logger === undefined)
+        return undefined;
+    return {
+        warn: (message, context) => {
+            const cause = context?.cause;
+            // LoggerAPI.warn 不带 cause 形参：cause 归一为单行文本进 fields。
+            logger.warn(message, cause === undefined ? undefined : { cause: describeCause(cause) });
+        },
+    };
+}
+function describeCause(cause) {
+    if (cause instanceof Error)
+        return cause.message === "" ? cause.name : `${cause.name}: ${cause.message}`;
+    return String(cause);
+}
+/**
+ * 把插件装配进一个已构建的 `CapabilityAPI`（公共面；工厂与测试共用同一代码路径）：
+ *
+ * - `api.config` 无 `failover` 节（宿主未注入）→ 直接 return，不注册任何面；
+ *   残留 `failover.enabled` 键只警告并忽略（已移除，2026-10-03 D-079），节点按
+ *   其余字段正常解析装配。
+ * - 配置了解析后：宿主必须注入 `api.host.modelCatalog`（装载预检检查面来源），
+ *   缺席 = "settings 有 failover 但宿主不支持"——fail-loud 抛错，不静默降级。
+ * - 配置解析完成后同步执行装载预检（设计 §4.6）：失败条目从候选源剔除并警告，
+ *   警告经模块级去重每进程至多一次；预检不阻断其余条目与主 provider 的正常使用。
+ * - 熔断状态是模块级单例：本工厂跨会话重复调用注册的是新包装器实例，但共享
+ *   同一份状态（设计 §4.2）。
+ */
+function installProviderFailoverIntoApi(api, deps) {
+    const logger = deps.hostLogger ?? hostLoggerFromApi(api);
+    const warn = logger === undefined
+        ? (_message) => { }
+        : (message) => {
+            logger.warn(message);
+        };
+    // 注入契约：`{ version: 1, failover: <settings failover 节原样> }`；failover
+    // 键缺席 = 未配置（no-op）。
+    const config = parseProviderFailoverConfig(api.config.failover, warn);
+    if (config === undefined)
+        return;
+    const catalog = api.host.modelCatalog;
+    if (catalog === undefined) {
+        throw new Error("provider failover is configured but the host does not provide the modelCatalog capability service (api.host.modelCatalog); the plugin refuses to assemble without install-time preflight");
+    }
+    // P1 契约：ModelCatalogV1 的检查面（resolveModel/hasProvider/hasConfiguredAuth）
+    // 与预检 checks 同构，直接结构绑定；契约漂移在此处显式报型。
+    const preflight = catalog;
+    const warnPreflightOnce = (message) => {
+        if (preflightWarnedMessages.has(message))
+            return;
+        preflightWarnedMessages.add(message);
+        warn(message);
+    };
+    const preflighted = runProviderFailoverPreflight(config, preflight, warnPreflightOnce);
+    const now = deps.now ?? (() => Date.now());
+    // deps 须在此构建——api 只在工厂内可得。
+    const runtimeDeps = {
+        config: preflighted,
+        now,
+        ...(api.session === undefined ? {} : { session: api.session }),
+        ...(logger === undefined ? {} : { hostLogger: logger }),
+        hasLifecycleEvent: (type, version) => {
+            try {
+                api.lifecycle.get(type, version);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        dispatchLifecycleEvent: (request) => {
+            // LifecycleAPI 无 dispatchLifecycle（模块头差异登记）：等价公共面 =
+            // api.publish。source 由运行时归属本插件 manifest id；phase 不入
+            // EventEnvelope（本插件的可见性事件全部是 committed 相位）；所有派发点
+            // 都带 correlationId = chainId，兜底项仅为满足 LifecycleDispatchRequest
+            // 的可选键型。
+            void api
+                .publish({
+                type: request.type,
+                version: request.version,
+                correlationId: request.correlationId ?? request.type,
+                data: request.data,
+            })
+                .catch(() => {
+                // 可见性事件失败不打断换道判定（宪法 §8 的尽力通道）。
+            });
+        },
+    };
+    api.registerStreamFnWrapper(PROVIDER_FAILOVER_WRAPPER_NAME, createFailoverWrapper(runtimeDeps), {
+        priority: PROVIDER_FAILOVER_WRAPPER_PRIORITY,
+    });
+    // 装配期初始快照（status closed）覆盖恢复会话里的陈旧 open 残留：熔断
+    // 状态不持久化，新进程恒 CLOSED（设计 §4.2/§4.7）。无链上下文 → chainId 空。
+    writeStateSnapshot(runtimeDeps, {
+        version: 1,
+        chainId: "",
+        status: "closed",
+        probeAtMs: 0,
+        now: runtimeDeps.now(),
+    });
+}
+/**
+ * 构建 provider-failover 插件工厂（设计 §4.8 的插件包形态）：
+ * `(api: CapabilityAPI) => void`，经公共 `loadCapabilityPlugin`/manifest 通道装载。
+ * deps 仅用于测试注入时钟与进程日志；生产入口（entry.ts 默认导出）零参调用。
+ */
+export function createProviderFailoverPluginFactory(deps = {}) {
+    return (api) => {
+        installProviderFailoverIntoApi(api, deps);
+    };
+}
+//# sourceMappingURL=provider-failover.js.map