@bolloon/bolloon-agent 0.5.5 → 0.6.0

package/dist/kernel/model-runtime.js

@@ -0,0 +1,472 @@
+/**
+ * **K6: ModelRuntime 骨架** —— `acquire(modelSnapshot)` **只读**入手。
+ *
+ * 本步只做三件事 (其余能力在 `plan-modelruntime.ts` 里仍是 `not-started`):
+ *   ① **连接复用** (按 snapshot 派生 key 池化, 同一 key 只开一次连接)
+ *   ② **timeout** (按 snapshot 的预算; 超时即中止底层调用, 不是"放弃等待")
+ *   ③ **cancellation** (外部 AbortSignal 透传到连接, 取消真发生)
+ *
+ * 边界 (K6 红线):
+ *   · **只读**: 绝不改 provider 配置 / API key / 默认 URL / Global model / Run snapshot;
+ *   · 不重做既有 `selectModel` / registry / catalog / Run snapshot —— 真正的 provider 调用由 **ports 注入**
+ *     (内核不许 import 业务模块: `KERNEL_ALLOWED_IMPORT_PREFIXES = ['kernel/']`)。
+ *
+ * 通用判据 (K2 实证): **本文件出现后, 旧写口的调用点数不许增加** —— 由 `scanModelRuntimeFile` 机械核对。
+ */
+/** 429 识别 (端口可以把限流表达成返回值 status=429, 或抛一个带 status 的错) */
+export function isRateLimited(x) {
+    if (!x || typeof x !== 'object')
+        return false;
+    const o = x;
+    if (o.status === 429 || o.status === '429')
+        return true;
+    if (typeof o.error === 'string' && /\b429\b|rate ?limit/i.test(o.error))
+        return true;
+    return false;
+}
+/** 退避参数 (写成数据; 实现与测试共用) */
+export const BACKOFF_POLICY = {
+    baseMs: 200,
+    factor: 2,
+    maxMs: 5_000,
+    /** 抖动比例 (±) —— 防止多个调用方同拍重试 */
+    jitter: 0.25,
+    maxRetries: 3,
+};
+/**
+ * 计算第 n 次重试的等待时长 (n 从 0 起): `min(base * factor^n, max)` 再乘 ±jitter。
+ * `retryAfterMs` (供应商给的 Retry-After) 存在时**取最大值** —— 尊重上游而不只是听自己的退避曲线。
+ */
+export function backoffDelayMs(n, opts) {
+    const exp = Math.min(BACKOFF_POLICY.baseMs * BACKOFF_POLICY.factor ** n, BACKOFF_POLICY.maxMs);
+    const r = opts?.random ?? Math.random;
+    const jittered = exp * (1 + BACKOFF_POLICY.jitter * (2 * r() - 1));
+    return Math.max(0, Math.round(Math.max(jittered, opts?.retryAfterMs ?? 0)));
+}
+/**
+ * **熔断策略** (数据; 实现与测试共用)。按 pool key 记连续失败 ⇒ 开路 ⇒ 冷却后半开探测。
+ *   **什么算失败**: 网络/供应商故障类; **不算**: 取消 (调用方的选择) 与 429 (那是退避的活), 见 `countsTowardBreaker`。
+ */
+export const BREAKER_POLICY = {
+    failureThreshold: 3,
+    cooldownMs: 30_000,
+    /** 半开时允许几个探测 */
+    halfOpenProbes: 1,
+    why: '连续失败 ⇒ 开路 (fail fast, 不把故障放大) · 冷却后放一个探测 ⇒ 成功闭合, 失败重新开路',
+};
+/** 这次失败该不该计入熔断 */
+export function countsTowardBreaker(err) {
+    if (err instanceof ModelAbortError)
+        return false; // 调用方取消 ⇒ 不是供应商的错
+    if (err instanceof ModelTimeoutError)
+        return true; // 超时是供应商侧症状
+    if (isRateLimited(err))
+        return false; // 限流交给退避, 不熔断
+    return true;
+}
+export class ModelCircuitOpenError extends Error {
+    retryAtMs;
+    constructor(retryAtMs) {
+        super(`熔断中 (冷却至 ${retryAtMs})`);
+        this.retryAtMs = retryAtMs;
+        this.name = 'ModelCircuitOpenError';
+    }
+}
+export class ModelCapabilityError extends Error {
+    missing;
+    unknown;
+    constructor(missing, unknown = false) {
+        super(unknown ? `未知能力 (snapshot 未声明 capabilities, 无法确认 ${missing.join(', ')})` : `缺能力: ${missing.join(', ')}`);
+        this.missing = missing;
+        this.unknown = unknown;
+        this.name = 'ModelCapabilityError';
+    }
+}
+export class ModelTimeoutError extends Error {
+    budgetMs;
+    constructor(budgetMs) {
+        super(`模型调用超时 (${budgetMs}ms)`);
+        this.budgetMs = budgetMs;
+        this.name = 'ModelTimeoutError';
+    }
+}
+export class ModelAbortError extends Error {
+    constructor() { super('模型调用被取消'); this.name = 'ModelAbortError'; }
+}
+/** snapshot → 池键 (只用**只读**字段; 与 provider/model/端点相关, 与调用内容无关) */
+export function modelPoolKey(s) {
+    return `${s.provider}::${s.model}::${s.baseUrl ?? ''}`;
+}
+export class ModelRuntime {
+    ports;
+    defaultTimeoutMs;
+    maxConcurrency;
+    pool = new Map();
+    stats = { reused: 0, opened: 0, timeouts: 0, aborts: 0, concurrencyWaits: 0, maxObservedConcurrency: 0, rateLimited: 0, retries: 0, lastBackoffMs: 0, circuitOpened: 0, failFast: 0, capabilityRejects: 0, halfOpenProbes: 0, breakerClosed: 0, fallbacks: 0, usageRecorded: 0, usageDropped: 0 };
+    /** 逐 key 熔断状态 */
+    breakers = new Map();
+    /** 每 key 当前在飞的调用数 + 等待队列 (多供应商并发: 各 key 各自算) */
+    active = new Map();
+    /** 等待者 → 它的 granted 标记 (转让路径用; 见 acquireSlot) */
+    grantedProbe = new WeakMap();
+    waiters = new Map();
+    constructor(ports, defaultTimeoutMs = 30_000, 
+    /** 每个 key 的最大并发 (多供应商并发: 逐 key 计数, 互不阻塞) */
+    maxConcurrency = 4) {
+        this.ports = ports;
+        this.defaultTimeoutMs = defaultTimeoutMs;
+        this.maxConcurrency = maxConcurrency;
+        if (typeof ports?.openConnection !== 'function')
+            throw new Error('ModelRuntime 需要 openConnection 端口');
+    }
+    /** **只读入口**: 取一个租约 (可能需要先开连接; 同一 pool key 复用) */
+    async acquire(snapshot, opts) {
+        if (!snapshot?.provider || !snapshot?.model)
+            throw new Error('acquire 需要 provider + model (缺了不许猜)');
+        // **只读**: 只读这些字段, 一个都不写回 (snapshot 常被上层冻结; 写它会当场抛)
+        const frozen = snapshot;
+        // ① 能力检查 (**拒在开连接之前** ⇒ 不浪费一次连接; 只读 snapshot.capabilities, 不改任何东西)
+        const need = opts?.require ?? [];
+        if (need.length > 0) {
+            if (!frozen.capabilities) {
+                this.stats.capabilityRejects += 1;
+                throw new ModelCapabilityError(need, true);
+            }
+            const have = new Set(frozen.capabilities);
+            const missing = need.filter((c) => !have.has(c));
+            if (missing.length > 0) {
+                this.stats.capabilityRejects += 1;
+                throw new ModelCapabilityError(missing);
+            }
+        }
+        const key = modelPoolKey(frozen);
+        const { conn } = await this.ensureConnection(frozen);
+        const snapshotReadonly = frozen;
+        let released = false;
+        const self = this;
+        return {
+            snapshot: snapshotReadonly,
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                const cur = self.pool.get(key);
+                if (cur)
+                    cur.leases = Math.max(0, cur.leases - 1);
+            },
+            call: async (req, opts) => {
+                if (released)
+                    return { ok: false, error: '租约已归还' };
+                const budget = snapshotReadonly.timeoutMs ?? this.defaultTimeoutMs;
+                const external = opts?.signal;
+                if (external?.aborted) {
+                    self.stats.aborts += 1;
+                    throw new ModelAbortError();
+                }
+                const started = (self.ports.now ?? Date.now)();
+                // **候选清单 = 主 provider + 备用 (来自 snapshot, 只读)** —— 运行时绝不改全局配置
+                const candidates = [snapshotReadonly];
+                for (const p of snapshotReadonly.fallbackProviders ?? []) {
+                    if (p && p !== snapshotReadonly.provider)
+                        candidates.push({ ...snapshotReadonly, provider: p });
+                }
+                let last = { ok: false, error: '没有可用的 provider' };
+                let totalAttempts = 0;
+                for (let ci = 0; ci < candidates.length; ci += 1) {
+                    const snapI = candidates[ci];
+                    const keyI = modelPoolKey(snapI);
+                    const isFallback = ci > 0;
+                    if (isFallback)
+                        self.stats.fallbacks += 1;
+                    try {
+                        const gate = self.breakerGate(keyI);
+                        if (gate) {
+                            self.stats.failFast += 1;
+                            // 熔断开路: **有下一个候选才回退**; 否则保持"抛出"的契约 (调用方能按类型区分快速失败)
+                            if (ci + 1 < candidates.length) {
+                                last = { ok: false, provider: snapI.provider, fallback: isFallback, error: `熔断中 (冷却至 ${gate})` };
+                                continue;
+                            }
+                            throw new ModelCircuitOpenError(gate);
+                        }
+                        const connI = keyI === key ? conn : (await self.ensureConnection(snapI)).conn;
+                        await self.acquireSlot(keyI, external);
+                        try {
+                            for (let attempt = 0;; attempt += 1) {
+                                totalAttempts += 1;
+                                let result;
+                                try {
+                                    result = await self.callOnce(connI, req, external, budget);
+                                }
+                                catch (err) {
+                                    if (countsTowardBreaker(err))
+                                        self.onFailure(keyI);
+                                    else
+                                        self.onSuccess(keyI);
+                                    throw err; // 取消/超时: 取消要立刻冒出去 (不回退), 超时由外层 catch 处理
+                                }
+                                if (result.ok) {
+                                    self.onSuccess(keyI);
+                                    const ms = (self.ports.now ?? Date.now)() - started;
+                                    const out = { ...result, provider: snapI.provider, fallback: isFallback, reused: (self.pool.get(keyI)?.leases ?? 0) > 1, ms };
+                                    await self.recordUsage(snapI, { provider: snapI.provider, model: snapI.model, ms, attempts: totalAttempts, fallback: isFallback, usage: result.usage });
+                                    return out;
+                                }
+                                if (!isRateLimited(result)) {
+                                    if (countsTowardBreaker(result))
+                                        self.onFailure(keyI);
+                                    else
+                                        self.onSuccess(keyI);
+                                    last = { ...result, provider: snapI.provider, fallback: isFallback, reused: (self.pool.get(keyI)?.leases ?? 0) > 1, ms: (self.ports.now ?? Date.now)() - started };
+                                    break; // 非限流失败 ⇒ 交给下一个候选
+                                }
+                                self.stats.rateLimited += 1;
+                                if (attempt >= BACKOFF_POLICY.maxRetries) {
+                                    last = { ...result, provider: snapI.provider, fallback: isFallback, ms: (self.ports.now ?? Date.now)() - started, error: `限流重试用尽 (${attempt + 1} 次): ${String(result.error ?? '')}` };
+                                    break; // 限流用尽 ⇒ 也可回退 (容量问题不是 bug)
+                                }
+                                const wait = backoffDelayMs(attempt, { retryAfterMs: Number(result.retryAfterMs ?? 0) || undefined, random: self.ports.random });
+                                self.stats.retries += 1;
+                                self.stats.lastBackoffMs = wait;
+                                await self.sleepOrAbort(wait, external); // 退避期间取消 ⇒ 立刻抛
+                            }
+                        }
+                        finally {
+                            self.releaseSlot(keyI);
+                        }
+                    }
+                    catch (err) {
+                        if (err instanceof ModelAbortError)
+                            throw err; // 调用方取消 ⇒ 不回退, 直接冒出去
+                        if (err instanceof ModelTimeoutError) {
+                            // 超时: **有下一个候选才回退**; 最后一个候选的超时保持原有契约 (抛出, 调用方才能区分"超时"与"软失败")
+                            if (ci + 1 < candidates.length) {
+                                last = { ok: false, provider: snapI.provider, fallback: isFallback, error: err.message };
+                                continue;
+                            }
+                            throw err;
+                        }
+                        throw err;
+                    }
+                }
+                const tried = candidates.map((c) => c.provider).join(' → ');
+                last = { ...last, ms: (self.ports.now ?? Date.now)() - started, error: `全部候选失败 (${tried}): ${String(last.error ?? '')}` };
+                await self.recordUsage(candidates[candidates.length - 1], { provider: last.provider ?? '', model: candidates[candidates.length - 1].model, ms: last.ms ?? 0, attempts: totalAttempts, fallback: candidates.length > 1, usage: undefined });
+                return last;
+            },
+        };
+    }
+    /** 连接池: 同一 pool key 复用; 开不起来不留脏槽 */
+    async ensureConnection(snapshot) {
+        const key = modelPoolKey(snapshot);
+        let slot = this.pool.get(key);
+        if (slot)
+            this.stats.reused += 1;
+        if (!slot) {
+            const controller = new AbortController(); // 连接级取消 (租约级用各自的 signal)
+            const opening = this.ports.openConnection(snapshot, controller.signal);
+            this.stats.opened += 1;
+            slot = { conn: undefined, opening, leases: 0 };
+            this.pool.set(key, slot);
+            try {
+                slot.conn = await opening;
+            }
+            catch (err) {
+                this.pool.delete(key); // 开不起来就不留脏槽 (否则后续全被判"复用")
+                throw err;
+            }
+        }
+        else if (!slot.conn) {
+            slot.conn = await slot.opening;
+        }
+        return { conn: slot.conn, key };
+    }
+    /** usage 记录: 端口抛错**不许**影响调用结果 (只记 usageDropped) */
+    async recordUsage(snapshot, entry) {
+        if (typeof this.ports.recordUsage !== 'function')
+            return;
+        try {
+            await this.ports.recordUsage(entry);
+            this.stats.usageRecorded += 1;
+        }
+        catch {
+            this.stats.usageDropped += 1;
+        }
+    }
+    /** 一次尝试 (超时与取消都走受控 controller; 底层只认一个 signal) */
+    async callOnce(conn, req, external, budget) {
+        const ctl = new AbortController();
+        const onExternalAbort = () => ctl.abort();
+        external?.addEventListener?.('abort', onExternalAbort, { once: true });
+        let timer;
+        const timeoutPromise = new Promise((_, reject) => {
+            timer = setTimeout(() => { this.stats.timeouts += 1; ctl.abort(); reject(new ModelTimeoutError(budget)); }, budget);
+        });
+        try {
+            const res = await Promise.race([conn.call(req, ctl.signal), timeoutPromise]);
+            return (res ?? { ok: true });
+        }
+        catch (err) {
+            if (err instanceof ModelTimeoutError)
+                throw err;
+            if (ctl.signal.aborted) {
+                this.stats.aborts += 1;
+                throw new ModelAbortError();
+            }
+            throw err;
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            external?.removeEventListener?.('abort', onExternalAbort);
+        }
+    }
+    /** 退避睡眠 (可取消; 不真等领域: 端口注入 sleep) */
+    async sleepOrAbort(ms, signal) {
+        if (signal?.aborted) {
+            this.stats.aborts += 1;
+            throw new ModelAbortError();
+        }
+        const sleep = this.ports.sleep ?? ((d) => new Promise((r) => setTimeout(r, d)));
+        let onAbort;
+        const aborted = new Promise((_, reject) => {
+            if (!signal)
+                return;
+            onAbort = () => { this.stats.aborts += 1; reject(new ModelAbortError()); };
+            signal.addEventListener('abort', onAbort, { once: true });
+        });
+        try {
+            await Promise.race([sleep(ms, signal), aborted]);
+        }
+        finally {
+            if (onAbort)
+                signal?.removeEventListener?.('abort', onAbort);
+        }
+    }
+    /** 熔断门: 开路且未到冷却 ⇒ 返回"何时可再试" (调用方快速失败); 冷却已过 ⇒ 转半开并放行探测 */
+    breakerGate(key) {
+        const b = this.breakers.get(key);
+        if (!b || b.state === 'closed')
+            return null;
+        const nowMs = (this.ports.now ?? Date.now)();
+        if (b.state === 'open' && nowMs >= b.openUntil) {
+            b.state = 'half-open';
+            b.probes = 0;
+        }
+        if (b.state === 'open')
+            return b.openUntil;
+        if (b.probes >= BREAKER_POLICY.halfOpenProbes)
+            return b.openUntil; // 半开探测名额用完 ⇒ 仍然快速失败
+        b.probes += 1;
+        this.stats.halfOpenProbes += 1;
+        return null;
+    }
+    /** 成功: 半开 ⇒ 闭合 (清零); 闭合态失败计数清零 */
+    onSuccess(key) {
+        const b = this.breakers.get(key);
+        if (!b)
+            return;
+        if (b.state === 'half-open') {
+            b.state = 'closed';
+            b.failures = 0;
+            b.probes = 0;
+            this.stats.breakerClosed += 1;
+            return;
+        }
+        b.failures = 0;
+    }
+    /** 失败: 累计; 达阈值 ⇒ 开路; 半开里失败 ⇒ 立刻重新开路 (冷却重新计时) */
+    onFailure(key) {
+        const b = this.breakers.get(key) ?? { failures: 0, state: 'closed', openUntil: 0, probes: 0 };
+        b.failures += 1;
+        const halfOpenFail = b.state === 'half-open';
+        if (halfOpenFail || b.failures >= BREAKER_POLICY.failureThreshold) {
+            b.state = 'open';
+            b.openUntil = (this.ports.now ?? Date.now)() + BREAKER_POLICY.cooldownMs;
+            b.probes = 0;
+            this.stats.circuitOpened += 1;
+        }
+        this.breakers.set(key, b);
+    }
+    /** 只读: 逐 key 熔断状态 (诊断/测试) */
+    breakerStates() {
+        const out = {};
+        for (const [k, v] of this.breakers)
+            out[k] = { failures: v.failures, state: v.state, openUntil: v.openUntil };
+        return out;
+    }
+    /** 取并发槽 (逐 key; 排队可取消) */
+    async acquireSlot(key, signal) {
+        const cur = this.active.get(key) ?? 0;
+        if (cur < this.maxConcurrency) {
+            this.active.set(key, cur + 1);
+            this.stats.maxObservedConcurrency = Math.max(this.stats.maxObservedConcurrency, cur + 1);
+            return;
+        }
+        if (signal?.aborted) {
+            this.stats.aborts += 1;
+            throw new ModelAbortError();
+        }
+        this.stats.concurrencyWaits += 1;
+        const granted = { value: false };
+        await new Promise((resolve, reject) => {
+            const list = this.waiters.get(key) ?? [];
+            const entry = { resolve, reject, signal };
+            const onAbort = () => {
+                const i = list.indexOf(entry);
+                if (i >= 0)
+                    list.splice(i, 1);
+                this.stats.aborts += 1;
+                reject(new ModelAbortError());
+            };
+            if (signal)
+                signal.addEventListener('abort', onAbort, { once: true });
+            list.push(entry);
+            this.waiters.set(key, list);
+            const wrappedResolve = () => { if (signal)
+                signal.removeEventListener('abort', onAbort); resolve(); };
+            entry.resolve = wrappedResolve;
+            // 槽是**转让**来的 (releaseSlot 直接 resolve 并置 granted) ⇒ 不再自增, 否则并发账虚高 (实测踩到)
+            this.grantedProbe.set(entry, granted);
+        });
+        if (!granted.value) {
+            this.active.set(key, (this.active.get(key) ?? 0) + 1);
+            this.stats.maxObservedConcurrency = Math.max(this.stats.maxObservedConcurrency, this.active.get(key));
+        }
+    }
+    /** 还槽: 有排队者就交给它 (不释放额度, 直接转让) */
+    releaseSlot(key) {
+        const list = this.waiters.get(key) ?? [];
+        const next = list.shift();
+        if (next) {
+            if (!this.waiters.get(key)?.length)
+                this.waiters.delete(key);
+            const probe = this.grantedProbe.get(next);
+            if (probe)
+                probe.value = true;
+            next.resolve();
+            return;
+        }
+        const cur = this.active.get(key) ?? 0;
+        if (cur <= 1)
+            this.active.delete(key);
+        else
+            this.active.set(key, cur - 1);
+    }
+    /** 只读统计 (诊断/门用) */
+    snapshotStats() {
+        return { connections: this.pool.size, defaultTimeoutMs: this.defaultTimeoutMs, ...this.stats };
+    }
+    /** 关闭全部连接 (进程收尾用) */
+    async closeAll() {
+        const all = [...this.pool.values()];
+        this.pool.clear();
+        await Promise.all(all.map(async (s) => {
+            try {
+                const c = s.conn ?? (await s.opening);
+                await c.close();
+            }
+            catch { /* 关不掉的连接不阻塞收尾 */ }
+        }));
+    }
+}