@magic6/dsh-llm-resilience 0.0.0-stage → 0.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/adapter.js ADDED
@@ -0,0 +1,1055 @@
1
+ /**
2
+ * dsh-llm-resilience 的 provider 适配器。
3
+ *
4
+ * 对外它是一条普通 provider route(默认 `fallback`):宿主照常 resolve 模型、
5
+ * 组装请求、消费 chunk。对内它按 `targets` 顺序逐条尝试上游 provider,每个
6
+ * target 有独立的重试预算和退避曲线,失败后从下一个 target 的第一次重试重新
7
+ * 起算,不继承上一条已经翻倍过的延迟。
8
+ *
9
+ * 三条硬约束:
10
+ *
11
+ * 1. **内容一旦交付就不能换 target**。文本/推理增量会立刻转发给宿主;只有
12
+ * tool-call 的 block-start/delta 会缓冲到该 block 的 `block-end`。因此:
13
+ * - 文本已交付后失败:抛错,交给宿主的整步重试(它能丢弃半截消息);
14
+ * - 只有未完成的 tool-call 被缓冲:丢弃缓冲、安全重试(宿主什么都没看见)。
15
+ * 2. **熔断按 provider+model 记账**。连续失败达到阈值后锁 `lockMs`;锁到期后
16
+ * 先发一个极小的探活请求,探活成功才真正使用该 target,失败则再锁一轮。
17
+ * 3. **外层重试只保留整步重放需要的 code**。链自身的预算由本适配器执行;
18
+ * 只有「内容已交付后失败」才回落到 dsh-llm-retry 的整步重放,避免耗尽整条链
19
+ * 之后又被外层重放一遍。
20
+ *
21
+ * @module dsh-llm-resilience/adapter
22
+ */
23
+
24
+ import { homedir } from 'node:os';
25
+ import { join } from 'node:path';
26
+
27
+ import { LlmAdapter, LlmError, resolveRetryPolicy } from '@deepseek-ai/dsh-llm';
28
+
29
+ import { resolvePluginConfig } from './config.js';
30
+ import {
31
+ ACTIONS,
32
+ AttemptBudget,
33
+ BREAKER_STATES,
34
+ CircuitBreaker,
35
+ buildRetrySchedule,
36
+ classifyFailure,
37
+ enabledTargets,
38
+ planAttempts,
39
+ runtimeSnapshot,
40
+ targetLabel,
41
+ usableAttempts,
42
+ validateChain,
43
+ } from './policy.js';
44
+ import { readStateFileSync, writeStateFileMerged } from './state-file.js';
45
+
46
+ const ENVELOPE_KIND = 'dsh-llm-resilience';
47
+ /** Replay envelopes written before the 0.5.0 rename remain readable. */
48
+ const LEGACY_ENVELOPE_KINDS = new Set(['dsh-llm-fallback']);
49
+ const ENVELOPE_VERSION = 1;
50
+ const AUTO_MODEL = 'auto';
51
+ /** cosmokit 的共享 volatile 写协议;设置页 describe 读取的就是这个活单元格。 */
52
+ const VOLATILE_WRITE = Symbol.for('cosmokit.volatile.write');
53
+ const RUNTIME_PUBLISH_MS = 5000;
54
+ const FLUSH_RETRY_MS = 1000;
55
+
56
+ /** 合成 route 自己的外层策略:只让「已交付内容后失败」走宿主的整步重放。 */
57
+ const OUTER_RETRY_POLICY = resolveRetryPolicy(
58
+ {
59
+ mode: 'normal',
60
+ maxRetries: 3,
61
+ // 不含 FALLBACK_EXHAUSTED / ALL_TARGETS_LOCKED / NO_TARGETS:
62
+ // 链已经尝试完的错误再重放整条链只会放大延迟。
63
+ retryableCodes: [
64
+ 'EMPTY_RESPONSE',
65
+ 'MALFORMED_RESPONSE',
66
+ 'PI_AI_ERROR',
67
+ 'RATE_LIMIT',
68
+ 'SERVER',
69
+ 'STREAM_CLOSED',
70
+ 'TIMEOUT',
71
+ 'TRANSPORT',
72
+ 'UNKNOWN',
73
+ ],
74
+ backoff: { initialDelayMs: 500, maxDelayMs: 5000, jitterRatio: 0.2 },
75
+ },
76
+ 'llm-fallback.retryPolicy',
77
+ );
78
+
79
+ function isAborted(signal) {
80
+ return signal?.aborted === true;
81
+ }
82
+
83
+ /** 把任意抛出值收敛成 LlmFailure 形状;调用方被取消时统一成 ABORTED。 */
84
+ function normalizeThrown(error, signal) {
85
+ if (isAborted(signal)) return { message: 'request aborted', code: 'ABORTED' };
86
+ if (error !== null && typeof error === 'object') {
87
+ const carried = error.failure;
88
+ if (
89
+ carried !== null &&
90
+ typeof carried === 'object' &&
91
+ typeof carried.message === 'string' &&
92
+ carried.message.length > 0 &&
93
+ typeof carried.code === 'string' &&
94
+ carried.code.length > 0
95
+ ) {
96
+ return carried;
97
+ }
98
+ if (typeof error.code === 'string' && error.code.length > 0) {
99
+ return {
100
+ message: typeof error.message === 'string' && error.message.length > 0 ? error.message : 'LLM adapter failed',
101
+ code: error.code,
102
+ ...(Number.isInteger(error.status) && error.status >= 100 && error.status <= 599 ? { status: error.status } : {}),
103
+ ...(Number.isSafeInteger(error.offloadImages) && error.offloadImages > 0
104
+ ? { offloadImages: error.offloadImages }
105
+ : {}),
106
+ };
107
+ }
108
+ }
109
+ const message = error instanceof Error && error.message ? error.message : String(error ?? 'LLM adapter failed');
110
+ return { message, code: 'UNKNOWN' };
111
+ }
112
+
113
+ function failureError(failure, message) {
114
+ return new LlmError(message ?? failure.message, failure.code || 'UNKNOWN', {
115
+ ...(Number.isInteger(failure.status) && failure.status >= 100 && failure.status <= 599
116
+ ? { status: failure.status }
117
+ : {}),
118
+ ...(typeof failure.requestId === 'string' && failure.requestId.length > 0
119
+ ? { requestId: failure.requestId }
120
+ : {}),
121
+ ...(Number.isFinite(failure.providerRetryAfterMs) && failure.providerRetryAfterMs > 0
122
+ ? { providerRetryAfterMs: failure.providerRetryAfterMs }
123
+ : {}),
124
+ // 宿主的 image-offload 恢复依赖这个字段;链路层只负责原样带出去。
125
+ ...(Number.isSafeInteger(failure.offloadImages) && failure.offloadImages > 0
126
+ ? { offloadImages: failure.offloadImages }
127
+ : {}),
128
+ });
129
+ }
130
+
131
+ function abortedFinish(signal) {
132
+ const reason = signal?.reason;
133
+ const message = reason instanceof Error && reason.message ? reason.message : 'request aborted';
134
+ return {
135
+ type: 'finish',
136
+ reason: { kind: 'aborted', failure: { message, code: 'ABORTED' } },
137
+ };
138
+ }
139
+
140
+ /** 可被调用方取消的等待;返回 false 表示被取消。 */
141
+ function sleep(ms, signal) {
142
+ if (isAborted(signal)) return Promise.resolve(false);
143
+ return new Promise((resolve) => {
144
+ const timer = setTimeout(() => {
145
+ cleanup();
146
+ resolve(true);
147
+ }, ms);
148
+ function onAbort() {
149
+ clearTimeout(timer);
150
+ cleanup();
151
+ resolve(false);
152
+ }
153
+ function cleanup() {
154
+ signal?.removeEventListener?.('abort', onAbort);
155
+ }
156
+ signal?.addEventListener?.('abort', onAbort, { once: true });
157
+ });
158
+ }
159
+
160
+ /** 合成 route 的 replay 信封:记住是哪个 target 产出的、内部信封原样保留。 */
161
+ function wrapFinish(finish, target) {
162
+ const inner = finish.replayState;
163
+ if (inner === undefined || inner.response === undefined) return finish;
164
+ return {
165
+ ...finish,
166
+ replayState: {
167
+ response: {
168
+ kind: ENVELOPE_KIND,
169
+ version: ENVELOPE_VERSION,
170
+ provider: target.provider,
171
+ model: target.model,
172
+ inner: inner.response,
173
+ },
174
+ ...(inner.blocks === undefined ? {} : { blocks: inner.blocks }),
175
+ },
176
+ };
177
+ }
178
+
179
+ function isEnvelope(value) {
180
+ return (
181
+ value !== null &&
182
+ typeof value === 'object' &&
183
+ value.response !== null &&
184
+ typeof value.response === 'object' &&
185
+ (ENVELOPE_KIND === value.response.kind || LEGACY_ENVELOPE_KINDS.has(value.response.kind)) &&
186
+ value.response.version === ENVELOPE_VERSION &&
187
+ typeof value.response.provider === 'string' &&
188
+ typeof value.response.model === 'string'
189
+ );
190
+ }
191
+
192
+ /**
193
+ * 把历史里由合成 route 产出的 assistant 消息还原成真实 target 的 replay 状态。
194
+ *
195
+ * 不还原的话,上游适配器看到的是 `provider: fallback` + 一个它不认识的
196
+ * replay 信封;pi-ai 会降级成 provider-neutral 历史(能跑,但丢掉签名/id)。
197
+ * 还原后与「不用 fallback 直接调该 target」的历史完全一致。
198
+ */
199
+ function unwrapMessages(messages, route) {
200
+ let changed = false;
201
+ const mapped = messages.map((message) => {
202
+ if (message.role !== 'assistant') return message;
203
+ const source = message.source;
204
+ if (source === null || typeof source !== 'object' || source.kind !== 'model' || source.provider !== route) {
205
+ return message;
206
+ }
207
+ const envelope = source.replayState;
208
+ if (!isEnvelope(envelope)) return message;
209
+ changed = true;
210
+ const { response } = envelope;
211
+ return {
212
+ ...message,
213
+ source: {
214
+ kind: 'model',
215
+ provider: response.provider,
216
+ model: response.model,
217
+ replayState: {
218
+ response: response.inner,
219
+ ...(envelope.blocks === undefined ? {} : { blocks: envelope.blocks }),
220
+ },
221
+ },
222
+ };
223
+ });
224
+ return changed ? mapped : messages;
225
+ }
226
+
227
+ /**
228
+ * 一次 step 重放的请求指纹。
229
+ *
230
+ * 内容已交付后失败时,宿主会重放整个 step;请求的 messages 与失败时相同。
231
+ * 用最后一条 user/tool 消息的 role + id 识别重放(system/developer 消息可能
232
+ * 在重放时被重新注入,不能作为锚点)。没有 id 的手工请求退回用条数。
233
+ */
234
+ function requestFingerprint(options) {
235
+ const messages = options.messages ?? [];
236
+ let pivot;
237
+ for (let index = messages.length - 1; index >= 0; index -= 1) {
238
+ const message = messages[index];
239
+ if (message?.role === 'user' || message?.role === 'tool') {
240
+ pivot = message;
241
+ break;
242
+ }
243
+ }
244
+ pivot ??= messages[messages.length - 1];
245
+ const role = pivot?.role ?? '';
246
+ const id = typeof pivot?.id === 'string' ? pivot.id : '';
247
+ return id.length > 0 ? `${role}\u0000${id}` : `${role}\u0000${messages.length}`;
248
+ }
249
+
250
+ function labelsOf(targets) {
251
+ return targets.map((target) => targetLabel(target)).join(' → ');
252
+ }
253
+
254
+ /** 展开 `$DSH_HOME`;dsh 默认 home 与 `dsh-home-paths` 的默认值一致。 */
255
+ function expandStateFile(value) {
256
+ if (typeof value !== 'string' || value.length === 0) return undefined;
257
+ const home =
258
+ typeof process.env.DSH_HOME === 'string' && process.env.DSH_HOME.length > 0
259
+ ? process.env.DSH_HOME
260
+ : join(homedir(), '.dsh');
261
+ return value.replace(/\$\{?DSH_HOME\}?/g, home);
262
+ }
263
+
264
+ function aggregateModelInfo(provider, model, entries, route) {
265
+ const resolved = entries.filter((entry) => entry.info !== undefined).map((entry) => entry.info);
266
+ const capabilities = {};
267
+
268
+ if (resolved.length > 0) {
269
+ const windows = resolved.map((info) => info.context?.contextWindow).filter((value) => Number.isFinite(value));
270
+ if (windows.length > 0) capabilities.context = { contextWindow: Math.min(...windows) };
271
+
272
+ const defaults = resolved.map((info) => info.defaultMaxTokens).filter((value) => Number.isSafeInteger(value));
273
+ if (defaults.length > 0) capabilities.defaultMaxTokens = Math.min(...defaults);
274
+
275
+ if (resolved.every((info) => Array.isArray(info.inputModalities))) {
276
+ const common = resolved[0].inputModalities.filter((modality) =>
277
+ resolved.every((info) => info.inputModalities.includes(modality)),
278
+ );
279
+ if (common.length > 0) capabilities.inputModalities = common;
280
+ } else if (
281
+ resolved.some((info) => Array.isArray(info.inputModalities) && !info.inputModalities.includes('image'))
282
+ ) {
283
+ // 有 target 明确只收文本、其余 target 能力未知:按最保守的文本处理,
284
+ // 免得把图片发给一个可能拒绝它的上游。
285
+ capabilities.inputModalities = ['text'];
286
+ }
287
+
288
+ const reasoning = resolved.every((info) => info.reasoning !== undefined)
289
+ ? commonReasoning(resolved.map((info) => info.reasoning))
290
+ : undefined;
291
+ if (reasoning !== undefined) capabilities.reasoning = reasoning;
292
+
293
+ const systemPromptUpdate = commonValue(resolved.map((info) => info.systemPromptUpdate));
294
+ if (systemPromptUpdate !== undefined) capabilities.systemPromptUpdate = systemPromptUpdate;
295
+
296
+ const toolUpdate = commonValue(resolved.map((info) => info.toolUpdate));
297
+ if (toolUpdate !== undefined) capabilities.toolUpdate = toolUpdate;
298
+ }
299
+
300
+ const all = entries.map((entry) => entry.target);
301
+ return {
302
+ provider,
303
+ id: model,
304
+ name: all.length > 0 ? `Fallback chain (${all.length})` : 'Fallback chain',
305
+ description: all.length > 0 ? `${route}: ${labelsOf(all)}` : `${route}: no targets configured`,
306
+ ...capabilities,
307
+ };
308
+ }
309
+
310
+ /** 所有 target 都声明了同样的值时才算数;否则返回 undefined。 */
311
+ function commonValue(values) {
312
+ if (values.length === 0) return undefined;
313
+ const [first] = values;
314
+ if (first === undefined) return undefined;
315
+ return values.every((value) => value === first) ? first : undefined;
316
+ }
317
+
318
+ function commonReasoning(infos) {
319
+ const [first] = infos;
320
+ if (first === undefined || first.efforts.length === 0) return undefined;
321
+ const common = first.efforts.filter((effort) =>
322
+ infos.every((info) => info.efforts.some((candidate) => candidate.id === effort.id)),
323
+ );
324
+ if (common.length === 0) return undefined;
325
+ const defaults = infos.map((info) => info.defaultEffort);
326
+ const defaultEffort =
327
+ defaults.every((value) => value !== undefined && value === defaults[0]) &&
328
+ common.some((effort) => effort.id === defaults[0])
329
+ ? defaults[0]
330
+ : undefined;
331
+ return { efforts: common, ...(defaultEffort === undefined ? {} : { defaultEffort }) };
332
+ }
333
+
334
+ /** 把缓冲的 tool-call chunk 按 block 索引暂存,`block-end` 到达时才交付。 */
335
+ function bufferChunk(buffers, chunk) {
336
+ const current = buffers.get(chunk.index);
337
+ if (current === undefined) buffers.set(chunk.index, [chunk]);
338
+ else current.push(chunk);
339
+ }
340
+
341
+ export class FallbackAdapter extends LlmAdapter {
342
+ /**
343
+ * @param options.route - 注册到宿主上的合成 route(apply 时固定,改 route 需重启)。
344
+ * @param options.config - 组合层原始配置;每次调用重新解析,以获得设置页的实时值。
345
+ * @param options.llm - 宿主 llm 服务,用于 resolveModelInfo 和嵌套 stream。
346
+ * @param options.logger - cordis logger。
347
+ * @param options.now - 时钟,测试可注入。
348
+ * @param options.random - 抖动随机源,测试可注入。
349
+ * @param options.sleep - 等待实现,测试可注入。
350
+ * @param options.runtimeRef - 配置里的 `runtime` 活单元格;宿主用它把运行状态推给设置页。
351
+ * @param options.recordSession - `(sessionId, event) => void`;写会话日志,失败自吞。
352
+ */
353
+ constructor({
354
+ route,
355
+ config,
356
+ llm,
357
+ logger,
358
+ now = Date.now,
359
+ random = Math.random,
360
+ sleep: sleepFn = sleep,
361
+ runtimeRef,
362
+ recordSession = () => {},
363
+ }) {
364
+ super();
365
+ this.route = route;
366
+ this.configSource = config;
367
+ this.llm = llm;
368
+ this.logger = logger;
369
+ this.now = now;
370
+ this.random = random;
371
+ this.sleep = sleepFn;
372
+ this.runtimeRef = runtimeRef;
373
+ this.recordSession = recordSession;
374
+ this.breaker = undefined;
375
+ this.stateFile = undefined;
376
+ this.persistTimer = undefined;
377
+ this.flushRetryTimer = undefined;
378
+ this.flushChain = Promise.resolve();
379
+ this.runtimeTimer = undefined;
380
+ this.backgroundProbes = new Map();
381
+ this.probeControllers = new Set();
382
+ this.disposed = false;
383
+ this.hints = new Map();
384
+ }
385
+
386
+ resolveConfig() {
387
+ return resolvePluginConfig(this.configSource);
388
+ }
389
+
390
+ providerInfo(provider) {
391
+ return { id: provider, name: 'Fallback chain' };
392
+ }
393
+
394
+ providerRetryPolicy() {
395
+ return OUTER_RETRY_POLICY;
396
+ }
397
+
398
+ ensureBreaker(breakerConfig) {
399
+ const failureThreshold = breakerConfig.failureThreshold;
400
+ const lockMs = breakerConfig.lockMs;
401
+ const stateFile = expandStateFile(breakerConfig.stateFile);
402
+ if (
403
+ this.breaker === undefined ||
404
+ this.breaker.failureThreshold !== failureThreshold ||
405
+ this.breaker.lockMs !== lockMs ||
406
+ stateFile !== this.stateFile
407
+ ) {
408
+ const snapshot =
409
+ stateFile !== this.stateFile
410
+ ? readStateFileSync(stateFile, this.logger)
411
+ : this.breaker?.snapshot();
412
+ this.stateFile = stateFile;
413
+ this.breaker = CircuitBreaker.fromSnapshot(snapshot, {
414
+ failureThreshold,
415
+ lockMs,
416
+ now: this.now,
417
+ });
418
+ }
419
+ this.#ensureRuntimeTimer();
420
+ this.#publishRuntime();
421
+ return this.breaker;
422
+ }
423
+
424
+ #ensureRuntimeTimer() {
425
+ if (this.runtimeTimer !== undefined || this.runtimeRef === undefined || this.disposed) return;
426
+ this.runtimeTimer = setInterval(() => this.#publishRuntime(), RUNTIME_PUBLISH_MS);
427
+ this.runtimeTimer.unref?.();
428
+ }
429
+
430
+ /** 把当前熔断状态写进配置的 volatile 单元格;设置页 describe 会读到它。 */
431
+ #publishRuntime() {
432
+ const ref = this.runtimeRef;
433
+ if (ref === null || typeof ref !== 'object' || typeof ref[VOLATILE_WRITE] !== 'function') return;
434
+ if (this.breaker === undefined) return;
435
+ const config = this.resolveConfig();
436
+ try {
437
+ ref[VOLATILE_WRITE](runtimeSnapshot(enabledTargets(config.targets), this.breaker, this.now()));
438
+ } catch (error) {
439
+ this.logger?.warn?.(
440
+ `llm-resilience: cannot publish runtime state: ${
441
+ error instanceof Error ? error.message : String(error)
442
+ }`,
443
+ );
444
+ }
445
+ }
446
+
447
+ /** 合并短时间内的多次熔断变化,避免每次失败都同步落盘。 */
448
+ persist() {
449
+ this.#publishRuntime();
450
+ if (
451
+ this.stateFile === undefined ||
452
+ this.breaker === undefined ||
453
+ this.persistTimer !== undefined ||
454
+ this.disposed
455
+ ) {
456
+ return;
457
+ }
458
+ this.persistTimer = setTimeout(() => {
459
+ this.persistTimer = undefined;
460
+ void this.flushState();
461
+ }, 200);
462
+ this.persistTimer.unref?.();
463
+ }
464
+
465
+ /**
466
+ * 持锁读-合并-写;拿不到锁时 1s 后重试。
467
+ *
468
+ * @returns 本次写入链的 promise,测试与 dispose 可以等待。
469
+ */
470
+ flushState() {
471
+ if (this.stateFile === undefined || this.breaker === undefined) return Promise.resolve();
472
+ const path = this.stateFile;
473
+ this.flushChain = this.flushChain
474
+ .then(async () => {
475
+ const merged = await writeStateFileMerged(path, this.breaker.snapshot(), {
476
+ logger: this.logger,
477
+ now: this.now,
478
+ });
479
+ if (merged === undefined) this.#scheduleFlushRetry();
480
+ })
481
+ .catch((error) => {
482
+ this.logger?.warn?.(
483
+ `llm-resilience: cannot persist breaker state ${path}: ${
484
+ error instanceof Error ? error.message : String(error)
485
+ }`,
486
+ );
487
+ this.#scheduleFlushRetry();
488
+ });
489
+ return this.flushChain;
490
+ }
491
+
492
+ #scheduleFlushRetry() {
493
+ if (this.disposed || this.flushRetryTimer !== undefined) return;
494
+ this.flushRetryTimer = setTimeout(() => {
495
+ this.flushRetryTimer = undefined;
496
+ void this.flushState();
497
+ }, FLUSH_RETRY_MS);
498
+ this.flushRetryTimer.unref?.();
499
+ }
500
+
501
+ dispose() {
502
+ if (this.persistTimer !== undefined) {
503
+ clearTimeout(this.persistTimer);
504
+ this.persistTimer = undefined;
505
+ }
506
+ if (this.flushRetryTimer !== undefined) {
507
+ clearTimeout(this.flushRetryTimer);
508
+ this.flushRetryTimer = undefined;
509
+ }
510
+ if (this.runtimeTimer !== undefined) {
511
+ clearInterval(this.runtimeTimer);
512
+ this.runtimeTimer = undefined;
513
+ }
514
+ for (const controller of this.probeControllers) {
515
+ controller.abort(new Error('llm-fallback disposed'));
516
+ }
517
+ this.probeControllers.clear();
518
+ const finalFlush = this.flushState();
519
+ this.disposed = true;
520
+ return finalFlush;
521
+ }
522
+
523
+ async listModels(provider) {
524
+ const config = this.resolveConfig();
525
+ const targets = enabledTargets(config.targets);
526
+ if (!config.enabled || targets.length === 0) return [];
527
+ return [
528
+ {
529
+ provider,
530
+ id: AUTO_MODEL,
531
+ name: 'Fallback chain',
532
+ description: labelsOf(targets),
533
+ },
534
+ ];
535
+ }
536
+
537
+ async resolveModel(provider, model, signal) {
538
+ const config = this.resolveConfig();
539
+ if (!config.enabled) throw new LlmError('llm-resilience: plugin is disabled', 'DISABLED');
540
+ const errors = validateChain(this.route, config.targets);
541
+ if (errors.length > 0) {
542
+ throw new LlmError(`llm-resilience: invalid configuration: ${errors.join('; ')}`, 'INVALID_CONFIG');
543
+ }
544
+ const targets = enabledTargets(config.targets);
545
+ if (targets.length === 0) {
546
+ throw new LlmError('llm-resilience: no targets configured', 'NO_TARGETS');
547
+ }
548
+
549
+ const entries = await Promise.all(
550
+ targets.map(async (target) => {
551
+ try {
552
+ const info = await this.llm.resolveModelInfo(target.provider, target.model, signal);
553
+ return { target, info };
554
+ } catch (error) {
555
+ if (isAborted(signal)) throw error;
556
+ this.logger?.warn?.(
557
+ `llm-resilience: cannot resolve target ${targetLabel(target)}: ${
558
+ error instanceof Error ? error.message : String(error)
559
+ }`,
560
+ );
561
+ return { target, info: undefined };
562
+ }
563
+ }),
564
+ );
565
+
566
+ return aggregateModelInfo(provider, model, entries, this.route);
567
+ }
568
+
569
+ async #runProbe(target, probe, signal) {
570
+ if (isAborted(signal)) return { aborted: true };
571
+ const controller = new AbortController();
572
+ const timer = setTimeout(() => controller.abort(new Error('probe timeout')), probe.timeoutMs);
573
+ const fusedSignal = signal === undefined ? controller.signal : AbortSignal.any([signal, controller.signal]);
574
+ let finish;
575
+ let failure;
576
+ try {
577
+ const stream = this.llm.stream({
578
+ provider: target.provider,
579
+ model: target.model,
580
+ messages: [{ role: 'user', content: [{ type: 'text', text: probe.prompt }] }],
581
+ maxTokens: probe.maxTokens,
582
+ signal: fusedSignal,
583
+ });
584
+ for await (const chunk of stream) {
585
+ if (chunk.type === 'finish') {
586
+ finish = chunk.reason;
587
+ break;
588
+ }
589
+ }
590
+ } catch (error) {
591
+ failure = normalizeThrown(error, signal);
592
+ } finally {
593
+ clearTimeout(timer);
594
+ }
595
+
596
+ if (isAborted(signal)) return { aborted: true };
597
+ if (failure !== undefined) return { ok: false, failure };
598
+ if (finish === undefined) {
599
+ return { ok: false, failure: { message: 'probe stream ended without a finish chunk', code: 'STREAM_CLOSED' } };
600
+ }
601
+ if (finish.kind === 'error' || finish.kind === 'aborted') {
602
+ return { ok: false, failure: finish.failure };
603
+ }
604
+ return { ok: true };
605
+ }
606
+
607
+ /**
608
+ * 后台探活:当前请求跳过这个 target,结果写回熔断器供下次请求使用。
609
+ * 同一 target 同时只跑一个探活;dispose 时 abort 未完成的探活。
610
+ */
611
+ #startBackgroundProbe({ target, key, label }, probe, options) {
612
+ if (this.backgroundProbes.has(key) || this.disposed) return;
613
+ const controller = new AbortController();
614
+ this.probeControllers.add(controller);
615
+ this.recordSession(options.sessionId, {
616
+ kind: 'probe',
617
+ target: label,
618
+ phase: 'start',
619
+ code: null,
620
+ lockedUntil: 0,
621
+ });
622
+ const task = (async () => {
623
+ const result = await this.#runProbe(target, probe, controller.signal);
624
+ if (this.disposed || result.aborted === true) return;
625
+ if (result.ok === true) {
626
+ this.breaker.probeSucceeded(key);
627
+ this.logger?.warn?.(`llm-resilience: background probe for ${label} succeeded; target is usable again`);
628
+ this.recordSession(options.sessionId, {
629
+ kind: 'probe',
630
+ target: label,
631
+ phase: 'success',
632
+ code: null,
633
+ lockedUntil: 0,
634
+ });
635
+ } else {
636
+ this.breaker.probeFailed(key);
637
+ const lockedUntil = this.breaker.snapshot().entries[key]?.lockedUntil ?? 0;
638
+ const code = result.failure?.code ?? 'UNKNOWN';
639
+ this.logger?.warn?.(
640
+ `llm-resilience: background probe for ${label} failed (${code}); target locked again`,
641
+ );
642
+ this.recordSession(options.sessionId, {
643
+ kind: 'probe',
644
+ target: label,
645
+ phase: 'failed',
646
+ code,
647
+ lockedUntil,
648
+ });
649
+ }
650
+ this.persist();
651
+ })()
652
+ .catch((error) => {
653
+ if (this.disposed) return;
654
+ this.breaker.probeFailed(key);
655
+ this.logger?.warn?.(
656
+ `llm-resilience: background probe for ${label} crashed: ${
657
+ error instanceof Error ? error.message : String(error)
658
+ }`,
659
+ );
660
+ this.persist();
661
+ })
662
+ .finally(() => {
663
+ this.backgroundProbes.delete(key);
664
+ this.probeControllers.delete(controller);
665
+ });
666
+ this.backgroundProbes.set(key, task);
667
+ }
668
+
669
+ /**
670
+ * 单个 target 的一次完整尝试(含它自己的重试预算)。
671
+ *
672
+ * @returns `{kind:'success'}` / `{kind:'failed', failure}` /
673
+ * `{kind:'fatal', failure}`(内容已交付,禁止换 target)/
674
+ * `{kind:'stop', failure}`(请求本身有问题,换 target 也没意义)/
675
+ * `{kind:'budget', reason, failure}`(全局时间/次数预算耗尽)/ `{kind:'aborted'}`。
676
+ */
677
+ async *attemptTarget({ target, key, label, options, messages, config, breaker, budget }) {
678
+ const schedule = buildRetrySchedule(target, { random: this.random });
679
+ let lastFailure;
680
+
681
+ for (let index = 0; index <= schedule.length; index += 1) {
682
+ const stop = budget.stopReason();
683
+ if (stop !== undefined) return { kind: 'budget', reason: stop, failure: lastFailure };
684
+
685
+ if (index > 0) {
686
+ const remaining = budget.remainingMs();
687
+ if (remaining <= 0) return { kind: 'budget', reason: 'deadline', failure: lastFailure };
688
+ const delayMs = Math.min(schedule[index - 1].delayMs, remaining);
689
+ const waited = await this.sleep(delayMs, options.signal);
690
+ if (!waited || isAborted(options.signal)) return { kind: 'aborted' };
691
+ const afterSleep = budget.stopReason();
692
+ if (afterSleep !== undefined) {
693
+ return { kind: 'budget', reason: afterSleep, failure: lastFailure };
694
+ }
695
+ }
696
+
697
+ budget.take();
698
+ const result = yield* this.attemptOnce({ target, options, messages });
699
+ if (result.kind === 'success') {
700
+ breaker.recordSuccess(key);
701
+ this.persist();
702
+ return result;
703
+ }
704
+ if (result.kind === 'aborted') return result;
705
+
706
+ lastFailure = result.failure;
707
+ const classification = classifyFailure(lastFailure, config.codeActions);
708
+ const action =
709
+ classification.action === ACTIONS.RETRY &&
710
+ lastFailure.code === 'MALFORMED_RESPONSE' &&
711
+ config.toolCalls.retryMalformed === false &&
712
+ classification.reason !== 'override'
713
+ ? ACTIONS.FALLBACK
714
+ : classification.action;
715
+
716
+ // 请求本身有问题:不记熔断、不换 target,直接把原始错误抛给宿主。
717
+ if (action === ACTIONS.FAIL) {
718
+ return { kind: 'stop', failure: lastFailure };
719
+ }
720
+
721
+ breaker.recordFailure(key);
722
+ this.persist();
723
+
724
+ // 内容已经交付:适配器层再试会重复内容;抛给宿主的整步重放。
725
+ if (result.delivered) return { kind: 'fatal', failure: lastFailure };
726
+
727
+ if (breaker.state(key) === BREAKER_STATES.OPEN) {
728
+ this.logger?.warn?.(`llm-resilience: ${label} opened the circuit breaker`);
729
+ this.recordSession(options.sessionId, {
730
+ kind: 'lock',
731
+ target: label,
732
+ code: lastFailure.code,
733
+ state: BREAKER_STATES.OPEN,
734
+ lockedUntil: breaker.snapshot().entries[key]?.lockedUntil ?? 0,
735
+ });
736
+ return { kind: 'failed', failure: lastFailure };
737
+ }
738
+ if (action !== ACTIONS.RETRY || index >= schedule.length) {
739
+ return { kind: 'failed', failure: lastFailure };
740
+ }
741
+
742
+ const nextDelayMs = Math.min(schedule[index].delayMs, budget.remainingMs());
743
+ this.recordSession(options.sessionId, {
744
+ kind: 'retry',
745
+ target: label,
746
+ code: lastFailure.code,
747
+ attempt: index + 1,
748
+ delayMs: Number.isFinite(nextDelayMs) ? nextDelayMs : schedule[index].delayMs,
749
+ });
750
+ this.logger?.warn?.(
751
+ `llm-resilience: ${label} attempt ${index + 1}/${schedule.length + 1} failed (${lastFailure.code}); retrying in ${nextDelayMs}ms`,
752
+ );
753
+ }
754
+
755
+ return { kind: 'failed', failure: lastFailure };
756
+ }
757
+
758
+ /**
759
+ * 单次上游调用。tool-call 的 block-start/delta 压到 `block-end` 再交付,
760
+ * 这样 MALFORMED_RESPONSE(工具参数非法、没有 block-end)发生时宿主还没
761
+ * 看见任何内容,可以安全重试。
762
+ */
763
+ async *attemptOnce({ target, options, messages }) {
764
+ const innerOptions = {
765
+ ...options,
766
+ provider: target.provider,
767
+ model: target.model,
768
+ messages,
769
+ };
770
+
771
+ const toolBuffers = new Map();
772
+ let usage;
773
+ let finish;
774
+ let failure;
775
+ let delivered = false;
776
+
777
+ try {
778
+ for await (const chunk of this.llm.stream(innerOptions)) {
779
+ if (chunk.type === 'usage') {
780
+ usage = chunk;
781
+ continue;
782
+ }
783
+ if (chunk.type === 'finish') {
784
+ finish = chunk;
785
+ break;
786
+ }
787
+ if (chunk.type === 'block-start' && chunk.blockType === 'tool-call') {
788
+ bufferChunk(toolBuffers, chunk);
789
+ continue;
790
+ }
791
+ if (chunk.type === 'tool-call-delta') {
792
+ bufferChunk(toolBuffers, chunk);
793
+ continue;
794
+ }
795
+ if (chunk.type === 'block-end' && chunk.block.type === 'tool-call' && toolBuffers.has(chunk.index)) {
796
+ for (const buffered of toolBuffers.get(chunk.index)) yield buffered;
797
+ toolBuffers.delete(chunk.index);
798
+ yield chunk;
799
+ delivered = true;
800
+ continue;
801
+ }
802
+ yield chunk;
803
+ delivered = true;
804
+ }
805
+ } catch (error) {
806
+ failure = normalizeThrown(error, options.signal);
807
+ }
808
+
809
+ if (failure === undefined && finish?.reason.kind === 'error') failure = finish.reason.failure;
810
+ if (failure === undefined && finish?.reason.kind === 'aborted') {
811
+ failure = finish.reason.failure ?? { message: 'stream aborted', code: 'ABORTED' };
812
+ }
813
+ if (failure === undefined && finish === undefined) {
814
+ failure = { message: 'inner stream ended without a finish chunk', code: 'STREAM_CLOSED' };
815
+ }
816
+
817
+ if (failure !== undefined) {
818
+ if (isAborted(options.signal)) return { kind: 'aborted', usage };
819
+ return { kind: 'failed', failure, delivered, usage };
820
+ }
821
+
822
+ if (toolBuffers.size > 0) {
823
+ this.logger?.warn?.(
824
+ `llm-resilience: ${targetLabel(target)} ended with ${toolBuffers.size} unterminated tool-call block(s); dropping them`,
825
+ );
826
+ }
827
+ if (usage !== undefined) yield usage;
828
+ yield wrapFinish(finish, target);
829
+ return { kind: 'success' };
830
+ }
831
+
832
+ #rememberHint(options, key, failure) {
833
+ if (options.sessionId === undefined) return;
834
+ this.hints.set(options.sessionId, {
835
+ fingerprint: requestFingerprint(options),
836
+ key,
837
+ failure,
838
+ });
839
+ }
840
+
841
+ /** 取出并消费一次「上一步已经试到这个 target」的提示;指纹不同视为过期。 */
842
+ #consumeHint(options) {
843
+ if (options.sessionId === undefined) return undefined;
844
+ const hint = this.hints.get(options.sessionId);
845
+ if (hint === undefined) return undefined;
846
+ this.hints.delete(options.sessionId);
847
+ return hint.fingerprint === requestFingerprint(options) ? hint : undefined;
848
+ }
849
+
850
+ #lockedError(attempts, breaker) {
851
+ const snapshot = breaker.snapshot().entries;
852
+ const now = this.now();
853
+ const details = attempts.map((attempt) => {
854
+ const entry = snapshot[attempt.key];
855
+ const until =
856
+ entry !== undefined && Number.isFinite(entry.lockedUntil) && entry.lockedUntil > now
857
+ ? ` until ${new Date(entry.lockedUntil).toISOString()}`
858
+ : '';
859
+ return `${attempt.label} (${attempt.state}${until})`;
860
+ });
861
+ return new LlmError(`llm-resilience: all targets are locked: ${details.join(', ')}`, 'ALL_TARGETS_LOCKED');
862
+ }
863
+
864
+ #exhaustedError(lastFailure, attempted, attempts) {
865
+ const last = lastFailure === undefined ? 'no target produced a response' : lastFailure.message;
866
+ const locked = attempts.length - attempted;
867
+ const suffix = locked > 0 ? `; ${locked} target(s) skipped by the circuit breaker` : '';
868
+ return failureError(
869
+ {
870
+ ...(lastFailure ?? { code: 'FALLBACK_EXHAUSTED' }),
871
+ code: 'FALLBACK_EXHAUSTED',
872
+ },
873
+ `llm-resilience: ${attempted} target(s) failed; last: ${last}${suffix}`,
874
+ );
875
+ }
876
+
877
+ #budgetError(reason, lastFailure, budget) {
878
+ const elapsed = Math.max(0, this.now() - budget.startedAt);
879
+ const code = reason === 'deadline' ? 'DEADLINE_EXCEEDED' : 'ATTEMPT_LIMIT';
880
+ const label =
881
+ reason === 'deadline'
882
+ ? `global deadline ${budget.maxTotalMs}ms`
883
+ : `global attempt limit ${budget.maxAttempts}`;
884
+ const last =
885
+ lastFailure === undefined
886
+ ? 'no target produced a response'
887
+ : `${lastFailure.code}: ${lastFailure.message}`;
888
+ return failureError(
889
+ { ...(lastFailure ?? { message: last }), code },
890
+ `llm-resilience: ${label} reached after ${budget.attempts} request(s) in ${elapsed}ms; last: ${last}`,
891
+ );
892
+ }
893
+
894
+ async *stream(options) {
895
+ const config = this.resolveConfig();
896
+ if (!config.enabled) throw new LlmError('llm-resilience: plugin is disabled', 'DISABLED');
897
+
898
+ const errors = validateChain(this.route, config.targets);
899
+ if (errors.length > 0) {
900
+ throw new LlmError(`llm-resilience: invalid configuration: ${errors.join('; ')}`, 'INVALID_CONFIG');
901
+ }
902
+ const targets = enabledTargets(config.targets);
903
+ if (targets.length === 0) {
904
+ throw new LlmError('llm-resilience: no targets configured', 'NO_TARGETS');
905
+ }
906
+
907
+ const breaker = this.ensureBreaker(config.breaker);
908
+ const budget = new AttemptBudget(config.limits, this.now);
909
+ const failBudget = (reason, failure) => {
910
+ this.recordSession(options.sessionId, {
911
+ kind: 'deadline',
912
+ reason,
913
+ attempts: budget.attempts,
914
+ code: failure?.code ?? null,
915
+ elapsedMs: Math.max(0, this.now() - budget.startedAt),
916
+ });
917
+ throw this.#budgetError(reason, failure, budget);
918
+ };
919
+ let attempts = planAttempts(targets, breaker, this.now());
920
+ const hint = this.#consumeHint(options);
921
+ if (hint !== undefined) {
922
+ const start = attempts.findIndex((attempt) => attempt.key === hint.key);
923
+ // 重放的续点是「轮转」,不是「截断」:
924
+ // 从失败 target 的下一个开始(保证跨重放的进展,不会把 3 次重放预算
925
+ // 全烧在一个粘性失败的链头上),绕回到被跳过的 target 结束。
926
+ // 截断(旧实现 slice(start + 1))会让 hint 之前的 target 在整次重放里
927
+ // 彻底消失。线上实测(2026-11-11 21:41,会话 54e71f76):eco 交付后断流
928
+ // → hint=eco → 重放只剩 [flash] → flash 撞上网关瞬时的 entitlement 500
929
+ // → 链空 → FALLBACK_EXHAUSTED「1 target(s) failed」,而 eco 早已恢复。
930
+ // 链尾的 hint 轮转后就是「从它自己开始」,与原地重试等价(见 DESIGN §13.8)。
931
+ if (start >= 0) {
932
+ const next = start + 1;
933
+ attempts = [...attempts.slice(next), ...attempts.slice(0, next)];
934
+ }
935
+ }
936
+ // 不变量:targets 非空(上面已判 NO_TARGETS),hint 只改变顺序、不删除任何 target,
937
+ // 因此这里一定还有可试的 target。真为空说明轮转逻辑写错——报错而不是伪装成链尾耗尽。
938
+ if (attempts.length === 0) {
939
+ throw new LlmError('llm-resilience: internal error: empty attempt plan for a non-empty chain', 'NO_TARGETS');
940
+ }
941
+ const usable = usableAttempts(attempts);
942
+ if (usable.length === 0) throw this.#lockedError(attempts, breaker);
943
+
944
+ const messages = unwrapMessages(options.messages, this.route);
945
+ let lastFailure;
946
+ let attempted = 0;
947
+
948
+ for (const plan of usable) {
949
+ if (isAborted(options.signal)) {
950
+ yield abortedFinish(options.signal);
951
+ return;
952
+ }
953
+
954
+ const stop = budget.stopReason();
955
+ if (stop !== undefined) failBudget(stop, lastFailure);
956
+
957
+ let claimedProbe = false;
958
+ if (plan.state === BREAKER_STATES.HALF_OPEN) {
959
+ // 后台探活:不阻塞当前请求,本次跳过;结果由下一个请求使用。
960
+ if (config.breaker.probe.enabled && config.breaker.probe.background) {
961
+ this.#startBackgroundProbe(plan, config.breaker.probe, options);
962
+ continue;
963
+ }
964
+ if (!breaker.beginProbe(plan.key)) continue;
965
+ claimedProbe = true;
966
+ if (config.breaker.probe.enabled) {
967
+ const remaining = budget.remainingMs();
968
+ if (remaining <= 0) failBudget('deadline', lastFailure);
969
+ const probeConfig =
970
+ remaining === Infinity
971
+ ? config.breaker.probe
972
+ : {
973
+ ...config.breaker.probe,
974
+ timeoutMs: Math.max(1, Math.min(config.breaker.probe.timeoutMs, remaining)),
975
+ };
976
+ const probe = await this.#runProbe(plan.target, probeConfig, options.signal);
977
+ if (probe.aborted === true) {
978
+ breaker.releaseProbe(plan.key);
979
+ yield abortedFinish(options.signal);
980
+ return;
981
+ }
982
+ if (probe.ok !== true) {
983
+ breaker.probeFailed(plan.key);
984
+ this.persist();
985
+ claimedProbe = false;
986
+ lastFailure = probe.failure;
987
+ this.logger?.warn?.(
988
+ `llm-resilience: probe failed for ${plan.label} (${
989
+ probe.failure?.code ?? 'UNKNOWN'
990
+ }); target locked again`,
991
+ );
992
+ continue;
993
+ }
994
+ // 探活成功后保持 probing 状态,直到真实请求给出成功/失败。
995
+ }
996
+ }
997
+
998
+ attempted += 1;
999
+ let result;
1000
+ try {
1001
+ result = yield* this.attemptTarget({
1002
+ target: plan.target,
1003
+ key: plan.key,
1004
+ label: plan.label,
1005
+ options,
1006
+ messages,
1007
+ config,
1008
+ breaker,
1009
+ budget,
1010
+ });
1011
+ } finally {
1012
+ // 成功时 entry 已被 recordSuccess 删除;失败时 probing 已清;
1013
+ // 取消 / 请求本身有错时这里负责把探活资格还回去,避免永久卡住。
1014
+ if (claimedProbe) breaker.releaseProbe(plan.key);
1015
+ }
1016
+
1017
+ if (result.kind === 'success') {
1018
+ this.hints.delete(options.sessionId);
1019
+ return;
1020
+ }
1021
+ if (result.kind === 'aborted') {
1022
+ this.hints.delete(options.sessionId);
1023
+ yield abortedFinish(options.signal);
1024
+ return;
1025
+ }
1026
+ if (result.kind === 'fatal') {
1027
+ this.#rememberHint(options, plan.key, result.failure);
1028
+ throw failureError(
1029
+ result.failure,
1030
+ `llm-resilience: ${plan.label} failed after streaming began; not switching targets: ${result.failure.message}`,
1031
+ );
1032
+ }
1033
+ if (result.kind === 'stop') {
1034
+ this.hints.delete(options.sessionId);
1035
+ throw failureError(result.failure);
1036
+ }
1037
+ if (result.kind === 'budget') {
1038
+ failBudget(result.reason, result.failure ?? lastFailure);
1039
+ }
1040
+
1041
+ lastFailure = result.failure;
1042
+ this.recordSession(options.sessionId, {
1043
+ kind: 'fallback',
1044
+ target: plan.label,
1045
+ code: result.failure.code,
1046
+ });
1047
+ this.logger?.warn?.(
1048
+ `llm-resilience: target ${plan.label} exhausted (${result.failure.code}); trying the next target`,
1049
+ );
1050
+ }
1051
+
1052
+ this.hints.delete(options.sessionId);
1053
+ throw this.#exhaustedError(lastFailure, attempted, attempts);
1054
+ }
1055
+ }