Merge remote-tracking branch 'origin/master' into worktree/pr703-ci-fix-20260727

# Conflicts:
#	docs/architecture.i18n.yaml
#	packages/core/agent-loop/src/agent.ts

packages/core/agent-loop/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/agent-loop/README.md
-README.md: ab6df4d49f05ff00b16a210830e7fd21504a0a9f
-README.zh.md: 5adb2a11ba3de2bb6fc7ff57b9d6dd07ac7f650e
+README.md: c12140f27aed400b0f7b4246700473e877d37632
+README.zh.md: 6394cd86f5f3241be07ef711c76079624bce1bfe

packages/core/agent-loop/README.md

@@ -64,7 +64,7 @@ Every provider call that reaches a successful finish appends exactly one `assist
 
 After `agent/request` returns a provider/model call config, the loop asks `ctx.llm.prepareCall()` to validate any adapter-owned reasoning effort and materialize its configured default under the active turn signal. The prepared call retains the exact adapter registration across this asynchronous resolution, `request/header` logging, and terminal dispatch, so HMR cannot mix one adapter's capability result with another adapter's request. The effective config is logged before dispatch, so a listener can change effort between steps without hidden request drift. A route with no registered adapter preserves the proposed config so an `llm/stream` listener can own and short-circuit it; unhandled terminal dispatch still fails with `NO_ADAPTER`. A new loop instance restores the last effort only when its initial provider/model route exactly matches the logged route; a route change discards that opaque model-owned ID and resolves the new model independently.
 
-Plugin failure ends the current turn, not the loop. A model-request failure first closes its step and enters `agent/request-error` with the exact live error, normalized provider facts, and the turn signal. A handling listener returns `{ kind: 'retry' }`; the loop closes the failed turn with its error and opens one numbered retry turn without an intervening idle notification. An unhandled failure is terminal. Other failures close directly. AgentLoop owns one cancellation signal for the current admission or turn. An effective `cancel(cause)` clears pending work unless `keepInbox` is set and cooperatively aborts that signal; idle cancellation is a no-op. Durable `turn/end` records `aborted` for `user` and `parent`, while disposal records `disposed`; undispatched model tool calls receive synthetic `tool/call` and `ABORTED_BEFORE_DISPATCH` result pairs. The cancellation cause changes reporting, not how result context finalized after cancellation is handled. Disposal waits for signal-ignoring work before registry removal. The [explicit-cancellation decision](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md) owns the lifecycle and race contract.
+Plugin failure ends the current turn, not the loop. Only final adapter dispatch/iteration failures and terminal in-band error or aborted finishes enter `agent/request-error`; middleware, result processing, tools, and other extension failures close directly. Recovery receives the exact live error, immutable provider facts, immutable prior failures, the immutable retry policy of the adapter registration that served the request, and the turn signal after the failed step closes; the policy is absent if no final adapter served it. A handling listener returns `{ kind: 'retry' }`; the loop closes the failed turn with its error and opens one numbered retry turn without an intervening idle notification. Success clears the consecutive history, and an unhandled failure is terminal. AgentLoop owns one cancellation signal for the current admission or turn. An effective `cancel(cause)` clears pending work unless `keepInbox` is set and cooperatively aborts that signal; idle cancellation is a no-op. Durable `turn/end` records `aborted` for `user` and `parent`, while disposal records `disposed`; undispatched model tool calls receive synthetic `tool/call` and `ABORTED_BEFORE_DISPATCH` result pairs. The cancellation cause changes reporting, not how result context finalized after cancellation is handled. Disposal waits for signal-ignoring work before registry removal. The [explicit-cancellation decision](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md) owns the lifecycle and race contract.
 
 Within a step, exclusive calls form barriers; parallel-safe calls use a bounded rolling pool and are reclassified before start. Only dispatch/body overlaps. Policy, durable results, and result context remain model-ordered. Abort stops new calls, drains started results, and retains their finalized result context without distinguishing the cancellation cause.
 
@@ -73,7 +73,7 @@ Within a step, exclusive calls form barriers; parallel-safe calls use a bounded
 Everything that goes beyond "call the model, run the tools, repeat" belongs to plugins listening on the event taxonomy:
 - Hooks and policy: the relevant `agent/*` checkpoints plus the guarded `tools/pre-execute` → `tools/execute` → `tools/post-execute` → definition-owned `finalizeContent` → `tools/result` pipeline; exact event signatures and modes live in the [generated event catalog](../../../docs/cordis-catalog/events.md)
 - Compaction: pressure on `agent/step`; canonical overflow repair on `agent/request-error`
-- Transient model recovery: `dsh-llm-retry` records and waits its finite backoff on `agent/request-error`, then returns a retry action
+- Model-request recovery: `dsh-llm-retry` records and waits exact-provider normal or unbounded backoff on `agent/request-error`, emits non-surface `llm/retry` status, then returns a retry action
 - Sandbox, permission, plan mode: `tools/pre-execute` for extensible deny/ask, `tools.guard()` for monotonic owner policy, `tools/post-execute` for result decisions, and `tools/result` for final observation
 - Sub-agents: implemented outside the loop as `ctx.subagents` providers; in-process providers use `ctx.agents.create()` and owned `AgentHandle` teardown, while generic [`ctx.tasks`](../../tasks/tasks/) plus [`dsh-tool-subagent`](../../subagent/tool-subagent/) own background collection.
 - Persistence: eager write-behind from `session/event`; `session/flush` is an explicit observation barrier

packages/core/agent-loop/README.zh.md

@@ -64,7 +64,7 @@ interface Config {
 
 在 `agent/request` 返回提供方／模型调用配置后，循环会调用 `ctx.llm.prepareCall()`，在活跃轮次信号的控制下校验由适配器持有的推理（reasoning）强度，并填入其配置默认值。准备完成的调用会在这次异步解析、`request/header` 日志记录和最终分派期间保留同一项确切的适配器注册，因此 HMR（热模块替换）不会把某个适配器的能力解析结果与另一适配器的请求混用。生效配置会在分派前写入日志，因此监听器可以在步骤之间更改推理强度，而不会产生未记录的请求变化。没有已注册适配器的路由会保留原定配置，使 `llm/stream` 监听器可以接管并短路该请求；最终分派仍会以 `NO_ADAPTER` 拒绝未得到处理的路由。新循环实例仅在初始提供方／模型路由与日志路由完全一致时恢复上次的推理强度；路由变化会丢弃由前一模型持有的不透明 ID，并单独解析新模型。
 
-插件失败会结束当前轮次，而不是结束循环。模型请求失败会先关闭其步骤，再带着确切的实时错误、规范化的提供方事实和轮次信号进入 `agent/request-error`。处理失败的监听器返回 `{ kind: 'retry' }`；循环用其错误关闭失败轮次，并在不插入空闲通知的情况下开启一个编号重试轮次。未被处理的失败是终态。其他失败直接关闭轮次。AgentLoop 为当前接纳或轮次拥有一个取消信号。有效的 `cancel(cause)` 在未设置 `keepInbox` 时清除待处理工作，并以协作方式中止该信号；空闲取消是空操作。持久 `turn/end` 为 `user` 和 `parent` 记录 `aborted`，dispose 则记录 `disposed`；未分发的模型工具调用会收到合成的 `tool/call` 与 `ABORTED_BEFORE_DISPATCH` 结果对。取消原因只改变报告方式，不改变对取消后已定案结果上下文的处理。Dispose 会等待忽略信号的工作完成，然后才从注册表移除。[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)规定生命周期与竞态契约。
+插件失败会结束当前轮次，而不是结束循环。只有最终适配器分发／迭代失败以及带内的终止错误或中止结束才进入 `agent/request-error`；中间件、结果处理、工具及其他扩展失败会直接关闭轮次。失败步骤关闭后，恢复逻辑会接收确切的实时错误、不可变的提供方事实、不可变的先前失败、为请求提供服务的适配器注册所对应的不可变重试策略，以及轮次信号；如果没有最终适配器为其提供服务，则该策略缺失。处理失败的监听器返回 `{ kind: 'retry' }`；循环用其错误关闭失败轮次，并在不插入空闲通知的情况下开启一个编号重试轮次。成功会清除连续失败历史；未被处理的失败是终态。AgentLoop 为当前接纳或轮次拥有一个取消信号。有效的 `cancel(cause)` 在未设置 `keepInbox` 时清除待处理工作，并以协作方式中止该信号；空闲取消是空操作。持久 `turn/end` 为 `user` 和 `parent` 记录 `aborted`，dispose（资源释放）则记录 `disposed`；未分发的模型工具调用会收到合成的 `tool/call` 与 `ABORTED_BEFORE_DISPATCH` 结果对。取消原因只改变报告方式，不改变对取消后已定案结果上下文的处理。dispose 会等待忽略信号的工作完成，然后才从注册表移除。[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)规定生命周期与竞态契约。
 
 在步骤内，独占调用形成屏障；并行安全调用使用有界滚动池，并在启动前重新分类。只有分发／主体会重叠。策略、持久结果和结果上下文仍保持模型顺序。中止会停止新调用，drain 已启动的结果，并保留其已定案的结果上下文，不区分取消原因。
 
@@ -73,7 +73,7 @@ interface Config {
 超出「调用模型、运行工具、重复」的所有内容，都属于监听事件分类体系的插件：
 - 钩子与策略：相关的 `agent/*` 检查点，加上受守卫保护的 `tools/pre-execute` → `tools/execute` → `tools/post-execute` → 定义拥有的 `finalizeContent` → `tools/result` 流水线；确切事件签名与 mode 位于生成的[事件目录](../../../docs/cordis-catalog/events.md)
 - 压缩（compaction）：在 `agent/step` 上观测压力；在 `agent/request-error` 上修复规范溢出
-- 瞬时模型恢复：`dsh-llm-retry` 在 `agent/request-error` 上记录并等待其有限退避，然后返回重试动作
+- 模型请求恢复：`dsh-llm-retry` 在 `agent/request-error` 上记录并等待按确切提供方配置的 normal 或无界退避，发出不进入表层的 `llm/retry` 状态，然后返回重试动作
 - 沙箱、权限、计划模式：使用 `tools/pre-execute` 提供可扩展的拒绝／询问，使用 `tools.guard()` 提供单调拥有方策略，使用 `tools/post-execute` 处理结果决定，并使用 `tools/result` 进行最终观测
 - subagent：在循环外部实现为 `ctx.subagents` 提供方；进程内提供方使用 `ctx.agents.create()` 和拥有的 `AgentHandle` 进行 teardown，而通用的 [`ctx.tasks`](../../tasks/tasks/) 与 [`dsh-tool-subagent`](../../subagent/tool-subagent/) 负责后台收集。
 - 持久化：从 `session/event` 立即后写；`session/flush` 是显式观测屏障

packages/core/agent-loop/src/agent.ts

@@ -27,9 +27,9 @@ import type {
   SendOptions,
 } from '@deepseek-ai/dsh-agent'
 import {
-  BlockAssembler, LlmError, assertNever, deepFreeze, errorChain, isHarnessError, llmFailureOf, markAgentLoopRequest,
+  BlockAssembler, LlmError, assertNever, deepFreeze, errorChain, isHarnessError, llmFailureOf, llmRetryPolicyOf, markAgentLoopRequest,
 } from '@deepseek-ai/dsh-llm'
-import type { GenerateOptions, LlmCallConfig, LlmFailure, Message, PreparedLlmCall } from '@deepseek-ai/dsh-llm'
+import type { GenerateOptions, LlmCallConfig, LlmFailure, Message, PreparedLlmCall, ResolvedRetryPolicy } from '@deepseek-ai/dsh-llm'
 import { canonicalHeader, headerEquals } from '@deepseek-ai/dsh-session'
 import type { Session, SessionId, TurnEndReason, TurnTrigger, UserMessageData } from '@deepseek-ai/dsh-session'
 import { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
@@ -39,7 +39,7 @@ import { executeToolCalls } from './tool-calls.ts'
 /** One completed step or a final-adapter failure eligible for recovery. */
 type StepOutcome =
   | { kind: 'completed'; continueTurn: boolean; concluded: boolean; maxTokens: boolean }
