dsh-subagent-default-model 2.1.12 → 2.1.13

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/CHANGELOG.md CHANGED
@@ -1,5 +1,70 @@
1
1
  # Changelog
2
2
 
3
+ ## 2.1.13 (2026-11-05)
4
+
5
+ 适配宿主 **0.2.2-rc.1**。这次不是行号位移,而是**一条契约收紧了语义**。
6
+
7
+ ### Fixed
8
+
9
+ **故障转移在 0.2.2 上会抛宿主内部错误。**
10
+
11
+ 0.2.2 把模型路由从「每次请求由 `agent/request` 瀑布决定」改成「**每个 step 在准备阶段固定**」:
12
+
13
+ - `preStep()` 里 `const selection = this.model.current()` 先捕获,随后一路传递,**重试复用同一份**(类型文档:*captured step selection, retained across retries*);
14
+ - `prepareRequest()` 用它拼出 `seedConfig`,并对瀑布返回的配置新增硬校验——改 provider/model 直接抛 `agent "X": agent/request proposed … after step preparation fixed …`;
15
+ - 该瀑布本身被标 **`@deprecated`**:*a replacement may adjust controls but must keep the provider, model, and reasoning effort selection*,并指明唯一替代是 `agent.model.select()`。
16
+
17
+ 本插件的故障转移恰好就是「在 `agent/request` 里把 seed 换成池中下一个模型」,因此在 0.2.2 上**必然抛错**——一次额度耗尽会变成一句难懂的宿主内部错误,比不修更糟。
18
+
19
+ ### Changed
20
+
21
+ **双路径故障转移,按能力探测自动选择**(`typeof agent.model?.select === "function"`;`agent.model` 在 0.2.2 之前不存在,无需版本比较):
22
+
23
+ - **旧宿主(≤0.2.1)**:行为完全不变,失败的那次请求当场换模型重试。
24
+ - **新宿主(≥0.2.2)**:
25
+ 1. 先 `await next()` 让下游处理。`dsh-llm-retry` 已在 `dsh-base` 组合里默认启用并负责退避;**瞬时失败不该换路**——`select()` 会持久化到下一步,重试成功后仍会留下一次无辜的切换。
26
+ 2. 下游不重试才说明这条路真的死了:用 `agent.model.select()` 为**下一个 step / turn** 预选池中下一条健康路由,然后**放行原始错误**(它才说明真实原因:配额、密钥)。
27
+ 3. 每个 step 最多选一次;`agent/request` 在新宿主上直接 `return next()`,绝不改写路由。
28
+ 4. `select()` 被宿主拒绝时打 warn 并照常放行原始错误,绝不吞掉真实原因。
29
+
30
+ **必须承认的代价**:0.2.2 上「同一次请求内透明续跑」无法实现——失败的那一步路由已锁定,`select()` 只影响下一步。因此永久性失败(配额耗尽、密钥失效)会结束当前 turn,而不再换供应商续跑;可续跑的 subagent 下次被唤醒时已在健康路由上。这是宿主收回的能力,不是实现取舍,README 中英文两版都已如实写明。
31
+
32
+ ### Compatibility
33
+
34
+ `ADMITTED_HOST_VERSIONS` 补入 `0.2.2-rc.1`(自检用例先失败后通过,符合预期)。
35
+
36
+ 本轮逐包比对 rc.5 → 0.2.2-rc.1:`desktop-runtime.json` 的共享包从 305 增至 329,几乎所有包都有改动,但**只有 `dsh-agent-loop` 这一处契约收紧**。其余依赖面实测完好:
37
+
38
+ | 依赖面 | 结论 |
39
+ | --- | --- |
40
+ | `agent/pre-step` 瀑布 | 完好(payload 新增 `modelSelection`,增量) |
41
+ | `agent/request-error` 瀑布 | 完好(payload 新增 `provider` / `retryPolicy`) |
42
+ | `agent.inbox.prepend/claim` | 完好(内部重构 `projections` → `readState`,API 未变) |
43
+ | `subagents.getProvider` / `startActivation` | 完好 |
44
+ | provider 的 `inheritsParentContext` | 完好(fork provider 仍为 `true`,`applyToForkChildren` 门禁依据不变) |
45
+ | `session.requestContext()` | 完好(`:1627` → `:1636`) |
46
+ | 客户端槽位 / locale / `settings.mutate` | 完好(`chat-subagent-model-notice` 实测 active) |
47
+ | `request/header` 的 `reason` 取值 | 完好(`initial` / `resume` / `change` / `series` 未变,对话行仍正常) |
48
+
49
+ 实测(宿主机 0.2.2-rc.1):`subagent` 子代理拿到池中 `minmax/MiniMax-M3.1-Flash`;`subagent_fork` 子代理按门禁继承父路由 `dsh-opencode-go`,未注入。
50
+
51
+ ### Tests
52
+
53
+ `172/172`(164 → 172),`skip 0`。新增 8 个用例覆盖新宿主路径:
54
+
55
+ - 下游重试成功时**不得**换路(否则重试成功后仍会留下一次无辜切换)
56
+ - 无人重试时选中下一条池内路由,并**放行原始错误**(而非宿主 guard 错误)
57
+ - `agent/request` 必须**原样返回**该 step 的路由(这条正是回归本体)
58
+ - 同一 step 最多选一次;下一个 step 可再选
59
+ - 池耗尽不再选新候选、不再伪造 retry
60
+ - `select()` 被拒时打 warn 且不吞原始错误
61
+ - AUTH 仍切换,且仍打「密钥可能无效」告警
62
+ - 主代理循环仍不受影响
63
+
64
+ 变异验证 4/4 命中:①新宿主仍走旧的 `agent/request` 覆盖路径 → 5 个用例失败;②`agent/request` 不提前 return → 原样返回用例失败;③忽略下游 retry → 不换路用例失败;④去掉「每 step 一次」限制 → 该用例失败。
65
+
66
+ > 夹具也被修了:原来它只驱动 `agent/request` 并断言返回值变了,模拟的是**旧宿主契约**,所以在会抛错的新宿主上依然全绿。当宿主给契约加硬校验时,夹具必须把校验也加进去,否则它只是在自证清白。
67
+
3
68
  ## 2.1.12 (2026-10-30)
