@ai-agent-forge/agent-forge 0.87.0 → 0.88.1

package/dist/core/extensions/microcompact.js

@@ -1,134 +0,0 @@
-/**
- * Microcompact (P1 context hygiene): before spending an LLM summarization
- * call, elide the BULKY OLD tool results from the LLM context — a pure local
- * history transform with zero model cost (the codex/ZCode "microcompact"
- * layer). The session file keeps every byte (append-only marker + logical
- * transform at context build); only the model-visible context shrinks.
- *
- * Contract: the marker is a `custom` session entry (`MICROCOMPACT_CUSTOM_TYPE`)
- * whose data names the elision point. The projection registered by the
- * bootstrap compaction policy plugin (via the PUBLIC
- * `api.registerEntryProjection` channel) replaces eligible tool-result
- * contents older than that point with a fixed placeholder, so reload and
- * token estimation stay consistent with live turns. The kernel applies
- * registered projections verbatim and knows nothing about microcompact.
- */
-import { contentText } from "@agent-forge/ai";
-import { estimateTokens } from "../compaction/index.js";
-/** Custom entry type carrying the microcompact elision point. */
-export const MICROCOMPACT_CUSTOM_TYPE = "microcompact.v1";
-/** Replacement content for an elided tool result. */
-export const MICROCOMPACT_ELIDED_PLACEHOLDER = "[earlier tool result elided by microcompact]";
-/** Tool results shorter than this are not worth eliding (noise, not bulk). */
-export const DEFAULT_MIN_ELIDE_CHARS = 200;
-/**
- * Minimum estimated token relief for a microcompact to fire: below this the
- * churn (marker entry + context transition) cannot pay for itself and the
- * caller falls through to full LLM compaction.
- */
-export const MIN_MICROCOMPACT_FREED_TOKENS = 2048;
-function isElidableToolResult(message, minChars) {
-    if (message.role !== "toolResult")
-        return false;
-    // 媒体保护：含非 text part（image 等）的 tool result 不 elide——占位符替换会
-    // 把模型可见上下文中的原图数据抹掉（会话文件虽保真，但投影按 marker 重放，
-    // 图像不会自行回来），保持"原图常驻直到全量压缩"的现行裁决。
-    if (Array.isArray(message.content) && message.content.some((part) => part.type !== "text")) {
-        return false;
-    }
-    return contentText(message.content, "").length >= minChars;
-}
-/**
- * Plan one microcompact over the branch path: protect the most recent
- * `keepRecentTokens` (estimated) as the verbatim tail, and elide the eligible
- * old tool results before that cut. Returns undefined when the caller disabled
- * the mechanism (`options.enabled === false`), when there is nothing to elide,
- * or when the relief cannot reach the minimum. Deliberately does NOT reuse
- * `CompactionSettings`: its `enabled` is the compaction master switch — a
- * different gate.
- */
-export function planMicrocompact(pathEntries, options) {
-    if (!options.enabled)
-        return undefined;
-    const minChars = options.minElideChars ?? DEFAULT_MIN_ELIDE_CHARS;
-    // Protect the recent tail: walk backwards accumulating estimated tokens,
-    // cutting before the entry that crosses the budget (same walk as
-    // findCutPoint, but without turn-boundary subtleties — elision never
-    // removes entries, only replaces contents, so any cut point is safe).
-    let accumulated = 0;
-    let cutIndex = 0;
-    for (let i = pathEntries.length - 1; i >= 0; i--) {
-        const entry = pathEntries[i];
-        const messageTokens = entry.message ? estimateTokens(entry.message) : 0;
-        if (messageTokens === 0)
-            continue;
-        accumulated += messageTokens;
-        if (accumulated >= options.keepRecentTokens) {
-            cutIndex = i;
-            break;
-        }
-    }
-    let freedTokens = 0;
-    let elidedCount = 0;
-    for (let i = 0; i < cutIndex; i++) {
-        const message = pathEntries[i].message;
-        if (!message || !isElidableToolResult(message, minChars))
-            continue;
-        freedTokens +=
-            estimateTokens(message) -
-                estimateTokens({ ...message, content: [{ type: "text", text: MICROCOMPACT_ELIDED_PLACEHOLDER }] });
-        elidedCount += 1;
-    }
-    const elideBefore = pathEntries[cutIndex];
-    if (elidedCount === 0 || freedTokens < MIN_MICROCOMPACT_FREED_TOKENS)
-        return undefined;
-    const elideBeforeEntryId = elideBefore?.id;
-    if (!elideBeforeEntryId)
-        return undefined;
-    return { elideBeforeEntryId, freedTokens, elidedCount };
-}
-/** Resolve the marker data of the LAST microcompact marker in path order. */
-export function lastMicrocompactMarker(pathEntries) {
-    let marker;
-    for (const entry of pathEntries) {
-        if (entry.type !== "custom" || entry.customType !== MICROCOMPACT_CUSTOM_TYPE)
-            continue;
-        const data = entry.data;
-        if (typeof data?.elideBeforeEntryId === "string") {
-            marker = {
-                elideBeforeEntryId: data.elideBeforeEntryId,
-                minChars: typeof data.minChars === "number" && data.minChars >= 0 ? data.minChars : DEFAULT_MIN_ELIDE_CHARS,
-            };
-        }
-    }
-    return marker;
-}
-/**
- * The entry projection backing microcompact: replaces the CONTENT of eligible
- * tool results before the marker's cut point with the fixed placeholder, and
- * keeps everything else verbatim. Registered through the public
- * `api.registerEntryProjection` channel — the same channel any third-party
- * context policy uses; the kernel applies it without interpretation.
- */
-export function applyMicrocompactElision(path) {
-    const marker = lastMicrocompactMarker(path);
-    if (marker === undefined)
-        return path;
-    const cutIndex = path.findIndex((entry) => entry.id === marker.elideBeforeEntryId);
-    if (cutIndex <= 0)
-        return path;
-    return path.map((entry, index) => {
-        if (index >= cutIndex || entry.type !== "message")
-            return entry;
-        const message = entry.message;
-        // 与 planMicrocompact 同一判定（长度阈值 + 媒体保护）：投影只 elide 规划
-        // 时认定为可省的 tool result，否则计划与投影对同一历史给出不同结果。
-        if (!isElidableToolResult(message, marker.minChars))
-            return entry;
-        return {
-            ...entry,
-            message: { ...message, content: [{ type: "text", text: MICROCOMPACT_ELIDED_PLACEHOLDER }] },
-        };
-    });
-}
-//# sourceMappingURL=microcompact.js.map

package/dist/core/extensions/microcompact.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"microcompact.js","sourceRoot":"","sources":["../../../src/core/extensions/microcompact.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Microcompact (P1 context hygiene): before spending an LLM summarization\n * call, elide the BULKY OLD tool results from the LLM context — a pure local\n * history transform with zero model cost (the codex/ZCode \"microcompact\"\n * layer). The session file keeps every byte (append-only marker + logical\n * transform at context build); only the model-visible context shrinks.\n *\n * Contract: the marker is a `custom` session entry (`MICROCOMPACT_CUSTOM_TYPE`)\n * whose data names the elision point. The projection registered by the\n * bootstrap compaction policy plugin (via the PUBLIC\n * `api.registerEntryProjection` channel) replaces eligible tool-result\n * contents older than that point with a fixed placeholder, so reload and\n * token estimation stay consistent with live turns. The kernel applies\n * registered projections verbatim and knows nothing about microcompact.\n */\n\nimport type { AgentMessage } from \"@agent-forge/agent-core\";\nimport { contentText } from \"@agent-forge/ai\";\nimport { estimateTokens } from \"../compaction/index.ts\";\nimport type { SessionEntry } from \"../session-manager.ts\";\n\n/** Custom entry type carrying the microcompact elision point. */\nexport const MICROCOMPACT_CUSTOM_TYPE = \"microcompact.v1\";\n\n/** Replacement content for an elided tool result. */\nexport const MICROCOMPACT_ELIDED_PLACEHOLDER = \"[earlier tool result elided by microcompact]\";\n\n/** Tool results shorter than this are not worth eliding (noise, not bulk). */\nexport const DEFAULT_MIN_ELIDE_CHARS = 200;\n\n/**\n * Minimum estimated token relief for a microcompact to fire: below this the\n * churn (marker entry + context transition) cannot pay for itself and the\n * caller falls through to full LLM compaction.\n */\nexport const MIN_MICROCOMPACT_FREED_TOKENS = 2048;\n\n/** Data carried by a {@link MICROCOMPACT_CUSTOM_TYPE} custom entry. */\nexport interface MicrocompactMarkerData {\n\t/** Entries strictly BEFORE this entry id (path order) are elision candidates. */\n\treadonly elideBeforeEntryId: string;\n\t/** Tool results whose serialized content is shorter are kept verbatim. */\n\treadonly minChars: number;\n}\n\nexport interface MicrocompactPlan {\n\treadonly elideBeforeEntryId: string;\n\t/** Estimated tokens freed by eliding the eligible tool results. */\n\treadonly freedTokens: number;\n\treadonly elidedCount: number;\n}\n\nfunction isElidableToolResult(\n\tmessage: AgentMessage,\n\tminChars: number,\n): message is Extract<AgentMessage, { role: \"toolResult\" }> {\n\tif (message.role !== \"toolResult\") return false;\n\t// 媒体保护：含非 text part（image 等）的 tool result 不 elide——占位符替换会\n\t// 把模型可见上下文中的原图数据抹掉（会话文件虽保真，但投影按 marker 重放，\n\t// 图像不会自行回来），保持\"原图常驻直到全量压缩\"的现行裁决。\n\tif (Array.isArray(message.content) && message.content.some((part) => part.type !== \"text\")) {\n\t\treturn false;\n\t}\n\treturn contentText(message.content, \"\").length >= minChars;\n}\n\n/** Explicit plan options: `enabled` gates THIS mechanism only (microcompact relief), not compaction. */\nexport interface MicrocompactPlanOptions {\n\t/** Whether microcompact relief may fire at all (settings switch AND session cooldown). */\n\tenabled: boolean;\n\t/** Verbatim-protected recent tail budget (estimated tokens). */\n\tkeepRecentTokens: number;\n\t/** Tool results shorter than this are not worth eliding. */\n\tminElideChars?: number;\n}\n\n/**\n * Plan one microcompact over the branch path: protect the most recent\n * `keepRecentTokens` (estimated) as the verbatim tail, and elide the eligible\n * old tool results before that cut. Returns undefined when the caller disabled\n * the mechanism (`options.enabled === false`), when there is nothing to elide,\n * or when the relief cannot reach the minimum. Deliberately does NOT reuse\n * `CompactionSettings`: its `enabled` is the compaction master switch — a\n * different gate.\n */\nexport function planMicrocompact(\n\tpathEntries: readonly { readonly id?: string; readonly type: string; readonly message?: AgentMessage }[],\n\toptions: MicrocompactPlanOptions,\n): MicrocompactPlan | undefined {\n\tif (!options.enabled) return undefined;\n\tconst minChars = options.minElideChars ?? DEFAULT_MIN_ELIDE_CHARS;\n\n\t// Protect the recent tail: walk backwards accumulating estimated tokens,\n\t// cutting before the entry that crosses the budget (same walk as\n\t// findCutPoint, but without turn-boundary subtleties — elision never\n\t// removes entries, only replaces contents, so any cut point is safe).\n\tlet accumulated = 0;\n\tlet cutIndex = 0;\n\tfor (let i = pathEntries.length - 1; i >= 0; i--) {\n\t\tconst entry = pathEntries[i];\n\t\tconst messageTokens = entry.message ? estimateTokens(entry.message) : 0;\n\t\tif (messageTokens === 0) continue;\n\t\taccumulated += messageTokens;\n\t\tif (accumulated >= options.keepRecentTokens) {\n\t\t\tcutIndex = i;\n\t\t\tbreak;\n\t\t}\n\t}\n\n\tlet freedTokens = 0;\n\tlet elidedCount = 0;\n\tfor (let i = 0; i < cutIndex; i++) {\n\t\tconst message = pathEntries[i].message;\n\t\tif (!message || !isElidableToolResult(message, minChars)) continue;\n\t\tfreedTokens +=\n\t\t\testimateTokens(message) -\n\t\t\testimateTokens({ ...message, content: [{ type: \"text\", text: MICROCOMPACT_ELIDED_PLACEHOLDER }] });\n\t\telidedCount += 1;\n\t}\n\n\tconst elideBefore = pathEntries[cutIndex];\n\tif (elidedCount === 0 || freedTokens < MIN_MICROCOMPACT_FREED_TOKENS) return undefined;\n\tconst elideBeforeEntryId = elideBefore?.id;\n\tif (!elideBeforeEntryId) return undefined;\n\treturn { elideBeforeEntryId, freedTokens, elidedCount };\n}\n\n/** Resolve the marker data of the LAST microcompact marker in path order. */\nexport function lastMicrocompactMarker(\n\tpathEntries: readonly { readonly type: string; readonly customType?: string; readonly data?: unknown }[],\n): MicrocompactMarkerData | undefined {\n\tlet marker: MicrocompactMarkerData | undefined;\n\tfor (const entry of pathEntries) {\n\t\tif (entry.type !== \"custom\" || entry.customType !== MICROCOMPACT_CUSTOM_TYPE) continue;\n\t\tconst data = entry.data as Partial<MicrocompactMarkerData> | undefined;\n\t\tif (typeof data?.elideBeforeEntryId === \"string\") {\n\t\t\tmarker = {\n\t\t\t\telideBeforeEntryId: data.elideBeforeEntryId,\n\t\t\t\tminChars: typeof data.minChars === \"number\" && data.minChars >= 0 ? data.minChars : DEFAULT_MIN_ELIDE_CHARS,\n\t\t\t};\n\t\t}\n\t}\n\treturn marker;\n}\n\n/**\n * The entry projection backing microcompact: replaces the CONTENT of eligible\n * tool results before the marker's cut point with the fixed placeholder, and\n * keeps everything else verbatim. Registered through the public\n * `api.registerEntryProjection` channel — the same channel any third-party\n * context policy uses; the kernel applies it without interpretation.\n */\nexport function applyMicrocompactElision(path: SessionEntry[]): SessionEntry[] {\n\tconst marker = lastMicrocompactMarker(path);\n\tif (marker === undefined) return path;\n\tconst cutIndex = path.findIndex((entry) => entry.id === marker.elideBeforeEntryId);\n\tif (cutIndex <= 0) return path;\n\treturn path.map((entry, index) => {\n\t\tif (index >= cutIndex || entry.type !== \"message\") return entry;\n\t\tconst message = entry.message;\n\t\t// 与 planMicrocompact 同一判定（长度阈值 + 媒体保护）：投影只 elide 规划\n\t\t// 时认定为可省的 tool result，否则计划与投影对同一历史给出不同结果。\n\t\tif (!isElidableToolResult(message, marker.minChars)) return entry;\n\t\treturn {\n\t\t\t...entry,\n\t\t\tmessage: { ...message, content: [{ type: \"text\", text: MICROCOMPACT_ELIDED_PLACEHOLDER }] },\n\t\t};\n\t});\n}\n"]}

package/dist/core/extensions/provider-failover.d.ts