-  | { kind: 'request-failed'; error: RequestError; failure: LlmFailure }
+  | { kind: 'request-failed'; error: RequestError; failure: LlmFailure; retryPolicy: ResolvedRetryPolicy | undefined }
 
 /**
  * The concrete {@link Agent}: each `run()` owns one turn and repeats model
@@ -303,6 +303,7 @@ export class ReactLoopAgent implements Agent {
     trigger: TurnTrigger,
     admitted: UserMessageData[] = [],
     inheritedOutboxLength = 0,
+    priorFailures: readonly LlmFailure[] = Object.freeze([]),
   ): Promise<void> {
     // Both entries hold the invariant: kick() clears the admission slot before
     // awaiting run(), and a retry is entered only after the prior run clears it.
@@ -317,8 +318,9 @@ export class ReactLoopAgent implements Agent {
     let opened = false
     let reason: TurnEndReason = { kind: 'completed' }
     let settleReason: SettleReason = { kind: 'completed' }
-    let retry = false
-    const cancelRetry = (): void => { retry = false }
+    let requestFailureHistory = priorFailures
+    let retryFailures: readonly LlmFailure[] | undefined
+    const cancelRetry = (): void => { retryFailures = undefined }
     signal.addEventListener('abort', cancelRetry, { once: true })
 
     try {
@@ -344,6 +346,7 @@ export class ReactLoopAgent implements Agent {
         const outcome = await this.step(turn, step, signal)
         switch (outcome.kind) {
           case 'completed':
+            requestFailureHistory = Object.freeze([])
             if (outcome.maxTokens) reason = { kind: 'max-tokens' }
             // A concluding tool result is terminal: steering already in the
             // log waits for the next turn's request instead of reopening this
@@ -361,10 +364,13 @@ export class ReactLoopAgent implements Agent {
               try {
                 const action = await this.loopCtx.waterfall(
                   agentCarrier(this), 'agent/request-error', this, turn, step, outcome.error,
-                  outcome.failure, signal,
+                  outcome.failure, requestFailureHistory, outcome.retryPolicy, signal,
                   () => Promise.resolve<RequestErrorAction>(undefined),
                 )
-                retry = action?.kind === 'retry' && !signal.aborted
+                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- signal can abort while recovery is awaited.
+                if (action?.kind === 'retry' && !signal.aborted) {
+                  retryFailures = Object.freeze([...requestFailureHistory, outcome.failure])
+                }
               } catch (recoveryError: unknown) {
                 this.loopCtx.logger.warn(
                   `agent "${this.id}": request recovery failed at turn ${turn}, step ${step}: ${errorChain(recoveryError)}`,
@@ -411,7 +417,7 @@ export class ReactLoopAgent implements Agent {
           this.session.append('turn/end', { turn, reason })
         }
       } catch (error: unknown) {
-        retry = false
+        retryFailures = undefined
         this.loopCtx.logger.warn(`agent "${this.id}": closing turn ${turn} failed: ${errorChain(error)}`)
         emitAgentEvent(this.loopCtx, this, 'agent/error', turn, step, error)
       }
@@ -431,8 +437,8 @@ export class ReactLoopAgent implements Agent {
       }
     }
 
-    if (retry) {
-      await this.run({ kind: 'retry' })
+    if (retryFailures !== undefined) {
+      await this.run({ kind: 'retry' }, [], 0, retryFailures)
     } else {
       // agent/settled names only committed turns: a run aborted or rejected
       // before turn/start has no durable turn/end for consumers to settle
@@ -492,7 +498,7 @@ export class ReactLoopAgent implements Agent {
     } catch (error: unknown) {
       const facts = llmFailureOf(stream, error)
       if (facts !== undefined && error instanceof Error) {
-        return { kind: 'request-failed', error, failure: facts }
+        return { kind: 'request-failed', error, failure: facts, retryPolicy: llmRetryPolicyOf(stream) }
       }
       throw error
     }
@@ -502,7 +508,7 @@ export class ReactLoopAgent implements Agent {
     const finish = assembler.finish
     if (finish.kind === 'error' || finish.kind === 'aborted') {
       const error = new LlmError(finish.failure.message, finish.failure.code, finish.failure)
-      return { kind: 'request-failed', error, failure: finish.failure }
+      return { kind: 'request-failed', error, failure: finish.failure, retryPolicy: llmRetryPolicyOf(stream) }
     }
 
     // Truncated (max-tokens) output cannot owe tool calls.

packages/core/agent-loop/tests/coverage-edges.spec.ts

@@ -285,7 +285,9 @@ describe('request-error action edges', () => {
     ])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('retry-raced'), { provider: 'mock', model: 'mock' })
-    ctx.on('agent/request-error', async (subject, _turn, _step, _error, _failure, signal, next) => {
+    ctx.on('agent/request-error', async (
+      subject, _turn, _step, _error, _failure, _priorFailures, _retryPolicy, signal, next,
+    ) => {
       await next()
       subject.cancel({ kind: 'user' })
       expect(signal.aborted).toBe(true)

packages/core/agent-loop/tests/request-error.spec.ts

@@ -3,7 +3,7 @@ import { Context } from 'cordis'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import LlmService, { LlmError } from '@deepseek-ai/dsh-llm'
-import type { LlmFailure } from '@deepseek-ai/dsh-llm'
+import type { LlmFailure, ResolvedRetryPolicy } from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
@@ -55,7 +55,13 @@ describe('agent/request-error', () => {
     ])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('request-error-retry'), { provider: 'mock', model: 'mock' })
-    const seen: { turn: number; step: number; failure: LlmFailure }[] = []
+    const seen: {
+      turn: number
+      step: number
+      failure: LlmFailure
+      priorFailures: readonly LlmFailure[]
+      retryPolicy: ResolvedRetryPolicy | undefined
+    }[] = []
     const statuses: string[] = []
     const settledTurns: number[] = []
     ctx.on('agent/status', (subject, status) => {
@@ -64,13 +70,15 @@ describe('agent/request-error', () => {
     ctx.on('agent/settled', (subject, turn) => {
       if (subject === agent) settledTurns.push(turn)
     })
-    ctx.on('agent/request-error', async (subject, turn, step, _error, failure) => {
+    ctx.on('agent/request-error', async (
+      subject, turn, step, _error, failure, priorFailures, retryPolicy,
+    ) => {
       expect(subject).toBe(agent)
       expect(agent.session.events.at(-1)).toMatchObject({
         type: 'step/end',
         data: { turn, step },
       })
-      seen.push({ turn, step, failure })
+      seen.push({ turn, step, failure, priorFailures, retryPolicy })
       return { kind: 'retry' }
     })
 
@@ -99,6 +107,12 @@ describe('agent/request-error', () => {
         { kind: 'retry' },
         { kind: 'retry' },
       ])
+    expect(seen.map(item => item.priorFailures.map(failure => failure.code)))
+      .toEqual([[], ['RATE_LIMIT']])
+    expect(seen.map(item => item.retryPolicy)).toEqual([
+      expect.objectContaining({ mode: 'normal' }),
+      expect.objectContaining({ mode: 'normal' }),
+    ])
     expect(statuses).toEqual(['running', 'idle'])
     expect(settledTurns).toEqual([3])
   })