4
69
 
5
70
  ### Fixed
package/lib/index.js CHANGED
@@ -200,6 +200,27 @@ const AUTH_FAILURE_CODES = ["AUTH", "INVALID_CREDENTIAL"];
200
200
  /** Every failure code that may trigger a switch. */
201
201
  const FAILOVER_ELIGIBLE_CODES = [...FAILOVER_TRIGGER_CODES, ...AUTH_FAILURE_CODES];
202
202
 
203
+ /**
204
+ * Whether this host fixes the step's route and only sanctions changing it
205
+ * through `agent.model.select()`.
206
+ *
207
+ * DSH 0.2.2 replaced the per-request route with a STEP-FIXED selection:
208
+ * `preStep()` reads `agent.model.current()` once and hands the result to the
209
+ * `agent/request` waterfall as `modelSelection`, which the type documents as
210
+ * "captured step selection, retained across retries". A listener that returns
211
+ * a different provider/model now throws
212
+ * `agent "X": agent/request proposed "p/m" after step preparation fixed "a/b"`
213
+ * — the waterfall itself is marked `@deprecated` for this use ("a replacement
214
+ * may adjust controls but must keep the provider, model, and reasoning effort
215
+ * selection").
216
+ *
217
+ * `agent.model` does not exist before 0.2.2, so this is a capability probe
218
+ * rather than a version compare: one plugin build serves both hosts.
219
+ */
220
+ function fixesStepRoute(agent) {
221
+ return typeof agent?.model?.select === "function";
222
+ }
223
+
203
224
  /** True when a failure code is an auth-class failure (picks the log wording). */