@@ -1,106 +0,0 @@
-/**
- * 第一方 provider 主备切换插件（设计：docs/design/供应商能力槽位与主备切换设计.md §4）。
- *
- * 形态与 bootstrap-retry 同族——嵌入式第一方插件，策略经公共
- * `api.registerStreamFnWrapper` 注册面挂进宿主默认 stream 装配——但熔断状态是
- * **宿主模块级单例**（设计 §4.2）：进程内所有会话与 subagent 共享同一份，不随
- * 会话 dispose，不持久化（重启后全部 CLOSED）。
- *
- * 判定哲学（设计 §2）：只看流终态 done/error/aborted 与"是否已向上层释放内容
- * 增量"两个本地事实，不解读错误类型/错误码语义；原始 errorMessage 照透传保留，
- * 只用于事件归因与 diagnostics，不参与机器判定分支。aborted 不计数、不换道、
- * 状态不变。换道从第一次失败即发生；`failureThreshold` 只控制"是否继续先撞主"
- * （连续 N 次后熔断打开，请求直接落备用，冷却期满后以真实请求试探回主）。
- */
-import type { Api, Model } from "@agent-forge/ai/compat";
-import type { HostLogger } from "../logger.ts";
-import { type CapabilityPluginHandle } from "./capability-plugin.ts";
-import type { CapabilityRuntime } from "./capability-runtime.ts";
-export declare const PROVIDER_FAILOVER_PLUGIN_ID = "agent-forge.provider-failover";
-export declare const PROVIDER_FAILOVER_WRAPPER_NAME = "provider-failover";
-/**
- * 会话日志快照通道的 customType（设计 §4.7 Phase 3）：插件经公共
- * `api.session.appendEntry` 在状态转移点写入快照，footer 每帧取最后一条渲染
- * 摘要行——与 goal.state / todo.state / workflow.state 同构，零新公共面。
- */
-export declare const PROVIDER_FAILOVER_STATE_ENTRY_TYPE = "provider.failover.state";
-/** `provider.failover.state` 快照负载（footer 按最后一条渲染）。 */
-export interface ProviderFailoverStateSnapshot {
-    readonly version: 1;
-    /** 主链引用 `provider/modelId`；装配期初始快照无链上下文，为空串。 */
-    readonly chainId: string;
-    readonly status: "closed" | "open" | "half-open";
-    /** 当前换道目标引用 `provider/modelId`（OPEN 期请求从链头重走）；closed 省略。 */
-    readonly backupProvider?: string;
-    /** 下次试探时间戳 = open 时刻 + 当前冷却；closed 为 0。 */
-    readonly probeAtMs: number;
-    /** 快照写入时刻（注入时钟友好）。 */
-    readonly now: number;
-}
-interface FailoverChainDeclaration {
-    readonly primary: string;
-    readonly backups: readonly string[];
-}
-interface ResolvedFailoverConfig {
-    /** 试探失败冷却起点（也是回 CLOSED 后的重置值）。 */
-    readonly cooldownInitialMs: number;
-    readonly cooldownMaxMs: number;
-    readonly failureThreshold: number;
-    readonly backupProviders: readonly string[];
-    readonly chains: readonly FailoverChainDeclaration[];
-}
-/**
- * 解析 settings `failover` 节。返回 undefined = 无 failover（未配置 / 显式关闭 /
- * 配置错误拒绝加载——后者附带一条警告，设计 §4.1"重复 primary 拒绝加载并警告"）。
- */
-export declare function parseProviderFailoverConfig(raw: unknown, warn: (message: string) => void): ResolvedFailoverConfig | undefined;
-/**
- * 从 SettingsManager 现有读面取合并后的 `failover` 原始节点（设计 §4.1 配置面）：
- * `getFailoverSettings()`（Phase 1 落地）原样透传合并层对象，本层不做结构收窄
- * ——解析与校验全部收在本模块（见 parseProviderFailoverConfig）。
- */
-export declare function readProviderFailoverSettingsNode(settingsManager: Pick<SettingsManagerFailoverReader, "getFailoverSettings">): unknown;
-interface SettingsManagerFailoverReader {
-    getFailoverSettings(): unknown;
-}
-/** 测试隔离钩子：清空模块级熔断单例与预检警告去重集（仅测试使用）。 */
-export declare function resetProviderFailoverStateForTests(): void;
-/**
- * 装载预检的宿主静态检查面（设计 §4.6）。全部为目录/凭据快照读取：不发网络
- * 请求、不触发 OAuth 刷新（凭据检查与 ModelRuntime.hasConfiguredAuth 同构——
- * 只读"该 provider 是否有凭据条目"，不做可用性探测）。
- */
-export interface ProviderFailoverPreflightChecks {
-    /** 目录解析，与运行时换道候选解析同一面。 */
-    readonly resolveModel: (provider: string, modelId: string) => Model<Api> | undefined;
-    /** provider 在组合目录（builtin + models.json + 扩展）中存在（backupProviders 层预检）。 */
-    readonly hasProvider: (providerId: string) => boolean;
-    /** provider 有凭据条目（静态；不触发 OAuth 刷新）。 */
-    readonly hasConfiguredAuth: (providerId: string) => boolean;
-}
-export interface ProviderFailoverInstallOptions {
-    /** settings `failover` 节的原始合并值（经 readProviderFailoverSettingsNode 读取）。 */
-    readonly failoverSettings: unknown;
-    /**
-     * 装载预检宿主检查面（设计 §4.6）：全部静态读取，零网络、零 OAuth 刷新。
-     * 必传——预检是安装契约的一部分，宿主缺失检查面时不应静默退化为无预检。
-     */
-    readonly preflight: ProviderFailoverPreflightChecks;
-    /** 注入时钟（测试用确定性时间）；缺省 Date.now。 */
-    readonly now?: () => number;
-    /** 宿主进程日志；缺省时配置警告静默丢弃。 */
-    readonly hostLogger?: HostLogger;
-}
-/**
- * 装配嵌入式 provider-failover 插件（设计 §4.8）。
- *
- * - 未配置 / `enabled: false` / 配置错误（已警告）→ 返回 undefined，不注册任何面。
- * - 配置解析完成后同步执行装载预检（设计 §4.6）：失败条目从候选源剔除并警告，
- *   警告经模块级去重每进程至多一次；预检不阻断其余条目与主 provider 的正常使用。
- * - 宿主侧装配失败由调用方兜底（failover 是可靠性能力，装载失败不得阻断会话）。
- * - 熔断状态是模块级单例：本函数跨会话重复调用注册的是新包装器实例，但共享
- *   同一份状态（设计 §4.2）。
- */
-export declare function installProviderFailoverPlugin(runtime: CapabilityRuntime, options: ProviderFailoverInstallOptions): CapabilityPluginHandle | undefined;
-export {};
-//# sourceMappingURL=provider-failover.d.ts.map

package/dist/core/extensions/provider-failover.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"provider-failover.d.ts","sourceRoot":"","sources":["../../../src/core/extensions/provider-failover.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * 第一方 provider 主备切换插件（设计：docs/design/供应商能力槽位与主备切换设计.md §4）。\n *\n * 形态与 bootstrap-retry 同族——嵌入式第一方插件，策略经公共\n * `api.registerStreamFnWrapper` 注册面挂进宿主默认 stream 装配——但熔断状态是\n * **宿主模块级单例**（设计 §4.2）：进程内所有会话与 subagent 共享同一份，不随\n * 会话 dispose，不持久化（重启后全部 CLOSED）。\n *\n * 判定哲学（设计 §2）：只看流终态 done/error/aborted 与\"是否已向上层释放内容\n * 增量\"两个本地事实，不解读错误类型/错误码语义；原始 errorMessage 照透传保留，\n * 只用于事件归因与 diagnostics，不参与机器判定分支。aborted 不计数、不换道、\n * 状态不变。换道从第一次失败即发生；`failureThreshold` 只控制\"是否继续先撞主\"\n * （连续 N 次后熔断打开，请求直接落备用，冷却期满后以真实请求试探回主）。\n */\n\nimport type {\n\tApi,\n\tAssistantMessage,\n\tAssistantMessageDiagnostic,\n\tAssistantMessageEvent,\n\tAssistantMessageEventStream,\n\tContext,\n\tModel,\n\tSimpleStreamOptions,\n} from \"@agent-forge/ai/compat\";\nimport { createAssistantMessageEventStream } from \"@agent-forge/ai/compat\";\nimport type { HostLogger } from \"../logger.ts\";\nimport { type CapabilityPluginHandle, loadCapabilityPluginSync } from \"./capability-plugin.ts\";\nimport type { CapabilityRuntime } from \"./capability-runtime.ts\";\nimport {\n\tPROVIDER_FAILOVER_PROBE_FAILED_EVENT_ID,\n\tPROVIDER_FAILOVER_PROBE_FAILED_EVENT_VERSION,\n\tPROVIDER_FAILOVER_RECOVERED_EVENT_ID,\n\tPROVIDER_FAILOVER_RECOVERED_EVENT_VERSION,\n\tPROVIDER_FAILOVER_SWITCHED_EVENT_ID,\n\tPROVIDER_FAILOVER_SWITCHED_EVENT_VERSION,\n} from \"./lifecycle-catalog.ts\";\nimport type { LifecycleDispatchRequest, SessionAPI, StreamFnWrapper } from \"./public-api.ts\";\nimport { EXPERIMENTAL_PUBLIC_API_VERSION } from \"./public-api.ts\";\n\nexport const PROVIDER_FAILOVER_PLUGIN_ID = \"agent-forge.provider-failover\";\nexport const PROVIDER_FAILOVER_WRAPPER_NAME = \"provider-failover\";\n\n/**\n * 会话日志快照通道的 customType（设计 §4.7 Phase 3）：插件经公共\n * `api.session.appendEntry` 在状态转移点写入快照，footer 每帧取最后一条渲染\n * 摘要行——与 goal.state / todo.state / workflow.state 同构，零新公共面。\n */\nexport const PROVIDER_FAILOVER_STATE_ENTRY_TYPE = \"provider.failover.state\";\n\n/** `provider.failover.state` 快照负载（footer 按最后一条渲染）。 */\nexport interface ProviderFailoverStateSnapshot {\n\treadonly version: 1;\n\t/** 主链引用 `provider/modelId`；装配期初始快照无链上下文，为空串。 */\n\treadonly chainId: string;\n\treadonly status: \"closed\" | \"open\" | \"half-open\";\n\t/** 当前换道目标引用 `provider/modelId`（OPEN 期请求从链头重走）；closed 省略。 */\n\treadonly backupProvider?: string;\n\t/** 下次试探时间戳 = open 时刻 + 当前冷却；closed 为 0。 */\n\treadonly probeAtMs: number;\n\t/** 快照写入时刻（注入时钟友好）。 */\n\treadonly now: number;\n}\n\n/** 链默认阈值/冷却（设计 §4.1：默认值全部可省）。 */\nconst DEFAULT_FAILURE_THRESHOLD = 2;\nconst DEFAULT_COOLDOWN_INITIAL_MS = 60_000;\nconst DEFAULT_COOLDOWN_MAX_MS = 15 * 60_000;\n/** 事件负载与 diagnostics 里的原始错误文本截断上限（只影响展示，不影响判定）。 */\nconst RAW_ERROR_MAX_LENGTH = 500;\n\n// ---------------------------------------------------------------------------\n// 配置解析（局部类型声明：settings `failover` 节不是 settings-manager 的已知面，\n// 解析与校验全部收在本模块内，宿主只递交原始节点）\n// ---------------------------------------------------------------------------\n\ninterface FailoverChainDeclaration {\n\treadonly primary: string;\n\treadonly backups: readonly string[];\n}\n\ninterface ResolvedFailoverConfig {\n\t/** 试探失败冷却起点（也是回 CLOSED 后的重置值）。 */\n\treadonly cooldownInitialMs: number;\n\treadonly cooldownMaxMs: number;\n\treadonly failureThreshold: number;\n\treadonly backupProviders: readonly string[];\n\treadonly chains: readonly FailoverChainDeclaration[];\n}\n\nconst isPlainObject = (value: unknown): value is Record<string, unknown> =>\n\ttypeof value === \"object\" && value !== null && !Array.isArray(value);\n\nfunction parseModelReference(reference: string): { provider: string; modelId: string } | undefined {\n\tconst separator = reference.indexOf(\"/\");\n\tif (separator <= 0 || separator === reference.length - 1) return undefined;\n\treturn { provider: reference.slice(0, separator), modelId: reference.slice(separator + 1) };\n}\n\nfunction parseModelReferenceList(value: unknown, label: string, warn: (message: string) => void): string[] | undefined {\n\tif (value === undefined) return undefined;\n\tif (!Array.isArray(value)) {\n\t\twarn(`failover ${label} must be an array of \"provider/modelId\" strings; ignoring it`);\n\t\treturn undefined;\n\t}\n\tconst references: string[] = [];\n\tfor (const entry of value) {\n\t\tif (typeof entry !== \"string\" || parseModelReference(entry) === undefined) {\n\t\t\twarn(`failover ${label} contains a non-\"provider/modelId\" entry; skipping it`);\n\t\t\tcontinue;\n\t\t}\n\t\treferences.push(entry);\n\t}\n\treturn references;\n}\n\n/** `backupProviders` 是纯 provider id 列表（设计 §4.1：`[\"proxy-a\", \"proxy-b\"]`），匹配运行时做。 */\nfunction parseProviderIdList(value: unknown, warn: (message: string) => void): string[] | undefined {\n\tif (value === undefined) return undefined;\n\tif (!Array.isArray(value)) {\n\t\twarn(\"failover.backupProviders must be an array of provider id strings; ignoring it\");\n\t\treturn undefined;\n\t}\n\tconst providerIds: string[] = [];\n\tfor (const entry of value) {\n\t\tif (typeof entry !== \"string\" || entry.trim() === \"\") {\n\t\t\twarn(\"failover.backupProviders contains a non-string entry; skipping it\");\n\t\t\tcontinue;\n\t\t}\n\t\tproviderIds.push(entry);\n\t}\n\treturn providerIds;\n}\n\n/**\n * 解析 settings `failover` 节。返回 undefined = 无 failover（未配置 / 显式关闭 /\n * 配置错误拒绝加载——后者附带一条警告，设计 §4.1\"重复 primary 拒绝加载并警告\"）。\n */\nexport function parseProviderFailoverConfig(\n\traw: unknown,\n\twarn: (message: string) => void,\n): ResolvedFailoverConfig | undefined {\n\tif (raw === undefined || raw === null) return undefined;\n\tif (!isPlainObject(raw)) {\n\t\twarn(\"failover settings must be an object; provider failover stays disabled\");\n\t\treturn undefined;\n\t}\n\tif (raw.enabled === false) return undefined;\n\tif (raw.enabled !== undefined && typeof raw.enabled !== \"boolean\") {\n\t\twarn(\"failover.enabled must be a boolean; provider failover stays disabled\");\n\t\treturn undefined;\n\t}\n\n\tlet failureThreshold = DEFAULT_FAILURE_THRESHOLD;\n\tif (raw.failureThreshold !== undefined) {\n\t\tif (\n\t\t\ttypeof raw.failureThreshold !== \"number\" ||\n\t\t\t!Number.isSafeInteger(raw.failureThreshold) ||\n\t\t\traw.failureThreshold < 1\n\t\t) {\n\t\t\twarn(\"failover.failureThreshold must be a positive integer; using the default (2)\");\n\t\t} else {\n\t\t\tfailureThreshold = raw.failureThreshold;\n\t\t}\n\t}\n\n\tlet cooldownInitialMs = DEFAULT_COOLDOWN_INITIAL_MS;\n\tlet cooldownMaxMs = DEFAULT_COOLDOWN_MAX_MS;\n\tif (raw.cooldown !== undefined) {\n\t\tif (!isPlainObject(raw.cooldown)) {\n\t\t\twarn(\"failover.cooldown must be an object { initialMs?, maxMs? }; using the defaults\");\n\t\t} else {\n\t\t\tconst initialMs = raw.cooldown.initialMs;\n\t\t\tconst maxMs = raw.cooldown.maxMs;\n\t\t\tif (\n\t\t\t\tinitialMs !== undefined &&\n\t\t\t\t(typeof initialMs !== \"number\" || !Number.isSafeInteger(initialMs) || initialMs < 1)\n\t\t\t) {\n\t\t\t\twarn(\"failover.cooldown.initialMs must be a positive integer; using the default (60000)\");\n\t\t\t} else if (initialMs !== undefined) {\n\t\t\t\tcooldownInitialMs = initialMs;\n\t\t\t}\n\t\t\tif (maxMs !== undefined && (typeof maxMs !== \"number\" || !Number.isSafeInteger(maxMs) || maxMs < 1)) {\n\t\t\t\twarn(\"failover.cooldown.maxMs must be a positive integer; using the default (900000)\");\n\t\t\t} else if (maxMs !== undefined) {\n\t\t\t\tcooldownMaxMs = maxMs;\n\t\t\t}\n\t\t}\n\t}\n\tif (cooldownMaxMs < cooldownInitialMs) {\n\t\twarn(\"failover.cooldown.maxMs is below initialMs; clamping maxMs to initialMs\");\n\t\tcooldownMaxMs = cooldownInitialMs;\n\t}\n\n\tconst backupProviders = parseProviderIdList(raw.backupProviders, warn) ?? [];\n\n\tconst chains: FailoverChainDeclaration[] = [];\n\tif (raw.chains !== undefined) {\n\t\tif (!Array.isArray(raw.chains)) {\n\t\t\twarn(\"failover.chains must be an array; ignoring explicit chains\");\n\t\t} else {\n\t\t\tconst seenPrimaries = new Set<string>();\n\t\t\tfor (const entry of raw.chains) {\n\t\t\t\tif (!isPlainObject(entry)) {\n\t\t\t\t\twarn(\"failover.chains entries must be objects; skipping one\");\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tif (typeof entry.primary !== \"string\" || parseModelReference(entry.primary) === undefined) {\n\t\t\t\t\twarn('failover.chains entry is missing a valid \"provider/modelId\" primary; skipping it');\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tconst backups = parseModelReferenceList(entry.backups, `chains[${entry.primary}].backups`, warn) ?? [];\n\t\t\t\tif (seenPrimaries.has(entry.primary)) {\n\t\t\t\t\t// 设计 §4.1：同一 primary 出现在多条显式链 → 配置错误拒绝加载。\n\t\t\t\t\twarn(\n\t\t\t\t\t\t`failover.chains declares primary \"${entry.primary}\" more than once; provider failover stays disabled`,\n\t\t\t\t\t);\n\t\t\t\t\treturn undefined;\n\t\t\t\t}\n\t\t\t\tseenPrimaries.add(entry.primary);\n\t\t\t\tif (backups.length > 2) {\n\t\t\t\t\twarn(\n\t\t\t\t\t\t`failover chain \"${entry.primary}\" declares ${backups.length} backups; the worst-case retry budget grows with chain length (recommended: at most 2)`,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tchains.push({ primary: entry.primary, backups });\n\t\t\t}\n\t\t}\n\t}\n\n\tif (backupProviders.length === 0 && chains.length === 0) return undefined;\n\treturn { cooldownInitialMs, cooldownMaxMs, failureThreshold, backupProviders, chains };\n}\n\n/**\n * 从 SettingsManager 现有读面取合并后的 `failover` 原始节点（设计 §4.1 配置面）：\n * `getFailoverSettings()`（Phase 1 落地）原样透传合并层对象，本层不做结构收窄\n * ——解析与校验全部收在本模块（见 parseProviderFailoverConfig）。\n */\nexport function readProviderFailoverSettingsNode(\n\tsettingsManager: Pick<SettingsManagerFailoverReader, \"getFailoverSettings\">,\n): unknown {\n\treturn settingsManager.getFailoverSettings();\n}\n\ninterface SettingsManagerFailoverReader {\n\tgetFailoverSettings(): unknown;\n}\n\n// ---------------------------------------------------------------------------\n// 熔断状态机（模块级单例，设计 §4.2：进程内所有会话共享，不持久化）\n// ---------------------------------------------------------------------------\n\ntype ProviderBreakerStatus = \"closed\" | \"open\" | \"half-open\";\n\ninterface ProviderBreakerState {\n\tstatus: ProviderBreakerStatus;\n\t/** CLOSED 期主连续失败计数；任一主 done 清零（设计 §4.2）。 */\n\tconsecutiveFailures: number;\n\t/** 当前冷却时长：打开时取 initialMs，每次试探失败 ×2 封顶 maxMs。 */\n\tcooldownMs: number;\n\topenedAtMs: number;\n}\n\nconst providerBreakerRegistry = new Map<string, ProviderBreakerState>();\n\n/** 预检警告去重集（设计 §4.6：每进程至多一次，与会话重复装载解耦）。 */\nconst preflightWarnedMessages = new Set<string>();\n\n/** 测试隔离钩子：清空模块级熔断单例与预检警告去重集（仅测试使用）。 */\nexport function resetProviderFailoverStateForTests(): void {\n\tproviderBreakerRegistry.clear();\n\tpreflightWarnedMessages.clear();\n}\n\nfunction getBreaker(chainId: string, config: ResolvedFailoverConfig): ProviderBreakerState {\n\tlet breaker = providerBreakerRegistry.get(chainId);\n\tif (breaker === undefined) {\n\t\tbreaker = {\n\t\t\tstatus: \"closed\",\n\t\t\tconsecutiveFailures: 0,\n\t\t\tcooldownMs: config.cooldownInitialMs,\n\t\t\topenedAtMs: 0,\n\t\t};\n\t\tproviderBreakerRegistry.set(chainId, breaker);\n\t}\n\treturn breaker;\n}\n\n// ---------------------------------------------------------------------------\n// 换道主体\n// ---------------------------------------------------------------------------\n\ninterface FailoverAttempt {\n\treadonly model: Model<Api>;\n\treadonly role: \"primary\" | \"backup\";\n}\n\ninterface AttemptFailure {\n\treadonly model: Model<Api>;\n\t/** 失败尝试的原始错误消息（照透传；诊断与事件只做展示截断）。 */\n\treadonly message: AssistantMessage;\n}\n\ntype AttemptOutcome =\n\t| { readonly outcome: \"done\"; readonly message: AssistantMessage }\n\t| { readonly outcome: \"aborted\"; readonly message: AssistantMessage }\n\t/** 已过提交边界（内容增量已释放）的 error：终态已转发，不可换道。 */\n\t| { readonly outcome: \"failed-forwarded\"; readonly message: AssistantMessage }\n\t/** 未过提交边界的 error：上层尚未看到任何事件，可安全重放。 */\n\t| { readonly outcome: \"failed-switchable\"; readonly failure: AttemptFailure };\n\nconst isCommittedDelta = (event: { type: string }): boolean =>\n\tevent.type === \"text_delta\" || event.type === \"thinking_delta\" || event.type === \"toolcall_delta\";\n\nfunction truncateRawError(text: string | undefined): string {\n\tconst value = text === undefined || text === \"\" ? \"unknown error\" : text;\n\treturn value.length > RAW_ERROR_MAX_LENGTH ? `${value.slice(0, RAW_ERROR_MAX_LENGTH)}…[truncated]` : value;\n}\n\nfunction createThrownErrorMessage(model: Model<Api>, error: unknown, nowMs: number): AssistantMessage {\n\treturn {\n\t\trole: \"assistant\",\n\t\tcontent: [],\n\t\tapi: model.api,\n\t\tprovider: model.provider,\n\t\tmodel: model.id,\n\t\tusage: {\n\t\t\tinput: 0,\n\t\t\toutput: 0,\n\t\t\tcacheRead: 0,\n\t\t\tcacheWrite: 0,\n\t\t\ttotalTokens: 0,\n\t\t\tcost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },\n\t\t},\n\t\tstopReason: \"error\",\n\t\terrorMessage: error instanceof Error ? error.message : String(error),\n\t\ttimestamp: nowMs,\n\t};\n}\n\n/**\n * 换道重放的凭据剔除（设计 §4.4）：apiKey/headers/env 是主 provider 的预解析\n * 凭据，照抄重放会把主的 key 发给备用 provider——剔除后由目标 provider 经\n * 宿主 auth 解析重新注入。其余 options（signal、预算、缓存策略等）原样保留。\n */\nfunction stripCredentialOptions(options: SimpleStreamOptions | undefined): SimpleStreamOptions | undefined {\n\tif (options === undefined) return undefined;\n\tconst { apiKey: _apiKey, headers: _headers, env: _env, ...rest } = options;\n\treturn rest;\n}\n\n/** 候选序列解析（设计 §4.1）：显式链优先，否则 backupProviders 按声明顺序同 id 匹配。 */\nfunction resolveFailoverCandidates(\n\tmodel: Model<Api>,\n\tconfig: ResolvedFailoverConfig,\n\tresolveModel: (provider: string, modelId: string) => Model<Api> | undefined,\n): Model<Api>[] {\n\tconst reference = `${model.provider}/${model.id}`;\n\tconst chain = config.chains.find((entry) => entry.primary === reference);\n\tif (chain !== undefined) {\n\t\tconst candidates: Model<Api>[] = [];\n\t\tfor (const backup of chain.backups) {\n\t\t\tconst parsed = parseModelReference(backup);\n\t\t\tconst resolved = parsed === undefined ? undefined : resolveModel(parsed.provider, parsed.modelId);\n\t\t\tif (resolved === undefined) continue;\n\t\t\tif (resolved.provider === model.provider && resolved.id === model.id) continue;\n\t\t\tcandidates.push(resolved);\n\t\t}\n\t\treturn candidates;\n\t}\n\tconst candidates: Model<Api>[] = [];\n\tfor (const providerId of config.backupProviders) {\n\t\t// 含主 provider 自身 → 忽略该项（设计 §4.1）。\n\t\tif (providerId === model.provider) continue;\n\t\tconst resolved = resolveModel(providerId, model.id);\n\t\tif (resolved !== undefined) candidates.push(resolved);\n\t}\n\treturn candidates;\n}\n\ninterface ProviderFailoverRuntimeDeps {\n\treadonly runtime: CapabilityRuntime;\n\treadonly config: ResolvedFailoverConfig;\n\treadonly now: () => number;\n\t/**\n\t * 会话日志快照通道（宿主声明 `session` feature 时在场；最小宿主可缺席）。\n\t * 缺席只损失 footer 可见性，不影响换道判定。\n\t */\n\treadonly session?: Pick<SessionAPI, \"appendEntry\">;\n\t/** 快照写入失败的警告通道；缺省静默（与 lifecycle 事件通道同级）。 */\n\treadonly hostLogger?: HostLogger;\n}\n\n/**\n * 写一条熔断状态快照进会话日志（设计 §4.7 Phase 3）。尽力通道：失败不打断\n * 换道判定，但经进程日志警告保持失败可见。\n */\nfunction writeStateSnapshot(deps: ProviderFailoverRuntimeDeps, snapshot: ProviderFailoverStateSnapshot): void {\n\tif (deps.session === undefined) return;\n\ttry {\n\t\tdeps.session.appendEntry(PROVIDER_FAILOVER_STATE_ENTRY_TYPE, snapshot);\n\t} catch (error) {\n\t\tdeps.hostLogger?.warn(\"provider-failover\", \"failover state snapshot append failed\", { cause: error });\n\t}\n}\n\n/** OPEN 转移点（阈值打开 / 试探失败重开）共用的 open 快照。 */\nfunction writeOpenStateSnapshot(\n\tdeps: ProviderFailoverRuntimeDeps,\n\tchainId: string,\n\tbreaker: ProviderBreakerState,\n\tbackupReference: string | undefined,\n): void {\n\twriteStateSnapshot(deps, {\n\t\tversion: 1,\n\t\tchainId,\n\t\tstatus: \"open\",\n\t\t...(backupReference === undefined ? {} : { backupProvider: backupReference }),\n\t\tprobeAtMs: breaker.openedAtMs + breaker.cooldownMs,\n\t\tnow: breaker.openedAtMs,\n\t});\n}\n\nfunction dispatchFailoverEvent(deps: ProviderFailoverRuntimeDeps, request: LifecycleDispatchRequest): void {\n\ttry {\n\t\tif (!deps.runtime.hasLifecycleEvent(request.type, request.version)) return;\n\t\tvoid deps.runtime.dispatchLifecycle(request).catch(() => {\n\t\t\t// 可见性事件失败不打断换道判定（宪法 §8 的尽力通道）。\n\t\t});\n\t} catch {\n\t\t// 同上：派发入口同步抛错也不影响请求路径。\n\t}\n}\n\nfunction createFailoverWrapper(deps: ProviderFailoverRuntimeDeps): StreamFnWrapper {\n\treturn (modelArgument, contextArgument, optionsArgument, next, host) => {\n\t\tconst model = modelArgument as Model<Api>;\n\t\tconst context = contextArgument as Context;\n\t\tconst options = optionsArgument as SimpleStreamOptions | undefined;\n\t\tconst outer = createAssistantMessageEventStream();\n\t\tconst resolveModel = (provider: string, modelId: string): Model<Api> | undefined =>\n\t\t\thost.resolveModel(provider, modelId) as Model<Api> | undefined;\n\t\tvoid driveFailoverStream(deps, outer, model, context, options, next, resolveModel);\n\t\treturn outer;\n\t};\n}\n\nasync function driveFailoverStream(\n\tdeps: ProviderFailoverRuntimeDeps,\n\touter: AssistantMessageEventStream,\n\tmodel: Model<Api>,\n\tcontext: Context,\n\toptions: SimpleStreamOptions | undefined,\n\tnext: (model: unknown, context: unknown, options: unknown) => unknown,\n\tresolveModel: (provider: string, modelId: string) => Model<Api> | undefined,\n): Promise<void> {\n\tconst { config } = deps;\n\tconst nowMs = deps.now();\n\tconst chainId = `${model.provider}/${model.id}`;\n\tconst breaker = getBreaker(chainId, config);\n\n\t// 入场判定（设计 §4.3 判定表）：CLOSED/HALF_OPEN 撞主，OPEN 且冷却未满落备用。\n\tlet attemptPrimary = true;\n\tlet isProbe = false;\n\tif (breaker.status === \"open\") {\n\t\tif (nowMs - breaker.openedAtMs >= breaker.cooldownMs) {\n\t\t\t// 冷却期满：下一个真实请求改道回主作试探（HALF_OPEN 并发放行）。\n\t\t\tbreaker.status = \"half-open\";\n\t\t\tisProbe = true;\n\t\t} else {\n\t\t\tattemptPrimary = false;\n\t\t}\n\t} else if (breaker.status === \"half-open\") {\n\t\tisProbe = true;\n\t}\n\n\tconst candidates = resolveFailoverCandidates(model, config, resolveModel);\n\t// OPEN 期请求从链头重走（设计 §4.3），快照披露的换道目标 = 链头候选。\n\tconst backupReference = candidates[0] === undefined ? undefined : `${candidates[0].provider}/${candidates[0].id}`;\n\n\tconst attempts: FailoverAttempt[] = [];\n\tif (attemptPrimary) attempts.push({ model, role: \"primary\" });\n\tfor (const candidate of candidates) attempts.push({ model: candidate, role: \"backup\" });\n\tif (attempts.length === 0) {\n\t\t// OPEN 且候选为空：无别处可去，直发主（按普通主请求计账，不作试探）。\n\t\tattempts.push({ model, role: \"primary\" });\n\t}\n\n\tconst failures: AttemptFailure[] = [];\n\tlet switchOrdinal = 0;\n\tfor (let index = 0; index < attempts.length; index++) {\n\t\tconst attempt = attempts[index];\n\t\tconst attemptOptions = attempt.role === \"backup\" ? stripCredentialOptions(options) : options;\n\t\tconst result = await runFailoverAttempt(outer, next, attempt.model, context, attemptOptions, deps.now);\n\n\t\tif (result.outcome === \"done\") {\n\t\t\tif (attempt.role === \"primary\") {\n\t\t\t\tbreaker.status = \"closed\";\n\t\t\t\tbreaker.consecutiveFailures = 0;\n\t\t\t\tbreaker.cooldownMs = config.cooldownInitialMs;\n\t\t\t\tif (isProbe) {\n\t\t\t\t\tdispatchFailoverEvent(deps, {\n\t\t\t\t\t\ttype: PROVIDER_FAILOVER_RECOVERED_EVENT_ID,\n\t\t\t\t\t\tversion: PROVIDER_FAILOVER_RECOVERED_EVENT_VERSION,\n\t\t\t\t\t\tphase: \"committed\",\n\t\t\t\t\t\tsource: PROVIDER_FAILOVER_PLUGIN_ID,\n\t\t\t\t\t\tdata: { version: 1, chainId, provider: model.provider },\n\t\t\t\t\t});\n\t\t\t\t\t// HALF_OPEN → CLOSED 转移点：footer 摘要行随最后一条 closed 快照消失。\n\t\t\t\t\twriteStateSnapshot(deps, {\n\t\t\t\t\t\tversion: 1,\n\t\t\t\t\t\tchainId,\n\t\t\t\t\t\tstatus: \"closed\",\n\t\t\t\t\t\tprobeAtMs: 0,\n\t\t\t\t\t\tnow: deps.now(),\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t}\n\t\t\t// 备用成败不影响 primary 熔断状态（设计 §4.2）。\n\t\t\treturn;\n\t\t}\n\n\t\tif (result.outcome === \"aborted\") {\n\t\t\t// 用户本地取消：不计数、不换道、状态不变（设计 §2/§4.3）。\n\t\t\treturn;\n\t\t}\n\n\t\tif (result.outcome === \"failed-forwarded\") {\n\t\t\t// 已过提交边界：不可重放，交回合级重试；主失败照常计数。\n\t\t\tif (attempt.role === \"primary\") {\n\t\t\t\trecordPrimaryFailure(deps, breaker, config, chainId, result.message, isProbe, backupReference);\n\t\t\t}\n\t\t\treturn;\n\t\t}\n\n\t\t// failed-switchable：无可见内容，可换道重放。\n\t\tfailures.push(result.failure);\n\t\tif (attempt.role === \"primary\") {\n\t\t\trecordPrimaryFailure(deps, breaker, config, chainId, result.failure.message, isProbe, backupReference);\n\t\t}\n\n\t\tif (index + 1 < attempts.length) {\n\t\t\tswitchOrdinal += 1;\n\t\t\tconst target = attempts[index + 1];\n\t\t\tdispatchFailoverEvent(deps, {\n\t\t\t\ttype: PROVIDER_FAILOVER_SWITCHED_EVENT_ID,\n\t\t\t\tversion: PROVIDER_FAILOVER_SWITCHED_EVENT_VERSION,\n\t\t\t\tphase: \"committed\",\n\t\t\t\tsource: PROVIDER_FAILOVER_PLUGIN_ID,\n\t\t\t\tdata: {\n\t\t\t\t\tversion: 1,\n\t\t\t\t\tchainId,\n\t\t\t\t\tfrom: `${attempt.model.provider}/${attempt.model.id}`,\n\t\t\t\t\tto: `${target.model.provider}/${target.model.id}`,\n\t\t\t\t\tattempt: switchOrdinal,\n\t\t\t\t\trawError: truncateRawError(result.failure.message.errorMessage),\n\t\t\t\t},\n\t\t\t});\n\t\t\tcontinue;\n\t\t}\n\t\tbreak;\n\t}\n\n\t// 全链尽：报链内最后一次实际失败的原始错误 + 整链摘要进 diagnostics（设计 §4.3）。\n\tconst lastFailure = failures[failures.length - 1];\n\tif (lastFailure === undefined) {\n\t\t// 不可达（至少一次 failed-switchable 才会走到这里）；保守以合成错误收尾。\n\t\tconst message = createThrownErrorMessage(model, new Error(\"provider failover exhausted the chain\"), deps.now());\n\t\touter.push({ type: \"error\", reason: \"error\", error: message });\n\t\touter.end();\n\t\treturn;\n\t}\n\tconst diagnostic: AssistantMessageDiagnostic = {\n\t\ttype: \"provider-failover\",\n\t\ttimestamp: deps.now(),\n\t\tdetails: {\n\t\t\tchainId,\n\t\t\tattempts: failures.map((failure) => ({\n\t\t\t\tprovider: failure.model.provider,\n\t\t\t\tmodel: failure.model.id,\n\t\t\t\terror: truncateRawError(failure.message.errorMessage),\n\t\t\t})),\n\t\t},\n\t};\n\tconst finalMessage: AssistantMessage = {\n\t\t...lastFailure.message,\n\t\tdiagnostics: [...(lastFailure.message.diagnostics ?? []), diagnostic],\n\t};\n\touter.push({ type: \"error\", reason: \"error\", error: finalMessage });\n\touter.end();\n}\n\n/**\n * 主失败计账（设计 §4.2/§4.3）：CLOSED 期连续 N 次达到阈值 → OPEN（冷却取\n * initialMs）；HALF_OPEN 试探失败 → OPEN 且冷却 ×2 封顶 maxMs（经 probe.failed\n * 事件可见）。backup 的成败永远不进这里。\n */\nfunction recordPrimaryFailure(\n\tdeps: ProviderFailoverRuntimeDeps,\n\tbreaker: ProviderBreakerState,\n\tconfig: ResolvedFailoverConfig,\n\tchainId: string,\n\tmessage: AssistantMessage,\n\tisProbe: boolean,\n\tbackupReference: string | undefined,\n): void {\n\tif (isProbe) {\n\t\topenAfterFailedProbe(deps, breaker, config, chainId, message, backupReference);\n\t\treturn;\n\t}\n\tbreaker.consecutiveFailures += 1;\n\tif (breaker.consecutiveFailures >= config.failureThreshold) {\n\t\tbreaker.status = \"open\";\n\t\tbreaker.cooldownMs = config.cooldownInitialMs;\n\t\tbreaker.openedAtMs = deps.now();\n\t\twriteOpenStateSnapshot(deps, chainId, breaker, backupReference);\n\t}\n}\n\n/** HALF_OPEN 试探失败：回 OPEN，冷却 ×2 封顶 maxMs，并派发 probe.failed（设计 §4.2）。 */\nfunction openAfterFailedProbe(\n\tdeps: ProviderFailoverRuntimeDeps,\n\tbreaker: ProviderBreakerState,\n\tconfig: ResolvedFailoverConfig,\n\tchainId: string,\n\tmessage: AssistantMessage,\n\tbackupReference: string | undefined,\n): void {\n\tbreaker.status = \"open\";\n\tbreaker.cooldownMs = Math.min(breaker.cooldownMs * 2, config.cooldownMaxMs);\n\tbreaker.openedAtMs = deps.now();\n\tdispatchFailoverEvent(deps, {\n\t\ttype: PROVIDER_FAILOVER_PROBE_FAILED_EVENT_ID,\n\t\tversion: PROVIDER_FAILOVER_PROBE_FAILED_EVENT_VERSION,\n\t\tphase: \"committed\",\n\t\tsource: PROVIDER_FAILOVER_PLUGIN_ID,\n\t\tdata: {\n\t\t\tversion: 1,\n\t\t\tchainId,\n\t\t\tprovider: message.provider,\n\t\t\trawError: truncateRawError(message.errorMessage),\n\t\t\tnextCooldownMs: breaker.cooldownMs,\n\t\t},\n\t});\n\twriteOpenStateSnapshot(deps, chainId, breaker, backupReference);\n}\n\nasync function runFailoverAttempt(\n\touter: AssistantMessageEventStream,\n\tnext: (model: unknown, context: unknown, options: unknown) => unknown,\n\tattemptModel: Model<Api>,\n\tcontext: Context,\n\toptions: SimpleStreamOptions | undefined,\n\tnow: () => number,\n): Promise<AttemptOutcome> {\n\tlet inner: AssistantMessageEventStream;\n\ttry {\n\t\tinner = (await next(attemptModel, context, options)) as AssistantMessageEventStream;\n\t} catch (error) {\n\t\tconst message = createThrownErrorMessage(attemptModel, error, now());\n\t\treturn { outcome: \"failed-switchable\", failure: { model: attemptModel, message } };\n\t}\n\n\t// 前奏事件缓冲（设计 §4.4）：提交边界（首个内容增量）或正常完成前不释放，\n\t// 使\"无可见内容\"的失败可以整段丢弃后无感重放。非增量、非终态事件（start、\n\t// *_start、*_end 及未知扩展事件）一律入缓冲——保守归入前奏，重放安全性优先。\n\tconst buffered: AssistantMessageEvent[] = [];\n\tlet committed = false;\n\tconst flushBuffer = (): void => {\n\t\tfor (const event of buffered) outer.push(event);\n\t\tbuffered.length = 0;\n\t};\n\ttry {\n\t\tfor await (const event of inner) {\n\t\t\tif (event.type === \"done\") {\n\t\t\t\tflushBuffer();\n\t\t\t\touter.push(event);\n\t\t\t\touter.end();\n\t\t\t\treturn { outcome: \"done\", message: event.message };\n\t\t\t}\n\t\t\tif (event.type === \"error\") {\n\t\t\t\tif (event.reason === \"aborted\") {\n\t\t\t\t\t// 不重放的终态：丢弃缓冲只发终态，避免上层收到孤立 start。\n\t\t\t\t\touter.push(event);\n\t\t\t\t\touter.end();\n\t\t\t\t\treturn { outcome: \"aborted\", message: event.error };\n\t\t\t\t}\n\t\t\t\tif (committed) {\n\t\t\t\t\touter.push(event);\n\t\t\t\t\touter.end();\n\t\t\t\t\treturn { outcome: \"failed-forwarded\", message: event.error };\n\t\t\t\t}\n\t\t\t\treturn { outcome: \"failed-switchable\", failure: { model: attemptModel, message: event.error } };\n\t\t\t}\n\t\t\tif (isCommittedDelta(event)) {\n\t\t\t\tif (!committed) {\n\t\t\t\t\tcommitted = true;\n\t\t\t\t\tflushBuffer();\n\t\t\t\t}\n\t\t\t\touter.push(event);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (committed) outer.push(event);\n\t\t\telse buffered.push(event);\n\t\t}\n\t} catch (error) {\n\t\tconst message = createThrownErrorMessage(attemptModel, error, now());\n\t\tif (committed) {\n\t\t\tconst errorEvent = { type: \"error\" as const, reason: \"error\" as const, error: message };\n\t\t\touter.push(errorEvent);\n\t\t\touter.end();\n\t\t\treturn { outcome: \"failed-forwarded\", message };\n\t\t}\n\t\treturn { outcome: \"failed-switchable\", failure: { model: attemptModel, message } };\n\t}\n\n\t// 流自然结束但没有终止信号：按设计 §2 的归一哲学视作 error 终态。\n\tconst message = createThrownErrorMessage(attemptModel, new Error(\"stream ended without a terminal event\"), now());\n\tif (committed) {\n\t\touter.push({ type: \"error\", reason: \"error\", error: message });\n\t\touter.end();\n\t\treturn { outcome: \"failed-forwarded\", message };\n\t}\n\treturn { outcome: \"failed-switchable\", failure: { model: attemptModel, message } };\n}\n\n// ---------------------------------------------------------------------------\n// 装载预检（设计 §4.6：插件安装时同步执行的静态检查，零网络请求）\n// ---------------------------------------------------------------------------\n\n/**\n * 装载预检的宿主静态检查面（设计 §4.6）。全部为目录/凭据快照读取：不发网络\n * 请求、不触发 OAuth 刷新（凭据检查与 ModelRuntime.hasConfiguredAuth 同构——\n * 只读\"该 provider 是否有凭据条目\"，不做可用性探测）。\n */\nexport interface ProviderFailoverPreflightChecks {\n\t/** 目录解析，与运行时换道候选解析同一面。 */\n\treadonly resolveModel: (provider: string, modelId: string) => Model<Api> | undefined;\n\t/** provider 在组合目录（builtin + models.json + 扩展）中存在（backupProviders 层预检）。 */\n\treadonly hasProvider: (providerId: string) => boolean;\n\t/** provider 有凭据条目（静态；不触发 OAuth 刷新）。 */\n\treadonly hasConfiguredAuth: (providerId: string) => boolean;\n}\n\n/**\n * 稳定序列化（键排序、剔除 undefined）：compat/thinkingLevelMap 的派生差异按\n * 值比较，不依赖对象键序。\n */\nfunction stableStringify(value: unknown): string {\n\tif (value === undefined) return \"∅\";\n\tif (value === null || typeof value !== \"object\") return JSON.stringify(value) ?? String(value);\n\tif (Array.isArray(value)) return `[${value.map(stableStringify).join(\",\")}]`;\n\tconst entries = Object.entries(value as Record<string, unknown>)\n\t\t.filter(([, entryValue]) => entryValue !== undefined)\n\t\t.sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));\n\treturn `{${entries.map(([key, entryValue]) => `${JSON.stringify(key)}:${stableStringify(entryValue)}`).join(\",\")}}`;\n}\n\n/**\n * 显式链全量预检（设计 §4.6）：每个 backup 逐一检查，失败条目从链中剔除并\n * 警告；主不可解析 → 整链跳过。contextWindow/compat/thinkingLevelMap/maxTokens\n * 差异只进警告清单、不硬拦——实施裁量：contextWindow 低于主的备用对小上下文\n * 请求仍可成功，剔除条目会静默损失兜底；只有上下文逼近主窗口的请求才必失败，\n * 该情形运行时走链内下一候选，有界。\n */\nfunction preflightExplicitChain(\n\tchain: FailoverChainDeclaration,\n\tchecks: ProviderFailoverPreflightChecks,\n\twarn: (message: string) => void,\n): FailoverChainDeclaration | undefined {\n\tconst parsedPrimary = parseModelReference(chain.primary);\n\tconst primaryModel =\n\t\tparsedPrimary === undefined ? undefined : checks.resolveModel(parsedPrimary.provider, parsedPrimary.modelId);\n\tif (parsedPrimary === undefined || primaryModel === undefined) {\n\t\twarn(`failover chain \"${chain.primary}\" primary does not resolve in the model catalog; skipping the chain`);\n\t\treturn undefined;\n\t}\n\tconst backups: string[] = [];\n\tfor (const backup of chain.backups) {\n\t\tconst parsed = parseModelReference(backup);\n\t\tconst backupModel = parsed === undefined ? undefined : checks.resolveModel(parsed.provider, parsed.modelId);\n\t\tif (parsed === undefined || backupModel === undefined) {\n\t\t\twarn(\n\t\t\t\t`failover chain \"${chain.primary}\" backup \"${backup}\" does not resolve in the model catalog; skipping it`,\n\t\t\t);\n\t\t\tcontinue;\n\t\t}\n\t\tif (!checks.hasConfiguredAuth(backupModel.provider)) {\n\t\t\twarn(\n\t\t\t\t`failover chain \"${chain.primary}\" backup provider \"${backupModel.provider}\" has no configured credentials; skipping \"${backup}\"`,\n\t\t\t);\n\t\t\tcontinue;\n\t\t}\n\t\tif (backupModel.contextWindow < primaryModel.contextWindow) {\n\t\t\twarn(\n\t\t\t\t`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)`,\n\t\t\t);\n\t\t}\n\t\tif (backupModel.maxTokens !== primaryModel.maxTokens) {\n\t\t\twarn(\n\t\t\t\t`failover chain \"${chain.primary}\" backup \"${backup}\" maxTokens (${backupModel.maxTokens}) differs from the primary's (${primaryModel.maxTokens}); output budget may change after switching`,\n\t\t\t);\n\t\t}\n\t\tif (stableStringify(backupModel.compat) !== stableStringify(primaryModel.compat)) {\n\t\t\twarn(\n\t\t\t\t`failover chain \"${chain.primary}\" backup \"${backup}\" compat differs from the primary's; request derivation may change after switching`,\n\t\t\t);\n\t\t}\n\t\tif (stableStringify(backupModel.thinkingLevelMap) !== stableStringify(primaryModel.thinkingLevelMap)) {\n\t\t\twarn(\n\t\t\t\t`failover chain \"${chain.primary}\" backup \"${backup}\" thinkingLevelMap differs from the primary's; reasoning level mapping may change after switching`,\n\t\t\t);\n\t\t}\n\t\tbackups.push(backup);\n\t}\n\tif (backups.length === 0 && chain.backups.length > 0) {\n\t\twarn(\n\t\t\t`failover chain \"${chain.primary}\" has no usable backups left after preflight; the primary keeps no failover candidates from this chain`,\n\t\t);\n\t}\n\treturn { primary: chain.primary, backups };\n}\n\n/**\n * backupProviders 层预检（设计 §4.6）：仅检 provider 存在 + 凭据条目；模型匹配\n * 留运行时（目录同 id 匹配不到时静默跳过，不算失败）。\n */\nfunction preflightBackupProviders(\n\tproviderIds: readonly string[],\n\tchecks: ProviderFailoverPreflightChecks,\n\twarn: (message: string) => void,\n): string[] {\n\tconst retained: string[] = [];\n\tfor (const providerId of providerIds) {\n\t\tif (!checks.hasProvider(providerId)) {\n\t\t\twarn(`failover.backupProviders entry \"${providerId}\" is not a known provider; skipping it`);\n\t\t\tcontinue;\n\t\t}\n\t\tif (!checks.hasConfiguredAuth(providerId)) {\n\t\t\twarn(`failover.backupProviders entry \"${providerId}\" has no configured credentials; skipping it`);\n\t\t\tcontinue;\n\t\t}\n\t\tretained.push(providerId);\n\t}\n\treturn retained;\n}\n\n/**\n * 装载预检主体：返回过滤后的派生配置（预检失败条目已从候选源剔除）。不改变\n * 运行时换道判定——过滤只发生在装载期，运行时候选解析逻辑不变。\n */\nfunction runProviderFailoverPreflight(\n\tconfig: ResolvedFailoverConfig,\n\tchecks: ProviderFailoverPreflightChecks,\n\twarn: (message: string) => void,\n): ResolvedFailoverConfig {\n\tconst backupProviders = preflightBackupProviders(config.backupProviders, checks, warn);\n\tconst chains: FailoverChainDeclaration[] = [];\n\tfor (const chain of config.chains) {\n\t\tconst preflighted = preflightExplicitChain(chain, checks, warn);\n\t\tif (preflighted !== undefined) chains.push(preflighted);\n\t}\n\treturn { ...config, backupProviders, chains };\n}\n\n// ---------------------------------------------------------------------------\n// 装配\n// ---------------------------------------------------------------------------\n\nexport interface ProviderFailoverInstallOptions {\n\t/** settings `failover` 节的原始合并值（经 readProviderFailoverSettingsNode 读取）。 */\n\treadonly failoverSettings: unknown;\n\t/**\n\t * 装载预检宿主检查面（设计 §4.6）：全部静态读取，零网络、零 OAuth 刷新。\n\t * 必传——预检是安装契约的一部分，宿主缺失检查面时不应静默退化为无预检。\n\t */\n\treadonly preflight: ProviderFailoverPreflightChecks;\n\t/** 注入时钟（测试用确定性时间）；缺省 Date.now。 */\n\treadonly now?: () => number;\n\t/** 宿主进程日志；缺省时配置警告静默丢弃。 */\n\treadonly hostLogger?: HostLogger;\n}\n\n/**\n * 装配嵌入式 provider-failover 插件（设计 §4.8）。\n *\n * - 未配置 / `enabled: false` / 配置错误（已警告）→ 返回 undefined，不注册任何面。\n * - 配置解析完成后同步执行装载预检（设计 §4.6）：失败条目从候选源剔除并警告，\n *   警告经模块级去重每进程至多一次；预检不阻断其余条目与主 provider 的正常使用。\n * - 宿主侧装配失败由调用方兜底（failover 是可靠性能力，装载失败不得阻断会话）。\n * - 熔断状态是模块级单例：本函数跨会话重复调用注册的是新包装器实例，但共享\n *   同一份状态（设计 §4.2）。\n */\nexport function installProviderFailoverPlugin(\n\truntime: CapabilityRuntime,\n\toptions: ProviderFailoverInstallOptions,\n): CapabilityPluginHandle | undefined {\n\tconst warn =\n\t\toptions.hostLogger === undefined\n\t\t\t? (_message: string) => {}\n\t\t\t: (message: string) => {\n\t\t\t\t\toptions.hostLogger?.warn(\"provider-failover\", message);\n\t\t\t\t};\n\tconst config = parseProviderFailoverConfig(options.failoverSettings, warn);\n\tif (config === undefined) return undefined;\n\tconst warnPreflightOnce = (message: string): void => {\n\t\tif (preflightWarnedMessages.has(message)) return;\n\t\tpreflightWarnedMessages.add(message);\n\t\twarn(message);\n\t};\n\tconst preflighted = runProviderFailoverPreflight(config, options.preflight, warnPreflightOnce);\n\tconst now = options.now ?? (() => Date.now());\n\treturn loadCapabilityPluginSync(\n\t\truntime,\n\t\t{\n\t\t\tid: PROVIDER_FAILOVER_PLUGIN_ID,\n\t\t\tversion: \"0.0.0\",\n\t\t\tapiVersion: EXPERIMENTAL_PUBLIC_API_VERSION,\n\t\t\tentry: \"<embedded:provider-failover>\",\n\t\t},\n\t\t(api) => {\n\t\t\t// 快照通道绑定本会话的公共 session 面（宿主声明 session feature 时在场）：\n\t\t\t// 会话 A 触发的熔断只写进 A 的日志，footer 可见性是会话局部的（设计 §4.7\n\t\t\t// 保真度限制）。deps 须在此构建——api 只在工厂内可得。\n\t\t\tconst deps: ProviderFailoverRuntimeDeps = {\n\t\t\t\truntime,\n\t\t\t\tconfig: preflighted,\n\t\t\t\tnow,\n\t\t\t\tsession: api.session,\n\t\t\t\t...(options.hostLogger === undefined ? {} : { hostLogger: options.hostLogger }),\n\t\t\t};\n\t\t\tapi.registerStreamFnWrapper(PROVIDER_FAILOVER_WRAPPER_NAME, createFailoverWrapper(deps));\n\t\t\t// 装配期初始快照（status closed）覆盖恢复会话里的陈旧 open 残留：熔断\n\t\t\t// 状态不持久化，新进程恒 CLOSED（设计 §4.2/§4.7）。无链上下文 → chainId 空。\n\t\t\twriteStateSnapshot(deps, { version: 1, chainId: \"\", status: \"closed\", probeAtMs: 0, now: deps.now() });\n\t\t},\n\t);\n}\n"]}