204
225
  function isAuthFailure(code) {
205
226
  return AUTH_FAILURE_CODES.includes(code);
@@ -380,6 +401,95 @@ function nextFailoverIndex(view, agent, current) {
380
401
  return (found + 1) % entries.length;
381
402
  }
382
403
 
404
+ /**
405
+ * Record a healthy route for the steps that FOLLOW a failure (DSH 0.2.2+).
406
+ *
407
+ * On these hosts the failed request cannot be re-routed: `preStep()` captured
408
+ * the step's selection and `agent/request` must hand it back unchanged, so a
409
+ * retry re-issues to the same dead route. The one sanctioned lever is
410
+ * `agent.model.select()`, whose result is read at the NEXT step preparation.
411
+ *
412
+ * Therefore:
413
+ *
414
+ * 1. ask the rest of the waterfall first. `dsh-llm-retry` owns backoff and is
415
+ * mounted in the base composition; a transient failure it recovers must NOT
416
+ * move the route, and pre-empting it here (as the pre-0.2.2 path does, where
417
+ * the retry carried a new route) would strip the backoff for no gain.
418
+ * 2. if nothing retries, this route is the reason the turn dies. Select the
419
+ * next untried pool entry so any later step or turn starts on a healthy
420
+ * route, and let the ORIGINAL error surface — it names the real cause
421
+ * (quota, auth), unlike the host's "after step preparation fixed" guard.
422
+ *
423
+ * The visible consequence, stated plainly: on 0.2.2 a permanently failing
424
+ * route ends the current turn instead of being transparently continued on
425
+ * another provider. The pool still governs every SUBSEQUENT request, so a
426
+ * continuable subagent resumes on a healthy route and the parent's next
427
+ * follow-up is not stuck on the dead one.
428
+ */
429
+ async function switchForNextStep(ctx, state, pending, payload, next) {
430
+ const { agent, step, failure, signal } = payload;
431
+ const downstream = await next();
432
+ if (signal?.aborted) return downstream;
433
+ // Someone downstream (llm-retry) is recovering this request: leave the
434
+ // route alone, since the failure may be transient.
435
+ if (downstream?.kind === "retry") return downstream;
436
+ // Re-read the view: the settings may have changed while we awaited.
437
+ const view = failoverView(state);
438
+ if (view === void 0) return downstream;
439
+ const current = pending.get(agent.id);
440
+ if (current !== void 0 && current.step === step) return downstream; // already switched for this step
441
+ if (current !== void 0 && current.count >= view.entries.length - 1) return downstream; // pool exhausted
442
+ const index = nextFailoverIndex(view, agent, current);
443
+ const target = view.entries[index];
444
+ if (target === void 0) return downstream;
445
+ const tried = new Set(current?.tried ?? []);
446
+ tried.add(index);
447
+ pending.set(agent.id, {
448
+ index,
449
+ tried,
450
+ count: (current?.count ?? 0) + 1,
451
+ step
452
+ });
453
+ try {
454
+ agent.model.select({
455
+ provider: target.provider,
456
+ model: target.model,
457
+ ...(target.reasoningEffort === void 0 ? {} : { reasoningEffort: target.reasoningEffort })
458
+ });
459
+ } catch (error) {
460
+ // A host that exposes `model.select` but refuses this call is not a
461
+ // reason to swallow the real failure — report it and let the original
462
+ // error through.
463
+ ctx.logger.warn(
464
+ `[dsh-subagent-default-model] could not pre-select %s/%s after %s; the subagent keeps its route: %s`,
465
+ target.provider,
466
+ target.model,
467
+ failure.code,
468
+ error instanceof Error ? error.message : String(error)
469
+ );
470
+ return downstream;
471
+ }
472
+ ctx.logger.warn(
473
+ `[dsh-subagent-default-model] subagent %s failed with %s on turn %d step %d; %s/%s is selected for its NEXT step (this host fixes the route of the failed step, so the current turn cannot continue on it)`,
474
+ agent.id,
475
+ failure.code,
476
+ payload.turn,
477
+ step,
478
+ target.provider,
479
+ target.model
480
+ );
481
+ if (isAuthFailure(failure.code)) {
482
+ ctx.logger.warn(
483
+ `[dsh-subagent-default-model] the credentials for the failing provider %s were refused (%s). This is NOT a connection problem: that provider's API key is likely invalid, expired, or unauthorised. The next step will use %s/%s — verify the failing provider's key, because every request routed to it will fail until it is fixed.`,
484
+ payload.provider ?? "(unknown)",
485
+ failure.code,
486
+ target.provider,
487
+ target.model
488
+ );
489
+ }
490
+ return downstream;
491
+ }
492
+
383
493
  /**
384
494
  * Install the subagent-only failover waterfalls. Both listeners no-op for the
385
495
  * main agent (origin gate) and for subagents whose failure code is not a
@@ -394,13 +504,17 @@ function installFailover(ctx, state) {
394
504
  // After a model failure on a subagent loop: advance the pool index and ask
395
505
  // the loop to rebuild the request (`{ kind: "retry" }`). When every pool
396
506
  // entry has been tried, let the real error surface untouched.
397
- const disposeRequestError = ctx.on("agent/request-error", (payload, next) => {
507
+ const disposeRequestError = ctx.on("agent/request-error", async (payload, next) => {
398
508
  const view = failoverView(state);
399
509
  if (view === void 0) return next();
400
510
  const { agent, turn, step, failure, signal } = payload;
401
511
  if (signal?.aborted) return next();
402
512
  if (!isSubagentAgent(agent)) return next();
403
513
  if (failure === void 0 || !FAILOVER_ELIGIBLE_CODES.includes(failure.code)) return next();
514
+ // 0.2.2+ fixed the route for the whole step, so the route cannot be
515
+ // swapped on the retry this hook used to request. See
516
+ // `switchForNextStep` for what replaces it.
517
+ if (fixesStepRoute(agent)) return switchForNextStep(ctx, state, pending, payload, next);
404
518
  const current = pending.get(agent.id);
405
519
  // The primary already failed (that triggered the first switch), so the
406
520
  // remaining candidates are the other pool entries: at most
@@ -464,6 +578,11 @@ function installFailover(ctx, state) {
464
578
  if (view === void 0) return next();
465
579
  const { agent } = payload;
466
580
  if (!isSubagentAgent(agent)) return next();
581
+ // 0.2.2+ : the route is fixed for the step and the host throws when a
582
+ // listener changes it. `switchForNextStep` already recorded the new
583
+ // selection, which the NEXT step reads; returning the seed untouched is
584
+ // the only correct answer here.
585
+ if (fixesStepRoute(agent)) return next();
467
586
  const current = pending.get(agent.id);
468
587
  if (current === void 0) return next();
469
588
  const target = view.entries[current.index];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-subagent-default-model",
3
- "version": "2.1.12",
3
+ "version": "2.1.13",
4
4
  "description": "为 DeepSeek Harness 子代理配置默认模型:多模型顺序/随机分配、跨供应商连接失败故障转移,并在轨迹/对话视图显示当前供应商与模型,同时以一行真实提示词把当前路由注入子代理上下文。",
5
5
  "keywords": [
6
6
  "deepseek-harness",