package/dist/core/extensions/provider-failover.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"provider-failover.js","sourceRoot":"","sources":["../../../src/core/extensions/provider-failover.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * 第一方 provider 主备切换插件（设计：docs/design/供应商能力槽位与主备切换设计.md §4）。\n *\n * 形态与 bootstrap-retry 同族——嵌入式第一方插件，策略经公共\n * `api.registerStreamFnWrapper` 注册面挂进宿主默认 stream 装配——但熔断状态是\n * **宿主模块级单例**（设计 §4.2）：进程内所有会话与 subagent 共享同一份，不随\n * 会话 dispose，不持久化（重启后全部 CLOSED）。\n *\n * 判定哲学（设计 §2）：只看流终态 done/error/aborted 与\"是否已向上层释放内容\n * 增量\"两个本地事实，不解读错误类型/错误码语义；原始 errorMessage 照透传保留，\n * 只用于事件归因与 diagnostics，不参与机器判定分支。aborted 不计数、不换道、\n * 状态不变。换道从第一次失败即发生；`failureThreshold` 只控制\"是否继续先撞主\"\n * （连续 N 次后熔断打开，请求直接落备用，冷却期满后以真实请求试探回主）。\n */\n\nimport type {\n\tApi,\n\tAssistantMessage,\n\tAssistantMessageDiagnostic,\n\tAssistantMessageEvent,\n\tAssistantMessageEventStream,\n\tContext,\n\tModel,\n\tSimpleStreamOptions,\n} from \"@agent-forge/ai/compat\";\nimport { createAssistantMessageEventStream } from \"@agent-forge/ai/compat\";\nimport type { HostLogger } from \"../logger.ts\";\nimport { type CapabilityPluginHandle, loadCapabilityPluginSync } from \"./capability-plugin.ts\";\nimport type { CapabilityRuntime } from \"./capability-runtime.ts\";\nimport {\n\tPROVIDER_FAILOVER_PROBE_FAILED_EVENT_ID,\n\tPROVIDER_FAILOVER_PROBE_FAILED_EVENT_VERSION,\n\tPROVIDER_FAILOVER_RECOVERED_EVENT_ID,\n\tPROVIDER_FAILOVER_RECOVERED_EVENT_VERSION,\n\tPROVIDER_FAILOVER_SWITCHED_EVENT_ID,\n\tPROVIDER_FAILOVER_SWITCHED_EVENT_VERSION,\n} from \"./lifecycle-catalog.ts\";\nimport type { LifecycleDispatchRequest, SessionAPI, StreamFnWrapper } from \"./public-api.ts\";\nimport { EXPERIMENTAL_PUBLIC_API_VERSION } from \"./public-api.ts\";\n\nexport const PROVIDER_FAILOVER_PLUGIN_ID = \"agent-forge.provider-failover\";\nexport const PROVIDER_FAILOVER_WRAPPER_NAME = \"provider-failover\";\n\n/**\n * 会话日志快照通道的 customType（设计 §4.7 Phase 3）：插件经公共\n * `api.session.appendEntry` 在状态转移点写入快照，footer 每帧取最后一条渲染\n * 摘要行——与 goal.state / todo.state / workflow.state 同构，零新公共面。\n */\nexport const PROVIDER_FAILOVER_STATE_ENTRY_TYPE = \"provider.failover.state\";\n\n/** `provider.failover.state` 快照负载（footer 按最后一条渲染）。 */\nexport interface ProviderFailoverStateSnapshot {\n\treadonly version: 1;\n\t/** 主链引用 `provider/modelId`；装配期初始快照无链上下文，为空串。 */\n\treadonly chainId: string;\n\treadonly status: \"closed\" | \"open\" | \"half-open\";\n\t/** 当前换道目标引用 `provider/modelId`（OPEN 期请求从链头重走）；closed 省略。 */\n\treadonly backupProvider?: string;\n\t/** 下次试探时间戳 = open 时刻 + 当前冷却；closed 为 0。 */\n\treadonly probeAtMs: number;\n\t/** 快照写入时刻（注入时钟友好）。 */\n\treadonly now: number;\n}\n\n/** 链默认阈值/冷却（设计 §4.1：默认值全部可省）。 */\nconst DEFAULT_FAILURE_THRESHOLD = 2;\nconst DEFAULT_COOLDOWN_INITIAL_MS = 60_000;\nconst DEFAULT_COOLDOWN_MAX_MS = 15 * 60_000;\n/** 事件负载与 diagnostics 里的原始错误文本截断上限（只影响展示，不影响判定）。 */\nconst RAW_ERROR_MAX_LENGTH = 500;\n\n// ---------------------------------------------------------------------------\n// 配置解析（局部类型声明：settings `failover` 节不是 settings-manager 的已知面，\n// 解析与校验全部收在本模块内，宿主只递交原始节点）\n// ---------------------------------------------------------------------------\n\ninterface FailoverChainDeclaration {\n\treadonly primary: string;\n\treadonly backups: readonly string[];\n}\n\ninterface ResolvedFailoverConfig {\n\t/** 试探失败冷却起点（也是回 CLOSED 后的重置值）。 */\n\treadonly cooldownInitialMs: number;\n\treadonly cooldownMaxMs: number;\n\treadonly failureThreshold: number;\n\treadonly backupProviders: readonly string[];\n\treadonly chains: readonly FailoverChainDeclaration[];\n}\n\nconst isPlainObject = (value: unknown): value is Record<string, unknown> =>\n\ttypeof value === \"object\" && value !== null && !Array.isArray(value);\n\nfunction parseModelReference(reference: string): { provider: string; modelId: string } | undefined {\n\tconst separator = reference.indexOf(\"/\");\n\tif (separator <= 0 || separator === reference.length - 1) return undefined;\n\treturn { provider: reference.slice(0, separator), modelId: reference.slice(separator + 1) };\n}\n\nfunction parseModelReferenceList(value: unknown, label: string, warn: (message: string) => void): string[] | undefined {\n\tif (value === undefined) return undefined;\n\tif (!Array.isArray(value)) {\n\t\twarn(`failover ${label} must be an array of \"provider/modelId\" strings; ignoring it`);\n\t\treturn undefined;\n\t}\n\tconst references: string[] = [];\n\tfor (const entry of value) {\n\t\tif (typeof entry !== \"string\" || parseModelReference(entry) === undefined) {\n\t\t\twarn(`failover ${label} contains a non-\"provider/modelId\" entry; skipping it`);\n\t\t\tcontinue;\n\t\t}\n\t\treferences.push(entry);\n\t}\n\treturn references;\n}\n\n/** `backupProviders` 是纯 provider id 列表（设计 §4.1：`[\"proxy-a\", \"proxy-b\"]`），匹配运行时做。 */\nfunction parseProviderIdList(value: unknown, warn: (message: string) => void): string[] | undefined {\n\tif (value === undefined) return undefined;\n\tif (!Array.isArray(value)) {\n\t\twarn(\"failover.backupProviders must be an array of provider id strings; ignoring it\");\n\t\treturn undefined;\n\t}\n\tconst providerIds: string[] = [];\n\tfor (const entry of value) {\n\t\tif (typeof entry !== \"string\" || entry.trim() === \"\") {\n\t\t\twarn(\"failover.backupProviders contains a non-string entry; skipping it\");\n\t\t\tcontinue;\n\t\t}\n\t\tproviderIds.push(entry);\n\t}\n\treturn providerIds;\n}\n\n/**\n * 解析 settings `failover` 节。返回 undefined = 无 failover（未配置 / 显式关闭 /\n * 配置错误拒绝加载——后者附带一条警告，设计 §4.1\"重复 primary 拒绝加载并警告\"）。\n */\nexport function parseProviderFailoverConfig(\n\traw: unknown,\n\twarn: (message: string) => void,\n): ResolvedFailoverConfig | undefined {\n\tif (raw === undefined || raw === null) return undefined;\n\tif (!isPlainObject(raw)) {\n\t\twarn(\"failover settings must be an object; provider failover stays disabled\");\n\t\treturn undefined;\n\t}\n\tif (raw.enabled === false) return undefined;\n\tif (raw.enabled !== undefined && typeof raw.enabled !== \"boolean\") {\n\t\twarn(\"failover.enabled must be a boolean; provider failover stays disabled\");\n\t\treturn undefined;\n\t}\n\n\tlet failureThreshold = DEFAULT_FAILURE_THRESHOLD;\n\tif (raw.failureThreshold !== undefined) {\n\t\tif (\n\t\t\ttypeof raw.failureThreshold !== \"number\" ||\n\t\t\t!Number.isSafeInteger(raw.failureThreshold) ||\n\t\t\traw.failureThreshold < 1\n\t\t) {\n\t\t\twarn(\"failover.failureThreshold must be a positive integer; using the default (2)\");\n\t\t} else {\n\t\t\tfailureThreshold = raw.failureThreshold;\n\t\t}\n\t}\n\n\tlet cooldownInitialMs = DEFAULT_COOLDOWN_INITIAL_MS;\n\tlet cooldownMaxMs = DEFAULT_COOLDOWN_MAX_MS;\n\tif (raw.cooldown !== undefined) {\n\t\tif (!isPlainObject(raw.cooldown)) {\n\t\t\twarn(\"failover.cooldown must be an object { initialMs?, maxMs? }; using the defaults\");\n\t\t} else {\n\t\t\tconst initialMs = raw.cooldown.initialMs;\n\t\t\tconst maxMs = raw.cooldown.maxMs;\n\t\t\tif (\n\t\t\t\tinitialMs !== undefined &&\n\t\t\t\t(typeof initialMs !== \"number\" || !Number.isSafeInteger(initialMs) || initialMs < 1)\n\t\t\t) {\n\t\t\t\twarn(\"failover.cooldown.initialMs must be a positive integer; using the default (60000)\");\n\t\t\t} else if (initialMs !== undefined) {\n\t\t\t\tcooldownInitialMs = initialMs;\n\t\t\t}\n\t\t\tif (maxMs !== undefined && (typeof maxMs !== \"number\" || !Number.isSafeInteger(maxMs) || maxMs < 1)) {\n\t\t\t\twarn(\"failover.cooldown.maxMs must be a positive integer; using the default (900000)\");\n\t\t\t} else if (maxMs !== undefined) {\n\t\t\t\tcooldownMaxMs = maxMs;\n\t\t\t}\n\t\t}\n\t}\n\tif (cooldownMaxMs < cooldownInitialMs) {\n\t\twarn(\"failover.cooldown.maxMs is below initialMs; clamping maxMs to initialMs\");\n\t\tcooldownMaxMs = cooldownInitialMs;\n\t}\n\n\tconst backupProviders = parseProviderIdList(raw.backupProviders, warn) ?? [];\n\n\tconst chains: FailoverChainDeclaration[] = [];\n\tif (raw.chains !== undefined) {\n\t\tif (!Array.isArray(raw.chains)) {\n\t\t\twarn(\"failover.chains must be an array; ignoring explicit chains\");\n\t\t} else {\n\t\t\tconst seenPrimaries = new Set<string>();\n\t\t\tfor (const entry of raw.chains) {\n\t\t\t\tif (!isPlainObject(entry)) {\n\t\t\t\t\twarn(\"failover.chains entries must be objects; skipping one\");\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tif (typeof entry.primary !== \"string\" || parseModelReference(entry.primary) === undefined) {\n\t\t\t\t\twarn('failover.chains entry is missing a valid \"provider/modelId\" primary; skipping it');\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tconst backups = parseModelReferenceList(entry.backups, `chains[${entry.primary}].backups`, warn) ?? [];\n\t\t\t\tif (seenPrimaries.has(entry.primary)) {\n\t\t\t\t\t// 设计 §4.1：同一 primary 出现在多条显式链 → 配置错误拒绝加载。\n\t\t\t\t\twarn(\n\t\t\t\t\t\t`failover.chains declares primary \"${entry.primary}\" more than once; provider failover stays disabled`,\n\t\t\t\t\t);\n\t\t\t\t\treturn undefined;\n\t\t\t\t}\n\t\t\t\tseenPrimaries.add(entry.primary);\n\t\t\t\tif (backups.length > 2) {\n\t\t\t\t\twarn(\n\t\t\t\t\t\t`failover chain \"${entry.primary}\" declares ${backups.length} backups; the worst-case retry budget grows with chain length (recommended: at most 2)`,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tchains.push({ primary: entry.primary, backups });\n\t\t\t}\n\t\t}\n\t}\n\n\tif (backupProviders.length === 0 && chains.length === 0) return undefined;\n\treturn { cooldownInitialMs, cooldownMaxMs, failureThreshold, backupProviders, chains };\n}\n\n/**\n * 从 SettingsManager 现有读面取合并后的 `failover` 原始节点（设计 §4.1 配置面）：\n * `getFailoverSettings()`（Phase 1 落地）原样透传合并层对象，本层不做结构收窄\n * ——解析与校验全部收在本模块（见 parseProviderFailoverConfig）。\n */\nexport function readProviderFailoverSettingsNode(\n\tsettingsManager: Pick<SettingsManagerFailoverReader, \"getFailoverSettings\">,\n): unknown {\n\treturn settingsManager.getFailoverSettings();\n}\n\ninterface SettingsManagerFailoverReader {\n\tgetFailoverSettings(): unknown;\n}\n\n// ---------------------------------------------------------------------------\n// 熔断状态机（模块级单例，设计 §4.2：进程内所有会话共享，不持久化）\n// ---------------------------------------------------------------------------\n\ntype ProviderBreakerStatus = \"closed\" | \"open\" | \"half-open\";\n\ninterface ProviderBreakerState {\n\tstatus: ProviderBreakerStatus;\n\t/** CLOSED 期主连续失败计数；任一主 done 清零（设计 §4.2）。 */\n\tconsecutiveFailures: number;\n\t/** 当前冷却时长：打开时取 initialMs，每次试探失败 ×2 封顶 maxMs。 */\n\tcooldownMs: number;\n\topenedAtMs: number;\n}\n\nconst providerBreakerRegistry = new Map<string, ProviderBreakerState>();\n\n/** 预检警告去重集（设计 §4.6：每进程至多一次，与会话重复装载解耦）。 */\nconst preflightWarnedMessages = new Set<string>();\n\n/** 测试隔离钩子：清空模块级熔断单例与预检警告去重集（仅测试使用）。 */\nexport function resetProviderFailoverStateForTests(): void {\n\tproviderBreakerRegistry.clear();\n\tpreflightWarnedMessages.clear();\n}\n\nfunction getBreaker(chainId: string, config: ResolvedFailoverConfig): ProviderBreakerState {\n\tlet breaker = providerBreakerRegistry.get(chainId);\n\tif (breaker === undefined) {\n\t\tbreaker = {\n\t\t\tstatus: \"closed\",\n\t\t\tconsecutiveFailures: 0,\n\t\t\tcooldownMs: config.cooldownInitialMs,\n\t\t\topenedAtMs: 0,\n\t\t};\n\t\tproviderBreakerRegistry.set(chainId, breaker);\n\t}\n\treturn breaker;\n}\n\n// ---------------------------------------------------------------------------\n// 换道主体\n// ---------------------------------------------------------------------------\n\ninterface FailoverAttempt {\n\treadonly model: Model<Api>;\n\treadonly role: \"primary\" | \"backup\";\n}\n\ninterface AttemptFailure {\n\treadonly model: Model<Api>;\n\t/** 失败尝试的原始错误消息（照透传；诊断与事件只做展示截断）。 */\n\treadonly message: AssistantMessage;\n}\n\ntype AttemptOutcome =\n\t| { readonly outcome: \"done\"; readonly message: AssistantMessage }\n\t| { readonly outcome: \"aborted\"; readonly message: AssistantMessage }\n\t/** 已过提交边界（内容增量已释放）的 error：终态已转发，不可换道。 */\n\t| { readonly outcome: \"failed-forwarded\"; readonly message: AssistantMessage }\n\t/** 未过提交边界的 error：上层尚未看到任何事件，可安全重放。 */\n\t| { readonly outcome: \"failed-switchable\"; readonly failure: AttemptFailure };\n\nconst isCommittedDelta = (event: { type: string }): boolean =>\n\tevent.type === \"text_delta\" || event.type === \"thinking_delta\" || event.type === \"toolcall_delta\";\n\nfunction truncateRawError(text: string | undefined): string {\n\tconst value = text === undefined || text === \"\" ? \"unknown error\" : text;\n\treturn value.length > RAW_ERROR_MAX_LENGTH ? `${value.slice(0, RAW_ERROR_MAX_LENGTH)}…[truncated]` : value;\n}\n\nfunction createThrownErrorMessage(model: Model<Api>, error: unknown, nowMs: number): AssistantMessage {\n\treturn {\n\t\trole: \"assistant\",\n\t\tcontent: [],\n\t\tapi: model.api,\n\t\tprovider: model.provider,\n\t\tmodel: model.id,\n\t\tusage: {\n\t\t\tinput: 0,\n\t\t\toutput: 0,\n\t\t\tcacheRead: 0,\n\t\t\tcacheWrite: 0,\n\t\t\ttotalTokens: 0,\n\t\t\tcost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },\n\t\t},\n\t\tstopReason: \"error\",\n\t\terrorMessage: error instanceof Error ? error.message : String(error),\n\t\ttimestamp: nowMs,\n\t};\n}\n\n/**\n * 换道重放的凭据剔除（设计 §4.4）：apiKey/headers/env 是主 provider 的预解析\n * 凭据，照抄重放会把主的 key 发给备用 provider——剔除后由目标 provider 经\n * 宿主 auth 解析重新注入。其余 options（signal、预算、缓存策略等）原样保留。\n */\nfunction stripCredentialOptions(options: SimpleStreamOptions | undefined): SimpleStreamOptions | undefined {\n\tif (options === undefined) return undefined;\n\tconst { apiKey: _apiKey, headers: _headers, env: _env, ...rest } = options;\n\treturn rest;\n}\n\n/** 候选序列解析（设计 §4.1）：显式链优先，否则 backupProviders 按声明顺序同 id 匹配。 */\nfunction resolveFailoverCandidates(\n\tmodel: Model<Api>,\n\tconfig: ResolvedFailoverConfig,\n\tresolveModel: (provider: string, modelId: string) => Model<Api> | undefined,\n): Model<Api>[] {\n\tconst reference = `${model.provider}/${model.id}`;\n\tconst chain = config.chains.find((entry) => entry.primary === reference);\n\tif (chain !== undefined) {\n\t\tconst candidates: Model<Api>[] = [];\n\t\tfor (const backup of chain.backups) {\n\t\t\tconst parsed = parseModelReference(backup);\n\t\t\tconst resolved = parsed === undefined ? undefined : resolveModel(parsed.provider, parsed.modelId);\n\t\t\tif (resolved === undefined) continue;\n\t\t\tif (resolved.provider === model.provider && resolved.id === model.id) continue;\n\t\t\tcandidates.push(resolved);\n\t\t}\n\t\treturn candidates;\n\t}\n\tconst candidates: Model<Api>[] = [];\n\tfor (const providerId of config.backupProviders) {\n\t\t// 含主 provider 自身 → 忽略该项（设计 §4.1）。\n\t\tif (providerId === model.provider) continue;\n\t\tconst resolved = resolveModel(providerId, model.id);\n\t\tif (resolved !== undefined) candidates.push(resolved);\n\t}\n\treturn candidates;\n}\n\ninterface ProviderFailoverRuntimeDeps {\n\treadonly runtime: CapabilityRuntime;\n\treadonly config: ResolvedFailoverConfig;\n\treadonly now: () => number;\n\t/**\n\t * 会话日志快照通道（宿主声明 `session` feature 时在场；最小宿主可缺席）。\n\t * 缺席只损失 footer 可见性，不影响换道判定。\n\t */\n\treadonly session?: Pick<SessionAPI, \"appendEntry\">;\n\t/** 快照写入失败的警告通道；缺省静默（与 lifecycle 事件通道同级）。 */\n\treadonly hostLogger?: HostLogger;\n}\n\n/**\n * 写一条熔断状态快照进会话日志（设计 §4.7 Phase 3）。尽力通道：失败不打断\n * 换道判定，但经进程日志警告保持失败可见。\n */\nfunction writeStateSnapshot(deps: ProviderFailoverRuntimeDeps, snapshot: ProviderFailoverStateSnapshot): void {\n\tif (deps.session === undefined) return;\n\ttry {\n\t\tdeps.session.appendEntry(PROVIDER_FAILOVER_STATE_ENTRY_TYPE, snapshot);\n\t} catch (error) {\n\t\tdeps.hostLogger?.warn(\"provider-failover\", \"failover state snapshot append failed\", { cause: error });\n\t}\n}\n\n/** OPEN 转移点（阈值打开 / 试探失败重开）共用的 open 快照。 */\nfunction writeOpenStateSnapshot(\n\tdeps: ProviderFailoverRuntimeDeps,\n\tchainId: string,\n\tbreaker: ProviderBreakerState,\n\tbackupReference: string | undefined,\n): void {\n\twriteStateSnapshot(deps, {\n\t\tversion: 1,\n\t\tchainId,\n\t\tstatus: \"open\",\n\t\t...(backupReference === undefined ? {} : { backupProvider: backupReference }),\n\t\tprobeAtMs: breaker.openedAtMs + breaker.cooldownMs,\n\t\tnow: breaker.openedAtMs,\n\t});\n}\n\nfunction dispatchFailoverEvent(deps: ProviderFailoverRuntimeDeps, request: LifecycleDispatchRequest): void {\n\ttry {\n\t\tif (!deps.runtime.hasLifecycleEvent(request.type, request.version)) return;\n\t\tvoid deps.runtime.dispatchLifecycle(request).catch(() => {\n\t\t\t// 可见性事件失败不打断换道判定（宪法 §8 的尽力通道）。\n\t\t});\n\t} catch {\n\t\t// 同上：派发入口同步抛错也不影响请求路径。\n\t}\n}\n\nfunction createFailoverWrapper(deps: ProviderFailoverRuntimeDeps): StreamFnWrapper {\n\treturn (modelArgument, contextArgument, optionsArgument, next, host) => {\n\t\tconst model = modelArgument as Model<Api>;\n\t\tconst context = contextArgument as Context;\n\t\tconst options = optionsArgument as SimpleStreamOptions | undefined;\n\t\tconst outer = createAssistantMessageEventStream();\n\t\tconst resolveModel = (provider: string, modelId: string): Model<Api> | undefined =>\n\t\t\thost.resolveModel(provider, modelId) as Model<Api> | undefined;\n\t\tvoid driveFailoverStream(deps, outer, model, context, options, next, resolveModel);\n\t\treturn outer;\n\t};\n}\n\nasync function driveFailoverStream(\n\tdeps: ProviderFailoverRuntimeDeps,\n\touter: AssistantMessageEventStream,\n\tmodel: Model<Api>,\n\tcontext: Context,\n\toptions: SimpleStreamOptions | undefined,\n\tnext: (model: unknown, context: unknown, options: unknown) => unknown,\n\tresolveModel: (provider: string, modelId: string) => Model<Api> | undefined,\n): Promise<void> {\n\tconst { config } = deps;\n\tconst nowMs = deps.now();\n\tconst chainId = `${model.provider}/${model.id}`;\n\tconst breaker = getBreaker(chainId, config);\n\n\t// 入场判定（设计 §4.3 判定表）：CLOSED/HALF_OPEN 撞主，OPEN 且冷却未满落备用。\n\tlet attemptPrimary = true;\n\tlet isProbe = false;\n\tif (breaker.status === \"open\") {\n\t\tif (nowMs - breaker.openedAtMs >= breaker.cooldownMs) {\n\t\t\t// 冷却期满：下一个真实请求改道回主作试探（HALF_OPEN 并发放行）。\n\t\t\tbreaker.status = \"half-open\";\n\t\t\tisProbe = true;\n\t\t} else {\n\t\t\tattemptPrimary = false;\n\t\t}\n\t} else if (breaker.status === \"half-open\") {\n\t\tisProbe = true;\n\t}\n\n\tconst candidates = resolveFailoverCandidates(model, config, resolveModel);\n\t// OPEN 期请求从链头重走（设计 §4.3），快照披露的换道目标 = 链头候选。\n\tconst backupReference = candidates[0] === undefined ? undefined : `${candidates[0].provider}/${candidates[0].id}`;\n\n\tconst attempts: FailoverAttempt[] = [];\n\tif (attemptPrimary) attempts.push({ model, role: \"primary\" });\n\tfor (const candidate of candidates) attempts.push({ model: candidate, role: \"backup\" });\n\tif (attempts.length === 0) {\n\t\t// OPEN 且候选为空：无别处可去，直发主（按普通主请求计账，不作试探）。\n\t\tattempts.push({ model, role: \"primary\" });\n\t}\n\n\tconst failures: AttemptFailure[] = [];\n\tlet switchOrdinal = 0;\n\tfor (let index = 0; index < attempts.length; index++) {\n\t\tconst attempt = attempts[index];\n\t\tconst attemptOptions = attempt.role === \"backup\" ? stripCredentialOptions(options) : options;\n\t\tconst result = await runFailoverAttempt(outer, next, attempt.model, context, attemptOptions, deps.now);\n\n\t\tif (result.outcome === \"done\") {\n\t\t\tif (attempt.role === \"primary\") {\n\t\t\t\tbreaker.status = \"closed\";\n\t\t\t\tbreaker.consecutiveFailures = 0;\n\t\t\t\tbreaker.cooldownMs = config.cooldownInitialMs;\n\t\t\t\tif (isProbe) {\n\t\t\t\t\tdispatchFailoverEvent(deps, {\n\t\t\t\t\t\ttype: PROVIDER_FAILOVER_RECOVERED_EVENT_ID,\n\t\t\t\t\t\tversion: PROVIDER_FAILOVER_RECOVERED_EVENT_VERSION,\n\t\t\t\t\t\tphase: \"committed\",\n\t\t\t\t\t\tsource: PROVIDER_FAILOVER_PLUGIN_ID,\n\t\t\t\t\t\tdata: { version: 1, chainId, provider: model.provider },\n\t\t\t\t\t});\n\t\t\t\t\t// HALF_OPEN → CLOSED 转移点：footer 摘要行随最后一条 closed 快照消失。\n\t\t\t\t\twriteStateSnapshot(deps, {\n\t\t\t\t\t\tversion: 1,\n\t\t\t\t\t\tchainId,\n\t\t\t\t\t\tstatus: \"closed\",\n\t\t\t\t\t\tprobeAtMs: 0,\n\t\t\t\t\t\tnow: deps.now(),\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t}\n\t\t\t// 备用成败不影响 primary 熔断状态（设计 §4.2）。\n\t\t\treturn;\n\t\t}\n\n\t\tif (result.outcome === \"aborted\") {\n\t\t\t// 用户本地取消：不计数、不换道、状态不变（设计 §2/§4.3）。\n\t\t\treturn;\n\t\t}\n\n\t\tif (result.outcome === \"failed-forwarded\") {\n\t\t\t// 已过提交边界：不可重放，交回合级重试；主失败照常计数。\n\t\t\tif (attempt.role === \"primary\") {\n\t\t\t\trecordPrimaryFailure(deps, breaker, config, chainId, result.message, isProbe, backupReference);\n\t\t\t}\n\t\t\treturn;\n\t\t}\n\n\t\t// failed-switchable：无可见内容，可换道重放。\n\t\tfailures.push(result.failure);\n\t\tif (attempt.role === \"primary\") {\n\t\t\trecordPrimaryFailure(deps, breaker, config, chainId, result.failure.message, isProbe, backupReference);\n\t\t}\n\n\t\tif (index + 1 < attempts.length) {\n\t\t\tswitchOrdinal += 1;\n\t\t\tconst target = attempts[index + 1];\n\t\t\tdispatchFailoverEvent(deps, {\n\t\t\t\ttype: PROVIDER_FAILOVER_SWITCHED_EVENT_ID,\n\t\t\t\tversion: PROVIDER_FAILOVER_SWITCHED_EVENT_VERSION,\n\t\t\t\tphase: \"committed\",\n\t\t\t\tsource: PROVIDER_FAILOVER_PLUGIN_ID,\n\t\t\t\tdata: {\n\t\t\t\t\tversion: 1,\n\t\t\t\t\tchainId,\n\t\t\t\t\tfrom: `${attempt.model.provider}/${attempt.model.id}`,\n\t\t\t\t\tto: `${target.model.provider}/${target.model.id}`,\n\t\t\t\t\tattempt: switchOrdinal,\n\t\t\t\t\trawError: truncateRawError(result.failure.message.errorMessage),\n\t\t\t\t},\n\t\t\t});\n\t\t\tcontinue;\n\t\t}\n\t\tbreak;\n\t}\n\n\t// 全链尽：报链内最后一次实际失败的原始错误 + 整链摘要进 diagnostics（设计 §4.3）。\n\tconst lastFailure = failures[failures.length - 1];\n\tif (lastFailure === undefined) {\n\t\t// 不可达（至少一次 failed-switchable 才会走到这里）；保守以合成错误收尾。\n\t\tconst message = createThrownErrorMessage(model, new Error(\"provider failover exhausted the chain\"), deps.now());\n\t\touter.push({ type: \"error\", reason: \"error\", error: message });\n\t\touter.end();\n\t\treturn;\n\t}\n\tconst diagnostic: AssistantMessageDiagnostic = {\n\t\ttype: \"provider-failover\",\n\t\ttimestamp: deps.now(),\n\t\tdetails: {\n\t\t\tchainId,\n\t\t\tattempts: failures.map((failure) => ({\n\t\t\t\tprovider: failure.model.provider,\n\t\t\t\tmodel: failure.model.id,\n\t\t\t\terror: truncateRawError(failure.message.errorMessage),\n\t\t\t})),\n\t\t},\n\t};\n\tconst finalMessage: AssistantMessage = {\n\t\t...lastFailure.message,\n\t\tdiagnostics: [...(lastFailure.message.diagnostics ?? []), diagnostic],\n\t};\n\touter.push({ type: \"error\", reason: \"error\", error: finalMessage });\n\touter.end();\n}\n\n/**\n * 主失败计账（设计 §4.2/§4.3）：CLOSED 期连续 N 次达到阈值 → OPEN（冷却取\n * initialMs）；HALF_OPEN 试探失败 → OPEN 且冷却 ×2 封顶 maxMs（经 probe.failed\n * 事件可见）。backup 的成败永远不进这里。\n */\nfunction recordPrimaryFailure(\n\tdeps: ProviderFailoverRuntimeDeps,\n\tbreaker: ProviderBreakerState,\n\tconfig: ResolvedFailoverConfig,\n\tchainId: string,\n\tmessage: AssistantMessage,\n\tisProbe: boolean,\n\tbackupReference: string | undefined,\n): void {\n\tif (isProbe) {\n\t\topenAfterFailedProbe(deps, breaker, config, chainId, message, backupReference);\n\t\treturn;\n\t}\n\tbreaker.consecutiveFailures += 1;\n\tif (breaker.consecutiveFailures >= config.failureThreshold) {\n\t\tbreaker.status = \"open\";\n\t\tbreaker.cooldownMs = config.cooldownInitialMs;\n\t\tbreaker.openedAtMs = deps.now();\n\t\twriteOpenStateSnapshot(deps, chainId, breaker, backupReference);\n\t}\n}\n\n/** HALF_OPEN 试探失败：回 OPEN，冷却 ×2 封顶 maxMs，并派发 probe.failed（设计 §4.2）。 */\nfunction openAfterFailedProbe(\n\tdeps: ProviderFailoverRuntimeDeps,\n\tbreaker: ProviderBreakerState,\n\tconfig: ResolvedFailoverConfig,\n\tchainId: string,\n\tmessage: AssistantMessage,\n\tbackupReference: string | undefined,\n): void {\n\tbreaker.status = \"open\";\n\tbreaker.cooldownMs = Math.min(breaker.cooldownMs * 2, config.cooldownMaxMs);\n\tbreaker.openedAtMs = deps.now();\n\tdispatchFailoverEvent(deps, {\n\t\ttype: PROVIDER_FAILOVER_PROBE_FAILED_EVENT_ID,\n\t\tversion: PROVIDER_FAILOVER_PROBE_FAILED_EVENT_VERSION,\n\t\tphase: \"committed\",\n\t\tsource: PROVIDER_FAILOVER_PLUGIN_ID,\n\t\tdata: {\n\t\t\tversion: 1,\n\t\t\tchainId,\n\t\t\tprovider: message.provider,\n\t\t\trawError: truncateRawError(message.errorMessage),\n\t\t\tnextCooldownMs: breaker.cooldownMs,\n\t\t},\n\t});\n\twriteOpenStateSnapshot(deps, chainId, breaker, backupReference);\n}\n\nasync function runFailoverAttempt(\n\touter: AssistantMessageEventStream,\n\tnext: (model: unknown, context: unknown, options: unknown) => unknown,\n\tattemptModel: Model<Api>,\n\tcontext: Context,\n\toptions: SimpleStreamOptions | undefined,\n\tnow: () => number,\n): Promise<AttemptOutcome> {\n\tlet inner: AssistantMessageEventStream;\n\ttry {\n\t\tinner = (await next(attemptModel, context, options)) as AssistantMessageEventStream;\n\t} catch (error) {\n\t\tconst message = createThrownErrorMessage(attemptModel, error, now());\n\t\treturn { outcome: \"failed-switchable\", failure: { model: attemptModel, message } };\n\t}\n\n\t// 前奏事件缓冲（设计 §4.4）：提交边界（首个内容增量）或正常完成前不释放，\n\t// 使\"无可见内容\"的失败可以整段丢弃后无感重放。非增量、非终态事件（start、\n\t// *_start、*_end 及未知扩展事件）一律入缓冲——保守归入前奏，重放安全性优先。\n\tconst buffered: AssistantMessageEvent[] = [];\n\tlet committed = false;\n\tconst flushBuffer = (): void => {\n\t\tfor (const event of buffered) outer.push(event);\n\t\tbuffered.length = 0;\n\t};\n\ttry {\n\t\tfor await (const event of inner) {\n\t\t\tif (event.type === \"done\") {\n\t\t\t\tflushBuffer();\n\t\t\t\touter.push(event);\n\t\t\t\touter.end();\n\t\t\t\treturn { outcome: \"done\", message: event.message };\n\t\t\t}\n\t\t\tif (event.type === \"error\") {\n\t\t\t\tif (event.reason === \"aborted\") {\n\t\t\t\t\t// 不重放的终态：丢弃缓冲只发终态，避免上层收到孤立 start。\n\t\t\t\t\touter.push(event);\n\t\t\t\t\touter.end();\n\t\t\t\t\treturn { outcome: \"aborted\", message: event.error };\n\t\t\t\t}\n\t\t\t\tif (committed) {\n\t\t\t\t\touter.push(event);\n\t\t\t\t\touter.end();\n\t\t\t\t\treturn { outcome: \"failed-forwarded\", message: event.error };\n\t\t\t\t}\n\t\t\t\treturn { outcome: \"failed-switchable\", failure: { model: attemptModel, message: event.error } };\n\t\t\t}\n\t\t\tif (isCommittedDelta(event)) {\n\t\t\t\tif (!committed) {\n\t\t\t\t\tcommitted = true;\n\t\t\t\t\tflushBuffer();\n\t\t\t\t}\n\t\t\t\touter.push(event);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (committed) outer.push(event);\n\t\t\telse buffered.push(event);\n\t\t}\n\t} catch (error) {\n\t\tconst message = createThrownErrorMessage(attemptModel, error, now());\n\t\tif (committed) {\n\t\t\tconst errorEvent = { type: \"error\" as const, reason: \"error\" as const, error: message };\n\t\t\touter.push(errorEvent);\n\t\t\touter.end();\n\t\t\treturn { outcome: \"failed-forwarded\", message };\n\t\t}\n\t\treturn { outcome: \"failed-switchable\", failure: { model: attemptModel, message } };\n\t}\n\n\t// 流自然结束但没有终止信号：按设计 §2 的归一哲学视作 error 终态。\n\tconst message = createThrownErrorMessage(attemptModel, new Error(\"stream ended without a terminal event\"), now());\n\tif (committed) {\n\t\touter.push({ type: \"error\", reason: \"error\", error: message });\n\t\touter.end();\n\t\treturn { outcome: \"failed-forwarded\", message };\n\t}\n\treturn { outcome: \"failed-switchable\", failure: { model: attemptModel, message } };\n}\n\n// ---------------------------------------------------------------------------\n// 装载预检（设计 §4.6：插件安装时同步执行的静态检查，零网络请求）\n// ---------------------------------------------------------------------------\n\n/**\n * 装载预检的宿主静态检查面（设计 §4.6）。全部为目录/凭据快照读取：不发网络\n * 请求、不触发 OAuth 刷新（凭据检查与 ModelRuntime.hasConfiguredAuth 同构——\n * 只读\"该 provider 是否有凭据条目\"，不做可用性探测）。\n */\nexport interface ProviderFailoverPreflightChecks {\n\t/** 目录解析，与运行时换道候选解析同一面。 */\n\treadonly resolveModel: (provider: string, modelId: string) => Model<Api> | undefined;\n\t/** provider 在组合目录（builtin + models.json + 扩展）中存在（backupProviders 层预检）。 */\n\treadonly hasProvider: (providerId: string) => boolean;\n\t/** provider 有凭据条目（静态；不触发 OAuth 刷新）。 */\n\treadonly hasConfiguredAuth: (providerId: string) => boolean;\n}\n\n/**\n * 稳定序列化（键排序、剔除 undefined）：compat/thinkingLevelMap 的派生差异按\n * 值比较，不依赖对象键序。\n */\nfunction stableStringify(value: unknown): string {\n\tif (value === undefined) return \"∅\";\n\tif (value === null || typeof value !== \"object\") return JSON.stringify(value) ?? String(value);\n\tif (Array.isArray(value)) return `[${value.map(stableStringify).join(\",\")}]`;\n\tconst entries = Object.entries(value as Record<string, unknown>)\n\t\t.filter(([, entryValue]) => entryValue !== undefined)\n\t\t.sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));\n\treturn `{${entries.map(([key, entryValue]) => `${JSON.stringify(key)}:${stableStringify(entryValue)}`).join(\",\")}}`;\n}\n\n/**\n * 显式链全量预检（设计 §4.6）：每个 backup 逐一检查，失败条目从链中剔除并\n * 警告；主不可解析 → 整链跳过。contextWindow/compat/thinkingLevelMap/maxTokens\n * 差异只进警告清单、不硬拦——实施裁量：contextWindow 低于主的备用对小上下文\n * 请求仍可成功，剔除条目会静默损失兜底；只有上下文逼近主窗口的请求才必失败，\n * 该情形运行时走链内下一候选，有界。\n */\nfunction preflightExplicitChain(\n\tchain: FailoverChainDeclaration,\n\tchecks: ProviderFailoverPreflightChecks,\n\twarn: (message: string) => void,\n): FailoverChainDeclaration | undefined {\n\tconst parsedPrimary = parseModelReference(chain.primary);\n\tconst primaryModel =\n\t\tparsedPrimary === undefined ? undefined : checks.resolveModel(parsedPrimary.provider, parsedPrimary.modelId);\n\tif (parsedPrimary === undefined || primaryModel === undefined) {\n\t\twarn(`failover chain \"${chain.primary}\" primary does not resolve in the model catalog; skipping the chain`);\n\t\treturn undefined;\n\t}\n\tconst backups: string[] = [];\n\tfor (const backup of chain.backups) {\n\t\tconst parsed = parseModelReference(backup);\n\t\tconst backupModel = parsed === undefined ? undefined : checks.resolveModel(parsed.provider, parsed.modelId);\n\t\tif (parsed === undefined || backupModel === undefined) {\n\t\t\twarn(\n\t\t\t\t`failover chain \"${chain.primary}\" backup \"${backup}\" does not resolve in the model catalog; skipping it`,\n\t\t\t);\n\t\t\tcontinue;\n\t\t}\n\t\tif (!checks.hasConfiguredAuth(backupModel.provider)) {\n\t\t\twarn(\n\t\t\t\t`failover chain \"${chain.primary}\" backup provider \"${backupModel.provider}\" has no configured credentials; skipping \"${backup}\"`,\n\t\t\t);\n\t\t\tcontinue;\n\t\t}\n\t\tif (backupModel.contextWindow < primaryModel.contextWindow) {\n\t\t\twarn(\n\t\t\t\t`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)`,\n\t\t\t);\n\t\t}\n\t\tif (backupModel.maxTokens !== primaryModel.maxTokens) {\n\t\t\twarn(\n\t\t\t\t`failover chain \"${chain.primary}\" backup \"${backup}\" maxTokens (${backupModel.maxTokens}) differs from the primary's (${primaryModel.maxTokens}); output budget may change after switching`,\n\t\t\t);\n\t\t}\n\t\tif (stableStringify(backupModel.compat) !== stableStringify(primaryModel.compat)) {\n\t\t\twarn(\n\t\t\t\t`failover chain \"${chain.primary}\" backup \"${backup}\" compat differs from the primary's; request derivation may change after switching`,\n\t\t\t);\n\t\t}\n\t\tif (stableStringify(backupModel.thinkingLevelMap) !== stableStringify(primaryModel.thinkingLevelMap)) {\n\t\t\twarn(\n\t\t\t\t`failover chain \"${chain.primary}\" backup \"${backup}\" thinkingLevelMap differs from the primary's; reasoning level mapping may change after switching`,\n\t\t\t);\n\t\t}\n\t\tbackups.push(backup);\n\t}\n\tif (backups.length === 0 && chain.backups.length > 0) {\n\t\twarn(\n\t\t\t`failover chain \"${chain.primary}\" has no usable backups left after preflight; the primary keeps no failover candidates from this chain`,\n\t\t);\n\t}\n\treturn { primary: chain.primary, backups };\n}\n\n/**\n * backupProviders 层预检（设计 §4.6）：仅检 provider 存在 + 凭据条目；模型匹配\n * 留运行时（目录同 id 匹配不到时静默跳过，不算失败）。\n */\nfunction preflightBackupProviders(\n\tproviderIds: readonly string[],\n\tchecks: ProviderFailoverPreflightChecks,\n\twarn: (message: string) => void,\n): string[] {\n\tconst retained: string[] = [];\n\tfor (const providerId of providerIds) {\n\t\tif (!checks.hasProvider(providerId)) {\n\t\t\twarn(`failover.backupProviders entry \"${providerId}\" is not a known provider; skipping it`);\n\t\t\tcontinue;\n\t\t}\n\t\tif (!checks.hasConfiguredAuth(providerId)) {\n\t\t\twarn(`failover.backupProviders entry \"${providerId}\" has no configured credentials; skipping it`);\n\t\t\tcontinue;\n\t\t}\n\t\tretained.push(providerId);\n\t}\n\treturn retained;\n}\n\n/**\n * 装载预检主体：返回过滤后的派生配置（预检失败条目已从候选源剔除）。不改变\n * 运行时换道判定——过滤只发生在装载期，运行时候选解析逻辑不变。\n */\nfunction runProviderFailoverPreflight(\n\tconfig: ResolvedFailoverConfig,\n\tchecks: ProviderFailoverPreflightChecks,\n\twarn: (message: string) => void,\n): ResolvedFailoverConfig {\n\tconst backupProviders = preflightBackupProviders(config.backupProviders, checks, warn);\n\tconst chains: FailoverChainDeclaration[] = [];\n\tfor (const chain of config.chains) {\n\t\tconst preflighted = preflightExplicitChain(chain, checks, warn);\n\t\tif (preflighted !== undefined) chains.push(preflighted);\n\t}\n\treturn { ...config, backupProviders, chains };\n}\n\n// ---------------------------------------------------------------------------\n// 装配\n// ---------------------------------------------------------------------------\n\nexport interface ProviderFailoverInstallOptions {\n\t/** settings `failover` 节的原始合并值（经 readProviderFailoverSettingsNode 读取）。 */\n\treadonly failoverSettings: unknown;\n\t/**\n\t * 装载预检宿主检查面（设计 §4.6）：全部静态读取，零网络、零 OAuth 刷新。\n\t * 必传——预检是安装契约的一部分，宿主缺失检查面时不应静默退化为无预检。\n\t */\n\treadonly preflight: ProviderFailoverPreflightChecks;\n\t/** 注入时钟（测试用确定性时间）；缺省 Date.now。 */\n\treadonly now?: () => number;\n\t/** 宿主进程日志；缺省时配置警告静默丢弃。 */\n\treadonly hostLogger?: HostLogger;\n}\n\n/**\n * 装配嵌入式 provider-failover 插件（设计 §4.8）。\n *\n * - 未配置 / `enabled: false` / 配置错误（已警告）→ 返回 undefined，不注册任何面。\n * - 配置解析完成后同步执行装载预检（设计 §4.6）：失败条目从候选源剔除并警告，\n *   警告经模块级去重每进程至多一次；预检不阻断其余条目与主 provider 的正常使用。\n * - 宿主侧装配失败由调用方兜底（failover 是可靠性能力，装载失败不得阻断会话）。\n * - 熔断状态是模块级单例：本函数跨会话重复调用注册的是新包装器实例，但共享\n *   同一份状态（设计 §4.2）。\n */\nexport function installProviderFailoverPlugin(\n\truntime: CapabilityRuntime,\n\toptions: ProviderFailoverInstallOptions,\n): CapabilityPluginHandle | undefined {\n\tconst warn =\n\t\toptions.hostLogger === undefined\n\t\t\t? (_message: string) => {}\n\t\t\t: (message: string) => {\n\t\t\t\t\toptions.hostLogger?.warn(\"provider-failover\", message);\n\t\t\t\t};\n\tconst config = parseProviderFailoverConfig(options.failoverSettings, warn);\n\tif (config === undefined) return undefined;\n\tconst warnPreflightOnce = (message: string): void => {\n\t\tif (preflightWarnedMessages.has(message)) return;\n\t\tpreflightWarnedMessages.add(message);\n\t\twarn(message);\n\t};\n\tconst preflighted = runProviderFailoverPreflight(config, options.preflight, warnPreflightOnce);\n\tconst now = options.now ?? (() => Date.now());\n\treturn loadCapabilityPluginSync(\n\t\truntime,\n\t\t{\n\t\t\tid: PROVIDER_FAILOVER_PLUGIN_ID,\n\t\t\tversion: \"0.0.0\",\n\t\t\tapiVersion: EXPERIMENTAL_PUBLIC_API_VERSION,\n\t\t\tentry: \"<embedded:provider-failover>\",\n\t\t},\n\t\t(api) => {\n\t\t\t// 快照通道绑定本会话的公共 session 面（宿主声明 session feature 时在场）：\n\t\t\t// 会话 A 触发的熔断只写进 A 的日志，footer 可见性是会话局部的（设计 §4.7\n\t\t\t// 保真度限制）。deps 须在此构建——api 只在工厂内可得。\n\t\t\tconst deps: ProviderFailoverRuntimeDeps = {\n\t\t\t\truntime,\n\t\t\t\tconfig: preflighted,\n\t\t\t\tnow,\n\t\t\t\tsession: api.session,\n\t\t\t\t...(options.hostLogger === undefined ? {} : { hostLogger: options.hostLogger }),\n\t\t\t};\n\t\t\tapi.registerStreamFnWrapper(PROVIDER_FAILOVER_WRAPPER_NAME, createFailoverWrapper(deps));\n\t\t\t// 装配期初始快照（status closed）覆盖恢复会话里的陈旧 open 残留：熔断\n\t\t\t// 状态不持久化，新进程恒 CLOSED（设计 §4.2/§4.7）。无链上下文 → chainId 空。\n\t\t\twriteStateSnapshot(deps, { version: 1, chainId: \"\", status: \"closed\", probeAtMs: 0, now: deps.now() });\n\t\t},\n\t);\n}\n"]}

package/dist/core/tools/bash.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"bash.d.ts","sourceRoot":"","sources":["../../../src/core/tools/bash.ts"],"names":[],"mappings":"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","sourcesContent":["import { constants } from \"node:fs\";\nimport { access as fsAccess } from \"node:fs/promises\";\nimport { constants as osConstants } from \"node:os\";\nimport type { AgentTool } from \"@agent-forge/agent-core\";\nimport { Container, Text, truncateToWidth } from \"@agent-forge/tui\";\nimport { spawn } from \"child_process\";\nimport { type Static, Type } from \"typebox\";\nimport { keyHint } from \"../../modes/interactive/components/keybinding-hints.ts\";\nimport { truncateToVisualLines } from \"../../modes/interactive/components/visual-truncate.ts\";\nimport { theme } from \"../../modes/interactive/theme/theme.ts\";\nimport { waitForChildProcess } from \"../../utils/child-process.ts\";\nimport {\n\tgetShellConfig,\n\tgetShellEnv,\n\tkillProcessTree,\n\ttype ShellConfig,\n\ttrackDetachedChildPid,\n\tuntrackDetachedChildPid,\n} from \"../../utils/shell.ts\";\nimport { t } from \"../i18n/index.ts\";\nimport { OutputAccumulator } from \"./output-accumulator.ts\";\nimport { getTextOutput, invalidArgText, str } from \"./render-utils.ts\";\nimport type { ToolDefinition, ToolExecuteContext, ToolRenderResultOptions } from \"./tool-definition.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\nimport { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, type TruncationResult } from \"./truncate.ts\";\n\nconst MAX_TIMEOUT_MS = 2_147_483_647;\nconst MAX_TIMEOUT_SECONDS = MAX_TIMEOUT_MS / 1000;\n\nfunction resolveTimeoutMs(timeout: number | undefined): number | undefined {\n\tif (timeout === undefined) return undefined;\n\tif (!Number.isFinite(timeout) || timeout <= 0) {\n\t\tthrow new Error(t(\"Invalid timeout: must be a finite number of seconds\"));\n\t}\n\n\tconst timeoutMs = timeout * 1000;\n\tif (timeoutMs > MAX_TIMEOUT_MS) {\n\t\tthrow new Error(t(\"Invalid timeout: maximum is {maxSeconds} seconds\", { maxSeconds: MAX_TIMEOUT_SECONDS }));\n\t}\n\treturn timeoutMs;\n}\n\nconst bashSchema = Type.Object({\n\tcommand: Type.String({ description: \"Shell command to execute\" }),\n\ttimeout: Type.Optional(Type.Number({ description: \"Timeout in seconds (optional, no default timeout)\" })),\n});\n\nexport const bashToolSystemPromptContribution = {\n\tsnippet: \"Execute bash commands (ls, grep, find, etc.)\",\n\tguidelines: [\"You can inspect AGENT_FORGE_* environment variables for current model and session details.\"],\n} as const;\n\nexport type BashToolInput = Static<typeof bashSchema>;\n\nexport interface BashToolDetails {\n\ttruncation?: TruncationResult;\n\tfullOutputPath?: string;\n}\n\n/**\n * Pluggable operations for the bash tool.\n * Override these to delegate command execution to remote systems (for example SSH).\n */\nexport interface BashOperations {\n\t/**\n\t * Execute a command and stream output.\n\t * @param command The command to execute\n\t * @param cwd Working directory\n\t * @param options Execution options\n\t * @returns Promise resolving to the exit code. Report signal terminations as 128 + signal number;\n\t * a null exit code is treated as a failed command.\n\t */\n\texec: (\n\t\tcommand: string,\n\t\tcwd: string,\n\t\toptions: {\n\t\t\tonData: (data: Buffer) => void;\n\t\t\tsignal?: AbortSignal;\n\t\t\ttimeout?: number;\n\t\t\tenv?: NodeJS.ProcessEnv;\n\t\t},\n\t) => Promise<{ exitCode: number | null }>;\n}\n\n/** Shared process execution used by the built-in shell tools. */\nexport function createLocalShellOperations(shellName: string, resolveShellConfig: () => ShellConfig): BashOperations {\n\treturn {\n\t\texec: async (command, cwd, { onData, signal, timeout, env }) => {\n\t\t\tconst timeoutMs = resolveTimeoutMs(timeout);\n\t\t\tif (signal?.aborted) {\n\t\t\t\tthrow new Error(\"aborted\");\n\t\t\t}\n\t\t\tconst shellConfig = resolveShellConfig();\n\t\t\ttry {\n\t\t\t\tawait fsAccess(cwd, constants.F_OK);\n\t\t\t} catch {\n\t\t\t\tthrow new Error(\n\t\t\t\t\tt(\"Working directory does not exist: {cwd}\\nCannot execute {shellName} commands.\", {\n\t\t\t\t\t\tcwd,\n\t\t\t\t\t\tshellName,\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t}\n\n\t\t\tconst commandFromStdin = shellConfig.commandTransport === \"stdin\";\n\t\t\tconst child = spawn(shellConfig.shell, commandFromStdin ? shellConfig.args : [...shellConfig.args, command], {\n\t\t\t\tcwd,\n\t\t\t\tdetached: process.platform !== \"win32\",\n\t\t\t\tenv: env ?? getShellEnv(),\n\t\t\t\tstdio: [commandFromStdin ? \"pipe\" : \"ignore\", \"pipe\", \"pipe\"],\n\t\t\t\twindowsHide: true,\n\t\t\t});\n\t\t\tif (commandFromStdin) {\n\t\t\t\tchild.stdin?.on(\"error\", () => {});\n\t\t\t\tchild.stdin?.end(command);\n\t\t\t}\n\t\t\tif (child.pid) trackDetachedChildPid(child.pid);\n\t\t\tlet timedOut = false;\n\t\t\tlet timeoutHandle: NodeJS.Timeout | undefined;\n\t\t\tconst onAbort = () => {\n\t\t\t\tif (child.pid) killProcessTree(child.pid);\n\t\t\t};\n\n\t\t\ttry {\n\t\t\t\t// Set timeout if provided.\n\t\t\t\tif (timeoutMs !== undefined) {\n\t\t\t\t\ttimeoutHandle = setTimeout(() => {\n\t\t\t\t\t\ttimedOut = true;\n\t\t\t\t\t\tif (child.pid) killProcessTree(child.pid);\n\t\t\t\t\t}, timeoutMs);\n\t\t\t\t}\n\t\t\t\t// Stream stdout and stderr.\n\t\t\t\tchild.stdout?.on(\"data\", onData);\n\t\t\t\tchild.stderr?.on(\"data\", onData);\n\t\t\t\t// Handle abort signal by killing the entire process tree.\n\t\t\t\tif (signal) {\n\t\t\t\t\tif (signal.aborted) onAbort();\n\t\t\t\t\telse signal.addEventListener(\"abort\", onAbort, { once: true });\n\t\t\t\t}\n\t\t\t\t// Handle shell spawn errors and wait for the process to terminate without hanging\n\t\t\t\t// on inherited stdio handles held by detached descendants.\n\t\t\t\tconst exitCode = await waitForChildProcess(child);\n\t\t\t\tif (signal?.aborted) {\n\t\t\t\t\tthrow new Error(\"aborted\");\n\t\t\t\t}\n\t\t\t\tif (timedOut) {\n\t\t\t\t\tthrow new Error(`timeout:${timeout}`);\n\t\t\t\t}\n\t\t\t\t// A signal-killed shell has no exit code. Use the standard shell convention so\n\t\t\t\t// callers do not mistake the termination for a successful command.\n\t\t\t\tconst signalCode = child.signalCode;\n\t\t\t\treturn { exitCode: exitCode ?? (signalCode ? 128 + (osConstants.signals[signalCode] ?? 0) : 1) };\n\t\t\t} finally {\n\t\t\t\tif (child.pid) untrackDetachedChildPid(child.pid);\n\t\t\t\tif (timeoutHandle) clearTimeout(timeoutHandle);\n\t\t\t\tif (signal) signal.removeEventListener(\"abort\", onAbort);\n\t\t\t}\n\t\t},\n\t};\n}\n\n/**\n * Create bash operations using Agent Forge's built-in local shell execution backend.\n *\n * This is useful for extensions that intercept user_bash and still want Agent Forge's\n * standard local shell behavior while wrapping or rewriting commands.\n */\nexport function createLocalBashOperations(options?: { shellPath?: string }): BashOperations {\n\treturn createLocalShellOperations(\"bash\", () => getShellConfig(options?.shellPath));\n}\n\nexport interface BashSpawnContext {\n\tcommand: string;\n\tcwd: string;\n\tenv: NodeJS.ProcessEnv;\n}\n\nexport type BashSpawnHook = (context: BashSpawnContext) => BashSpawnContext;\n\nfunction resolveSpawnContext(\n\tcommand: string,\n\tcwd: string,\n\tspawnHook: BashSpawnHook | undefined,\n\texposeSessionEnvironment: boolean,\n\tctx: ToolExecuteContext | undefined,\n): BashSpawnContext {\n\tconst env = { ...getShellEnv() };\n\tdelete env.AGENT_FORGE_SESSION_ID;\n\tdelete env.AGENT_FORGE_SESSION_FILE;\n\tdelete env.AGENT_FORGE_PROVIDER;\n\tdelete env.AGENT_FORGE_MODEL;\n\tdelete env.AGENT_FORGE_REASONING_LEVEL;\n\tif (exposeSessionEnvironment && ctx) {\n\t\tconst model = ctx.model;\n\t\tenv.AGENT_FORGE_SESSION_ID = ctx.sessionManager.getSessionId();\n\t\tconst sessionFile = ctx.sessionManager.getSessionFile();\n\t\tif (sessionFile) env.AGENT_FORGE_SESSION_FILE = sessionFile;\n\t\tif (model) {\n\t\t\tenv.AGENT_FORGE_PROVIDER = model.provider;\n\t\t\tenv.AGENT_FORGE_MODEL = model.id;\n\t\t}\n\t\tif (ctx.thinkingLevel) env.AGENT_FORGE_REASONING_LEVEL = ctx.thinkingLevel;\n\t}\n\tconst baseContext: BashSpawnContext = { command, cwd, env };\n\treturn spawnHook ? spawnHook(baseContext) : baseContext;\n}\n\nexport interface BashToolOptions {\n\t/** Custom operations for command execution. Default: local shell */\n\toperations?: BashOperations;\n\t/** Command prefix prepended to every command (for example shell setup commands) */\n\tcommandPrefix?: string;\n\t/** Optional explicit shell path from settings */\n\tshellPath?: string;\n\t/** Expose current Agent Forge session metadata as AGENT_FORGE_* environment variables. Default: true */\n\texposeSessionEnvironment?: boolean;\n\t/** Hook to adjust command, cwd, or env before execution */\n\tspawnHook?: BashSpawnHook;\n}\n\nconst BASH_PREVIEW_LINES = 5;\nconst BASH_UPDATE_THROTTLE_MS = 100;\n\nexport type BashRenderState = {\n\tstartedAt: number | undefined;\n\tendedAt: number | undefined;\n\tinterval: NodeJS.Timeout | undefined;\n};\n\ntype BashResultRenderState = {\n\tcachedWidth: number | undefined;\n\tcachedLines: string[] | undefined;\n};\n\nclass BashResultRenderComponent extends Container {\n\tstate: BashResultRenderState = {\n\t\tcachedWidth: undefined,\n\t\tcachedLines: undefined,\n\t};\n}\n\nfunction formatDuration(ms: number): string {\n\tconst seconds = ms / 1000;\n\tif (seconds < 60) return `${seconds.toFixed(1)}s`;\n\n\tconst totalSeconds = Math.floor(seconds);\n\tconst minutes = Math.floor(totalSeconds / 60);\n\tconst remainder = totalSeconds % 60;\n\tif (minutes < 60) return `${minutes}m ${remainder}s`;\n\n\treturn `${Math.floor(minutes / 60)}h ${minutes % 60}m ${remainder}s`;\n}\n\nfunction formatShellCall(args: { command?: string; timeout?: number } | undefined, prompt: string): string {\n\tconst command = str(args?.command);\n\tconst timeout = args?.timeout as number | undefined;\n\tconst timeoutSuffix = timeout ? theme.fg(\"muted\", ` (timeout ${timeout}s)`) : \"\";\n\tconst commandDisplay = command === null ? invalidArgText(theme) : command ? command : theme.fg(\"toolOutput\", \"...\");\n\treturn theme.fg(\"toolTitle\", theme.bold(`${prompt} ${commandDisplay}`)) + timeoutSuffix;\n}\n\nfunction rebuildBashResultRenderComponent(\n\tcomponent: BashResultRenderComponent,\n\tresult: {\n\t\tcontent: Array<{ type: string; text?: string; data?: string; mimeType?: string }>;\n\t\tdetails?: BashToolDetails;\n\t},\n\toptions: ToolRenderResultOptions,\n\tshowImages: boolean,\n\tstartedAt: number | undefined,\n\tendedAt: number | undefined,\n): void {\n\tconst state = component.state;\n\tcomponent.clear();\n\n\tlet output = getTextOutput(result, showImages).trim();\n\tconst truncation = result.details?.truncation;\n\tconst fullOutputPath = result.details?.fullOutputPath;\n\tif (!options.isPartial && truncation?.truncated && fullOutputPath && output.endsWith(\"]\")) {\n\t\tconst footerStart = output.lastIndexOf(\"\\n\\n[\");\n\t\tif (footerStart !== -1 && output.slice(footerStart).includes(fullOutputPath)) {\n\t\t\toutput = output.slice(0, footerStart).trimEnd();\n\t\t}\n\t}\n\n\tif (output) {\n\t\tconst styledOutput = output\n\t\t\t.split(\"\\n\")\n\t\t\t.map((line) => theme.fg(\"toolOutput\", line))\n\t\t\t.join(\"\\n\");\n\n\t\tif (options.expanded) {\n\t\t\tcomponent.addChild(new Text(`\\n${styledOutput}`, 0, 0));\n\t\t} else {\n\t\t\tcomponent.addChild({\n\t\t\t\trender: (width: number) => {\n\t\t\t\t\t// Cache the complete output: this renders on every frame for every bash result in the transcript.\n\t\t\t\t\tif (state.cachedLines === undefined || state.cachedWidth !== width) {\n\t\t\t\t\t\tconst preview = truncateToVisualLines(styledOutput, BASH_PREVIEW_LINES, width);\n\t\t\t\t\t\tconst hintLines: string[] = [];\n\t\t\t\t\t\tif (preview.skippedCount > 0) {\n\t\t\t\t\t\t\tconst hint =\n\t\t\t\t\t\t\t\ttheme.fg(\"muted\", `... (${preview.skippedCount} earlier lines,`) +\n\t\t\t\t\t\t\t\t` ${keyHint(\"app.tools.expand\", \"to expand\")}${theme.fg(\"muted\", \")\")}`;\n\t\t\t\t\t\t\thintLines.push(truncateToWidth(hint, width, \"...\"));\n\t\t\t\t\t\t}\n\t\t\t\t\t\tstate.cachedLines = [\"\", ...hintLines, ...preview.visualLines];\n\t\t\t\t\t\tstate.cachedWidth = width;\n\t\t\t\t\t}\n\t\t\t\t\treturn state.cachedLines;\n\t\t\t\t},\n\t\t\t\tinvalidate: () => {\n\t\t\t\t\tstate.cachedWidth = undefined;\n\t\t\t\t\tstate.cachedLines = undefined;\n\t\t\t\t},\n\t\t\t});\n\t\t}\n\t}\n\n\tif (truncation?.truncated || fullOutputPath) {\n\t\tconst warnings: string[] = [];\n\t\tif (fullOutputPath) {\n\t\t\twarnings.push(`Full output: ${fullOutputPath}`);\n\t\t}\n\t\tif (truncation?.truncated) {\n\t\t\tif (truncation.truncatedBy === \"lines\") {\n\t\t\t\twarnings.push(`Truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines`);\n\t\t\t} else {\n\t\t\t\twarnings.push(\n\t\t\t\t\t`Truncated: ${truncation.outputLines} lines shown (${formatSize(truncation.maxBytes ?? DEFAULT_MAX_BYTES)} limit)`,\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t\tcomponent.addChild(new Text(`\\n${theme.fg(\"warning\", `[${warnings.join(\". \")}]`)}`, 0, 0));\n\t}\n\n\tif (startedAt !== undefined) {\n\t\tconst label = options.isPartial ? \"Elapsed\" : \"Took\";\n\t\tconst endTime = endedAt ?? Date.now();\n\t\tcomponent.addChild(new Text(`\\n${theme.fg(\"muted\", `${label} ${formatDuration(endTime - startedAt)}`)}`, 0, 0));\n\t}\n}\n\nexport interface ShellToolConfig {\n\tname: string;\n\tlabel: string;\n\tshellName: string;\n\tprompt: string;\n\tpromptSnippet: string;\n\tpromptGuidelines?: readonly string[];\n\ttempFilePrefix: string;\n}\n\nexport function createShellToolDefinition(\n\tcwd: string,\n\tconfig: ShellToolConfig,\n\toptions?: BashToolOptions,\n): ToolDefinition<typeof bashSchema, BashToolDetails | undefined, BashRenderState> {\n\tconst ops = options?.operations ?? createLocalBashOperations({ shellPath: options?.shellPath });\n\tconst commandPrefix = options?.commandPrefix;\n\tconst exposeSessionEnvironment = options?.exposeSessionEnvironment ?? true;\n\tconst spawnHook = options?.spawnHook;\n\treturn {\n\t\tname: config.name,\n\t\tlabel: config.label,\n\t\tdescription: `Execute a ${config.shellName} command in the current working directory. Returns stdout and stderr. Output is truncated to last ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). If truncated, full output is saved to a temp file. Optionally provide a timeout in seconds.`,\n\t\tpromptSnippet: config.promptSnippet,\n\t\tpromptGuidelines: exposeSessionEnvironment && config.promptGuidelines ? [...config.promptGuidelines] : undefined,\n\t\tparameters: bashSchema,\n\t\tconstrainedSampling: { type: \"json_schema\", strict: \"prefer\" },\n\t\tasync execute(\n\t\t\t_toolCallId,\n\t\t\t{ command, timeout }: { command: string; timeout?: number },\n\t\t\tsignal?: AbortSignal,\n\t\t\tonUpdate?,\n\t\t\tctx?: ToolExecuteContext,\n\t\t) {\n\t\t\tconst resolvedCommand = commandPrefix ? `${commandPrefix}\\n${command}` : command;\n\t\t\tconst spawnContext = resolveSpawnContext(\n\t\t\t\tresolvedCommand,\n\t\t\t\tctx?.cwd || cwd,\n\t\t\t\tspawnHook,\n\t\t\t\texposeSessionEnvironment,\n\t\t\t\tctx,\n\t\t\t);\n\t\t\tconst output = new OutputAccumulator({ tempFilePrefix: config.tempFilePrefix });\n\t\t\tlet acceptingOutput = true;\n\t\t\tlet updateTimer: NodeJS.Timeout | undefined;\n\t\t\tlet updateDirty = false;\n\t\t\tlet lastUpdateAt = 0;\n\n\t\t\tconst emitOutputUpdate = () => {\n\t\t\t\tif (!onUpdate || !updateDirty) return;\n\t\t\t\tupdateDirty = false;\n\t\t\t\tlastUpdateAt = Date.now();\n\t\t\t\tconst snapshot = output.snapshot({ persistIfTruncated: true });\n\t\t\t\tonUpdate({\n\t\t\t\t\tcontent: [{ type: \"text\", text: snapshot.content || \"\" }],\n\t\t\t\t\tdetails: {\n\t\t\t\t\t\ttruncation: snapshot.truncation.truncated ? snapshot.truncation : undefined,\n\t\t\t\t\t\tfullOutputPath: snapshot.fullOutputPath,\n\t\t\t\t\t},\n\t\t\t\t});\n\t\t\t};\n\n\t\t\tconst clearUpdateTimer = () => {\n\t\t\t\tif (updateTimer) {\n\t\t\t\t\tclearTimeout(updateTimer);\n\t\t\t\t\tupdateTimer = undefined;\n\t\t\t\t}\n\t\t\t};\n\n\t\t\tconst scheduleOutputUpdate = () => {\n\t\t\t\tif (!onUpdate) return;\n\t\t\t\tupdateDirty = true;\n\t\t\t\tconst delay = BASH_UPDATE_THROTTLE_MS - (Date.now() - lastUpdateAt);\n\t\t\t\tif (delay <= 0) {\n\t\t\t\t\tclearUpdateTimer();\n\t\t\t\t\temitOutputUpdate();\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tupdateTimer ??= setTimeout(() => {\n\t\t\t\t\tupdateTimer = undefined;\n\t\t\t\t\temitOutputUpdate();\n\t\t\t\t}, delay);\n\t\t\t};\n\n\t\t\tif (onUpdate) {\n\t\t\t\tonUpdate({ content: [], details: undefined });\n\t\t\t}\n\n\t\t\tconst handleData = (data: Buffer) => {\n\t\t\t\tif (!acceptingOutput) return;\n\t\t\t\toutput.append(data);\n\t\t\t\tscheduleOutputUpdate();\n\t\t\t};\n\n\t\t\tconst finishOutput = async () => {\n\t\t\t\tacceptingOutput = false;\n\t\t\t\toutput.finish();\n\t\t\t\tclearUpdateTimer();\n\t\t\t\temitOutputUpdate();\n\t\t\t\tconst snapshot = output.snapshot({ persistIfTruncated: true });\n\t\t\t\tawait output.closeTempFile();\n\t\t\t\treturn snapshot;\n\t\t\t};\n\n\t\t\tconst formatOutput = (snapshot: Awaited<ReturnType<typeof finishOutput>>, emptyText = \"(no output)\") => {\n\t\t\t\tconst truncation = snapshot.truncation;\n\t\t\t\tlet text = snapshot.content || emptyText;\n\t\t\t\tlet details: BashToolDetails | undefined;\n\t\t\t\tif (truncation.truncated) {\n\t\t\t\t\tdetails = { truncation, fullOutputPath: snapshot.fullOutputPath };\n\t\t\t\t\tconst startLine = truncation.totalLines - truncation.outputLines + 1;\n\t\t\t\t\tconst endLine = truncation.totalLines;\n\t\t\t\t\tif (truncation.lastLinePartial) {\n\t\t\t\t\t\tconst lastLineSize = formatSize(output.getLastLineBytes());\n\t\t\t\t\t\ttext += `\\n\\n[Showing last ${formatSize(truncation.outputBytes)} of line ${endLine} (line is ${lastLineSize}). Full output: ${snapshot.fullOutputPath}]`;\n\t\t\t\t\t} else if (truncation.truncatedBy === \"lines\") {\n\t\t\t\t\t\ttext += `\\n\\n[Showing lines ${startLine}-${endLine} of ${truncation.totalLines}. Full output: ${snapshot.fullOutputPath}]`;\n\t\t\t\t\t} else {\n\t\t\t\t\t\ttext += `\\n\\n[Showing lines ${startLine}-${endLine} of ${truncation.totalLines} (${formatSize(DEFAULT_MAX_BYTES)} limit). Full output: ${snapshot.fullOutputPath}]`;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\treturn { text, details };\n\t\t\t};\n\n\t\t\tconst appendStatus = (text: string, status: string) => `${text ? `${text}\\n\\n` : \"\"}${status}`;\n\n\t\t\ttry {\n\t\t\t\tlet exitCode: number | null;\n\t\t\t\ttry {\n\t\t\t\t\tconst result = await ops.exec(spawnContext.command, spawnContext.cwd, {\n\t\t\t\t\t\tonData: handleData,\n\t\t\t\t\t\tsignal,\n\t\t\t\t\t\ttimeout,\n\t\t\t\t\t\tenv: spawnContext.env,\n\t\t\t\t\t});\n\t\t\t\t\texitCode = result.exitCode;\n\t\t\t\t} catch (err) {\n\t\t\t\t\tconst snapshot = await finishOutput();\n\t\t\t\t\tconst { text } = formatOutput(snapshot, \"\");\n\t\t\t\t\tif (err instanceof Error && err.message === \"aborted\") {\n\t\t\t\t\t\tthrow new Error(appendStatus(text, t(\"Command aborted\")));\n\t\t\t\t\t}\n\t\t\t\t\tif (err instanceof Error && err.message.startsWith(\"timeout:\")) {\n\t\t\t\t\t\tconst timeoutSecs = err.message.split(\":\")[1];\n\t\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t\tappendStatus(text, t(\"Command timed out after {seconds} seconds\", { seconds: timeoutSecs })),\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t\tthrow err;\n\t\t\t\t}\n\n\t\t\t\tconst snapshot = await finishOutput();\n\t\t\t\tconst { text: outputText, details } = formatOutput(snapshot);\n\t\t\t\tif (exitCode === null) {\n\t\t\t\t\tthrow new Error(appendStatus(outputText, t(\"Command terminated without an exit code\")));\n\t\t\t\t}\n\t\t\t\tif (exitCode !== 0) {\n\t\t\t\t\tthrow new Error(appendStatus(outputText, t(\"Command exited with code {exitCode}\", { exitCode })));\n\t\t\t\t}\n\t\t\t\treturn { content: [{ type: \"text\", text: outputText }], details };\n\t\t\t} finally {\n\t\t\t\tclearUpdateTimer();\n\t\t\t}\n\t\t},\n\t\trenderCall(args, _theme, context) {\n\t\t\tconst state = context.state;\n\t\t\tif (context.executionStarted && state.startedAt === undefined) {\n\t\t\t\tstate.startedAt = Date.now();\n\t\t\t\tstate.endedAt = undefined;\n\t\t\t}\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\ttext.setText(formatShellCall(args, config.prompt));\n\t\t\treturn text;\n\t\t},\n\t\trenderResult(result, options, _theme, context) {\n\t\t\tconst state = context.state;\n\t\t\tif (state.startedAt !== undefined && options.isPartial && !state.interval) {\n\t\t\t\tstate.interval = setInterval(() => context.invalidate(), 1000);\n\t\t\t}\n\t\t\tif (!options.isPartial || context.isError) {\n\t\t\t\tstate.endedAt ??= Date.now();\n\t\t\t\tif (state.interval) {\n\t\t\t\t\tclearInterval(state.interval);\n\t\t\t\t\tstate.interval = undefined;\n\t\t\t\t}\n\t\t\t}\n\t\t\tconst component =\n\t\t\t\t(context.lastComponent as BashResultRenderComponent | undefined) ?? new BashResultRenderComponent();\n\t\t\trebuildBashResultRenderComponent(\n\t\t\t\tcomponent,\n\t\t\t\tresult,\n\t\t\t\toptions,\n\t\t\t\tcontext.showImages,\n\t\t\t\tstate.startedAt,\n\t\t\t\tstate.endedAt,\n\t\t\t);\n\t\t\tcomponent.invalidate();\n\t\t\treturn component;\n\t\t},\n\t};\n}\n\nconst bashToolConfig: ShellToolConfig = {\n\tname: \"bash\",\n\tlabel: \"bash\",\n\tshellName: \"bash\",\n\tprompt: \"$\",\n\tpromptSnippet: bashToolSystemPromptContribution.snippet,\n\tpromptGuidelines: bashToolSystemPromptContribution.guidelines,\n\ttempFilePrefix: \"agent-forge-bash\",\n};\n\nexport function createBashToolDefinition(\n\tcwd: string,\n\toptions?: BashToolOptions,\n): ToolDefinition<typeof bashSchema, BashToolDetails | undefined, BashRenderState> {\n\treturn createShellToolDefinition(cwd, bashToolConfig, options);\n}\n\nexport function createBashTool(cwd: string, options?: BashToolOptions): AgentTool<typeof bashSchema> {\n\tconst definition = createBashToolDefinition(cwd, options);\n\tconst tool = wrapToolDefinition(definition);\n\tObject.assign(tool, {\n\t\tpromptSnippet: definition.promptSnippet,\n\t\tpromptGuidelines: definition.promptGuidelines,\n\t});\n\treturn tool;\n}\n"]}