Merge remote-tracking branch 'origin/master' into fix/pty-handoff-grace

packages/client/ui-conversation/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/client/ui-conversation/README.md
-README.md: 453922dafd1eb7a617cb2d1c93ac1daa2e7273c6
-README.zh.md: 88992176165ab11050a30c7df381479796908ba2
+README.md: 32651291253077098bc43a930cf4ce11d29b1ed8
+README.zh.md: ea8f398541d7af6136b29c3365a78c4ea3a1e85d

packages/client/ui-conversation/README.md

@@ -8,7 +8,7 @@ The no-session hero renders the frontend Session Intent from the Session list pr
 
 The view ring IS a slot: the conversation registration declares the `'conversation.view'` list slot (session scope) in its `children` table, ConversationRoot renders the active entry through its renderSlot share (`only: <active id>`), and view tabs project from the ring ledger's registration options (`id`/`order`/`label`). The chat view is this package's own ring entry; other plugins (ui-trajectory) contribute tabs through plain `ctx.slots.register` — the former package-local view registry (`registerView`/`ViewEntry`/`ConversationViewMap` and the chrome attachment table) is retired, with per-view chrome dissolved into the view components themselves.
 
-Generic tool rows classify the built-in bash, read, search, write, edit, and run_code names into dedicated visual variants. The filesystem variants render the edit icon and `Write · <path>` or `Edit · <path>` summary while retaining the shared row-to-details interaction. The code variant summarizes with the model-authored `description` and expands to the program itself; its logged sub-dispatches render as always-visible nested rows through the SAME keyed toolview hole (custom registrations and the GenericToolCard fallback apply to sub-rows unchanged), and the details panel resolves a selected sub-call id to its full logged args and complete output.
+Generic tool rows classify the built-in bash, read, search, write, edit, and run_code names into dedicated visual variants. The filesystem variants render the edit icon and `Write · <path>` or `Edit · <path>` summary while retaining the shared row-to-details interaction. The code variant summarizes with the model-authored `description` and expands to the program itself; its logged sub-dispatches render as always-visible nested rows through the SAME keyed toolview hole (custom registrations and the GenericToolCard fallback apply to sub-rows unchanged), and the details panel resolves a selected sub-call id to its full logged args and complete output. Cordis lifecycle tools reuse those generic variants while presenting `Inspect`, `Mount temporary Plugin`, and `Unmount temporary Plugin` with a shared Cordis accent; mount keeps the code variant's expandable source rendering.
 
 Tool rows are slots too — the standalone tool ring (`ToolViewRegistry`/`ctx.toolviews`/outlet) is retired. The chat entry declares the keyed `'conversation.chat.toolview'` hole (session scope; the key space is runtime-open); its render site dispatches per row via `entryKey: toolName` with `GenericToolCard` as the call-site `fallback`. The owner payload is the uniform `ToolRowOwnerProps` (`callId`/`toolName`/`block`/`openDetails`) and `ToolRowProps` pre-composes it with the session standard kit. A registrant is a plain plugin: `ctx.slots.register({ name: 'conversation.chat.toolview', key: '<tool>', inject? }, Row)` with `inject: ['slots', 'conversation']` as the load-order seam (apply mounts ConversationService after the chat registration, so the service being present guarantees the slot is declared); session differentiation happens inside the component (`useSessions` reading `parentId` — the bash sample is the third-party-posture exemplar). Trajectory/waterfall toolview slots share this shape and land with their own render sites (RendersCheck rejects a declaration nobody renders).
 

packages/client/ui-conversation/README.zh.md

@@ -8,7 +8,7 @@
 
 视图环本身就是 slot：会话注册声明 `'conversation.view'` 列表 slot（Session scope），并将其列在 `children` 表中；ConversationRoot 通过 renderSlot share 渲染活跃配置项（`only: <active id>`）；视图标签页从环账本的注册选项（`id`／`order`／`label`）投影而来。聊天视图是该包自身的环配置项；其他插件（ui-trajectory）通过普通的 `ctx.slots.register` 贡献标签页。先前包内的视图注册表（`registerView`／`ViewEntry`／`ConversationViewMap` 及 chrome 附加表）已退役，逐视图 chrome 则被拆入视图组件自身。
 
-通用工具行把内置的 bash、read、search、write、edit 和 run_code 名称归入专用视觉变体。文件系统变体会渲染 edit 图标和 `Write · <path>` 或 `Edit · <path>` 摘要，同时保留共享的行到详情交互。code 变体以模型撰写的 `description` 作摘要，展开后显示程序本身；其已记录的子调用经由同一个键控 toolview 空位渲染为始终可见的嵌套行（自定义注册和 GenericToolCard fallback 原样适用于子行），details 面板则会根据选中的子调用 id 解析出其完整记录的参数与完整输出。
+通用工具行把内置的 bash、read、search、write、edit 和 run_code 名称归入专用视觉变体。文件系统变体会渲染 edit 图标和 `Write · <path>` 或 `Edit · <path>` 摘要，同时保留共享的行到详情交互。code 变体以模型撰写的 `description` 作摘要，展开后显示程序本身；其已记录的子调用经由同一个键控 toolview 空位渲染为始终可见的嵌套行（自定义注册和 GenericToolCard fallback 原样适用于子行），details 面板则会根据选中的子调用 id 解析出其完整记录的参数与完整输出。Cordis 生命周期工具复用这些通用变体，同时以统一的 Cordis 强调色呈现 `Inspect`、`Mount temporary Plugin` 和 `Unmount temporary Plugin`；mount 行保留 code 变体的可展开源码渲染。
 
 工具行同样是 slot：独立工具环（`ToolViewRegistry`／`ctx.toolviews`／outlet）已经退役。聊天配置项声明键控的 `'conversation.chat.toolview'` 空位（Session scope；key 空间在运行时开放）；其渲染点逐行通过 `entryKey: toolName` 分发，并以 `GenericToolCard` 作为调用点 `fallback`。owner 载荷是统一的 `ToolRowOwnerProps`（`callId`／`toolName`／`block`／`openDetails`），`ToolRowProps` 则预先将其与 Session 标准工具包组合。注册方只是普通插件：`ctx.slots.register({ name: 'conversation.chat.toolview', key: '<tool>', inject? }, Row)`，以 `inject: ['slots', 'conversation']` 作为加载顺序 seam（apply 在聊天注册后挂载 ConversationService，因此服务存在即可保证 slot 已声明）；Session 区分在组件内部完成（`useSessions` 读取 `parentId`，bash 示例是第三方姿态的范例）。Trajectory/waterfall 工具视图 slot 共享此形状，并随各自的渲染点落地（RendersCheck 会拒绝没有任何渲染方的声明）。
 

packages/client/ui-conversation/src/client/chat/GenericToolCard.tsx

@@ -30,6 +30,7 @@ export function GenericToolCard({ toolName, block, openDetails }: ToolRowOwnerPr
   return (
     <ToolRow
       variant={model.variant}
+      toolName={toolName}
       icon={VARIANT_ICONS[model.variant]}
       title={model.title}
       summary={model.summary}

packages/client/ui-conversation/src/client/chat/ToolRow.module.css

@@ -42,6 +42,21 @@
   color: var(--dsw-alias-label-secondary);
 }
 
+/* Cordis lifecycle tools retain their generic row mechanics while carrying a
+   shared product accent and tool-owned action title. */
+.root[data-tool^='cordis_'] .leading,
+.root[data-tool^='cordis_'] .title {
+  color: var(--dsw-alias-state-business-primary);
+}
+
+.root[data-tool^='cordis_'] .title {
+  font-weight: 500;
+}
+
+.root[data-tool^='cordis_'] .sep {
+  background: var(--dsw-alias-state-business-primary);
+}
+
 button.leading {
   cursor: pointer;
 }

packages/client/ui-conversation/src/client/chat/ToolRow.tsx

@@ -13,6 +13,8 @@ import css from './ToolRow.module.css'
 
 export interface ToolRowProps {
   variant: ToolRowVariant
+  /** Wire tool name for tool-owned styling layered over the generic variant. */
+  toolName?: string | undefined
   /** Leading 16px tool icon, shown while collapsed and not running/failed. */
   icon: ReactNode
   title: string
@@ -39,6 +41,7 @@ function leadingFor(state: ToolRowState, icon: ReactNode): ReactNode {
 
 export function ToolRow({
   variant,
+  toolName,
   icon,
   title,
   summary,
@@ -64,7 +67,7 @@ export function ToolRow({
     toggleExpand()
   }
   return (
-    <div className={css.root} data-variant={variant} data-state={state}>
+    <div className={css.root} data-variant={variant} data-tool={toolName} data-state={state}>
       <div
         className={css.row}
         data-clickable={rowExpands || onOpenDetails !== undefined || undefined}

packages/client/ui-conversation/src/client/contract/tool-call-model.ts

@@ -36,6 +36,16 @@ const TOOL_VARIANTS: Record<string, ToolRowVariant> = {
   write: 'write',
   edit: 'edit',
   run_code: 'code',
+  cordis_inspect: 'read',
+  cordis_mount: 'code',
+  cordis_unmount: 'others',
+}
+
+/** Tool-owned titles that refine a generic row variant without replacing it. */
+const TOOL_TITLES: Record<string, string> = {
+  cordis_inspect: 'Inspect',
+  cordis_mount: 'Mount temporary Plugin',
+  cordis_unmount: 'Unmount temporary Plugin',
 }
 
 /**
@@ -130,12 +140,15 @@ export function toolRowModel(toolName: string, block: ToolCallBlock): ToolRowMod
     : block.error?.code === 'interrupted' ? 'stopped'
       : block.isError ? 'error' : 'ok'
   const base = argsRaw === '' ? block.callId : deriveSummary(variant, argsRaw)
+  const toolTitle = TOOL_TITLES[toolName]
   // Others keeps the static "Tool call" title (figma literal); the real tool
-  // name rides the mutable summary slot so no information is lost.
-  const summary = variant === 'others' && toolName !== '' ? `${toolName} · ${base}` : base
+  // name rides the mutable summary slot unless the tool owns a specific title.
+  const summary = variant === 'others' && toolName !== '' && toolTitle === undefined
+    ? `${toolName} · ${base}`
+    : base
   return {
     variant,
-    title: VARIANT_TITLES[variant],
+    title: toolTitle ?? VARIANT_TITLES[variant],
     summary,
     body: deriveBody(variant, argsRaw),
     state,

packages/client/ui-conversation/tests/chat-code-subcalls.spec.tsx

@@ -167,6 +167,28 @@ describe('run_code sub-calls through the real chat machinery', () => {
     expect(view.getByText('Tool call')).toBeTruthy()
   })
 
+  it('renders Cordis sub-calls with lifecycle titles over the generic variants', async () => {
+    const parent = 'call-cordis'
+    const code = 'return { name: "audit", apply(ctx) {} }'
+    const dispatches = new Map([[parent, [
+      subCall(11, parent, 1, 'cordis_inspect', { what: 'temporary' }, '## Temporary Plugins'),
+      subCall(12, parent, 2, 'cordis_mount', { code }, 'Temporary Plugin dyn-2 is running'),
+      subCall(13, parent, 3, 'cordis_unmount', { id: 'dyn-2' }, 'Temporary Plugin dyn-2 was unmounted and removed.'),
+    ]]])
+    const b = await bench(snapshotWith([codeResult(10, parent)], dispatches))
+    const view = mountApp(b.slots)
+    const nest = view.container.querySelector('[data-subcalls]')!
+
+    expect(nest.querySelector('[data-tool="cordis_inspect"]')?.textContent).toContain('Inspect')
+    const mounted = nest.querySelector('[data-variant="code"]')
+    expect(mounted?.textContent).toContain(`Mount temporary Plugin${code}`)
+    expect(nest.querySelector('[data-tool="cordis_unmount"]')?.textContent)
+      .toContain('Unmount temporary Plugindyn-2')
+
+    fireEvent.click(mounted!.querySelector('button[aria-expanded]')!)
+    expect(mounted!.querySelector('pre.shiki')?.textContent).toBe(code)
+  })
+
   it('expanding the code row reveals the program body verbatim (shiki-tokenized)', async () => {
     const parent = 'call-64'
     const b = await bench(snapshotWith([codeResult(10, parent)], new Map()))

packages/client/ui-conversation/tests/chat-tool-row.spec.tsx

@@ -31,6 +31,9 @@ describe('tool-call-model', () => {
     expect(classifyTool('grep')).toBe('search')
     expect(classifyTool('write')).toBe('write')
     expect(classifyTool('edit')).toBe('edit')
+    expect(classifyTool('cordis_inspect')).toBe('read')
+    expect(classifyTool('cordis_mount')).toBe('code')
+    expect(classifyTool('cordis_unmount')).toBe('others')
     expect(classifyTool('todo_write')).toBe('others')
   })
 
@@ -67,6 +70,33 @@ describe('tool-call-model', () => {
     expect(toolRowModel('bash', running({ argsRaw: '' })).body).toBeNull()
     expect(toolRowModel('bash', result({ call: null })).body).toBeNull()
   })
+
+  it('gives Cordis lifecycle tools action titles over their generic variants', () => {
+    expect(toolRowModel('cordis_inspect', running({
+      name: 'cordis_inspect',
+      argsRaw: '{"what":"api","name":"tools"}',
+    }))).toMatchObject({
+      variant: 'read',
+      title: 'Inspect',
+      summary: 'api',
+    })
+    expect(toolRowModel('cordis_mount', running({
+      name: 'cordis_mount',
+      argsRaw: '{"code":"return { name: \\"audit\\", apply(ctx) {} }"}',
+    }))).toMatchObject({
+      variant: 'code',
+      title: 'Mount temporary Plugin',
+      summary: 'return { name: "audit", apply(ctx) {} }',
+      body: 'return { name: "audit", apply(ctx) {} }',
+    })
+    expect(toolRowModel('cordis_unmount', result({
+      call: { name: 'cordis_unmount', argsRaw: '{"id":"dyn-2"}' },
+    }))).toMatchObject({
+      variant: 'others',
+      title: 'Unmount temporary Plugin',
+      summary: 'dyn-2',
+    })
+  })
 })
 
 describe('ToolRow', () => {

packages/client/ui-conversation/tests/chat-toolview-slot.spec.tsx

@@ -12,7 +12,7 @@
 
 import { Context } from 'cordis'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { act, cleanup, render } from '@testing-library/react'
+import { act, cleanup, fireEvent, render } from '@testing-library/react'
 import { createSnapshotStore, SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
 import type {
   ConversationSnapshot, SessionId, SessionListState, ToolResultNode, WorkspaceListState,
@@ -166,6 +166,25 @@ describe('keyed toolview hole through the real machinery', () => {
     expect(view.getByText('Tool call')).toBeTruthy()
   })
 
+  it('renders top-level Cordis calls with lifecycle titles over the generic variants', async () => {
+    const code = 'return { name: "audit", apply(ctx) {} }'
+    const b = await bench([
+      toolResult(3, 'cordis-1', 'cordis_inspect', '{"what":"api","name":"tools"}'),
+      toolResult(4, 'cordis-2', 'cordis_mount', JSON.stringify({ code })),
+      toolResult(5, 'cordis-3', 'cordis_unmount', '{"id":"dyn-2"}'),
+    ])
+    const view = mountApp(b.slots)
+
+    expect(view.container.querySelector('[data-tool="cordis_inspect"]')?.textContent).toContain('Inspect')
+    const mounted = view.container.querySelector('[data-variant="code"]')
+    expect(mounted?.textContent).toContain(`Mount temporary Plugin${code}`)
+    expect(view.container.querySelector('[data-tool="cordis_unmount"]')?.textContent)
+      .toContain('Unmount temporary Plugindyn-2')
+
+    fireEvent.click(mounted!.querySelector('button[aria-expanded]')!)
+    expect(mounted!.querySelector('pre.shiki')?.textContent).toBe(code)
+  })
+
   it('row clicks travel owner openDetails → chat inject → layout orchestration', async () => {
     const b = await bench([toolResult(3, 'c1', 'bash')])
     const view = mountApp(b.slots)

packages/compact/compact-basic/src/index.ts

@@ -173,6 +173,8 @@ export class BasicCompactService extends CompactService {
       _step,
       _error,
       failure,
+      _priorFailures,
+      _retryPolicy,
       signal,
       next,
     ) => {

packages/compact/compact-basic/tests/compact-basic.spec.ts

@@ -1296,7 +1296,7 @@ describe('automatic listener and loader composition', () => {
     const failure: LlmFailure = { message: error.message, code: error.code ?? 'UNKNOWN' }
     const turn = owner.session.events.findLast(event => event.type === 'turn/start')?.data.turn ?? 1
     return agentEvents(ctx, owner).waterfall(
-      'agent/request-error', turn, 1, error, failure, signal, next,
+      'agent/request-error', turn, 1, error, failure, [], undefined, signal, next,
     ).then(action => action?.kind === 'retry')
   }
 

packages/compact/compact-basic/tests/compact-loop-repro.spec.ts

@@ -1,8 +1,8 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { toolPairingBalancedAfter, toolPairingBalancedBefore } from '@deepseek-ai/dsh-compact'
-import { CONTEXT_WINDOW_EXCEEDED_CODE, LlmError } from '@deepseek-ai/dsh-llm'
-import type { ContentBlock, GenerateOptions, LlmResolvedModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm'
+import { CONTEXT_WINDOW_EXCEEDED_CODE, LlmError, resolveRetryPolicy } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock, GenerateOptions, LlmResolvedModelInfo, ResolvedRetryPolicy, StreamChunk } from '@deepseek-ai/dsh-llm'
 import { CallId, LlmAdapter } from '@deepseek-ai/dsh-llm'
 import { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
 import type { Agent } from '@deepseek-ai/dsh-agent'
@@ -73,6 +73,11 @@ class StepwiseToolAdapter extends LlmAdapter {
 class OverflowRecoveryAdapter extends LlmAdapter {
   readonly conversationRequests: GenerateOptions[] = []
   readonly summaryRequests: GenerateOptions[] = []
+  private readonly retryPolicy = resolveRetryPolicy({
+    mode: 'normal',
+    maxRetries: 1,
+    backoff: { initialDelayMs: 1, maxDelayMs: 1, jitterRatio: 0 },
+  }, 'compaction test provider retryPolicy')
 
   constructor(
     private readonly delivery: 'thrown' | 'in-band',
@@ -90,6 +95,10 @@ class OverflowRecoveryAdapter extends LlmAdapter {
     })
   }
 
+  override providerRetryPolicy(_provider: string): ResolvedRetryPolicy {
+    return this.retryPolicy
+  }
+
   override async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
     // The cache-reusing summarizer replays the conversation prefix and marks
     // its call only by the compaction instruction in the trailing user message.
@@ -375,12 +384,7 @@ describe('context-overflow recovery across the real loop and compact-basic', ()
     const adapter = new OverflowRecoveryAdapter('thrown', true)
     await mountAgentLoopTestDependencies(ctx)
     await mountInvariants(ctx)
-    await ctx.plugin(LlmRetry, {
-      maxTransientRetries: 1,
-      initialDelayMs: 1,
-      maxDelayMs: 1,
-      jitterRatio: 0,
-    })
+    await ctx.plugin(LlmRetry)
     await ctx.plugin(AgentLoop, { agents: [] })
     await ctx.plugin(TokenMeterService)
     ctx.llm.registerAdapter(['mock'], adapter)

packages/cordis/README.i18n.yaml

@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # 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
-README.md: b3a70b07c57ae1a2e3dd975a64c840d90c5a84ad
-README.zh.md: 5832310cfe14a299ac5998a28bcbbb500caf86b5
+#   pnpm run verify-translation-pairing --write packages/cordis/README.md
+README.md: a47b9ba20789bb6b9a36b1af9b3942b90e61b365
+README.zh.md: cc91e68f0dfa9fb343c332eba2579c2a077beb64

packages/cordis/README.md

@@ -6,4 +6,4 @@ Model-facing tools over the live cordis runtime the agent itself runs inside: in
 
 | Package | Role | ctx key |
 |---|---|---|
-| [`tool-cordis/`](tool-cordis/README.md) | The `cordis_inspect` / `cordis_mount` / `cordis_unmount` tools: read the runtime, evaluate model-written plugin code in a `node:vm` sandbox, and manage the dynamic mounts under one group fiber | registers on `ctx.tools` |
+| [`tool-cordis/`](tool-cordis/README.md) | The `cordis_inspect` / `cordis_mount` / `cordis_unmount` tools: read the current-process runtime and manage in-memory temporary Plugins under one owned group fiber | registers on `ctx.tools` |

packages/cordis/README.zh.md

@@ -2,8 +2,8 @@
 
 [English](README.md) | 中文
 
-面向模型、作用于 agent（智能体）自身所在实时 Cordis 运行时的工具：检查已加载插件与服务接口、挂载模型编写的插件，以及再次释放这些插件。设计归档见[工具集 Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)。
+面向模型、作用于 agent（智能体）所在实时 Cordis 运行时的工具：检查当前 DSH 进程，并挂载或卸载仅存于内存的临时 Plugin。设计归档见[工具集 Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)。
 
 | 包（package） | 角色 | ctx 键 |
 |---|---|---|
-| [`tool-cordis/`](tool-cordis/README.md) | `cordis_inspect`／`cordis_mount`／`cordis_unmount` 工具：读取运行时、在 `node:vm` 沙箱中求值模型编写的插件代码，并在同一个分组 fiber 下管理动态挂载 | 注册到 `ctx.tools` |
+| [`tool-cordis/`](tool-cordis/README.md) | `cordis_inspect`／`cordis_mount`／`cordis_unmount` 工具：读取当前进程运行时，并在一个自有分组 fiber 下管理临时 Plugin | 注册到 `ctx.tools` |

packages/cordis/tool-cordis/README.i18n.yaml

@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # 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
-README.md: 022e25decad650e03aa621cfa2b3f33ccc8d9743
-README.zh.md: 99a79209a2a895ee8e11e3b7345a305da514ac1e
+#   pnpm run verify-translation-pairing --write packages/cordis/tool-cordis/README.md
+README.md: 5b58e665dae95aea0d0ad094238fef5d3dc0fb97
+README.zh.md: 11e5be11dca84247b19888fefa7d70e5d74da174

packages/cordis/tool-cordis/README.md

@@ -2,17 +2,19 @@
 
 English | [中文](README.zh.md)
 
-The self-referential cordis toolset: three model-facing tools over the live runtime the agent runs inside. Design home — sandbox semantics, mount lifecycle, cross-mount composition, the generated API catalog, standing decisions: [the toolset Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md).
+The self-referential Cordis toolset: three model-facing tools over the live runtime in the current DSH process. Design home — sandbox semantics, temporary-plugin lifecycle and composition, the generated API catalog, standing decisions: [the toolset Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md).
 
 ## What it does
 
-- `cordis_inspect` — read-only report over the runtime: services, the loaded-plugin list, registered tools, the dynamic-mount table, and the catalog-backed `api` / `events` references. An exact `name` with `what: "api"` or `what: "events"` narrows the report and adds the original source JSDoc.
-- `cordis_mount` — evaluates model-written JavaScript (the body of an async function) in a `node:vm` sandbox; the code must `return` a cordis plugin, which is mounted under the `cordis-dynamic` group fiber and tracked as `dyn-<n>`.
-- `cordis_unmount` — disposes one mount by id, returning only after quiescence.
+- `cordis_inspect` — read-only report over the current process: services, all live plugin fibers, registered tools, the `cordis_mount` temporary-Plugin subset, and the catalog-backed `api` / `events` references. An exact `name` with `what: "api"` or `what: "events"` narrows the report and adds the original source JSDoc.
+- `cordis_mount` — evaluates model-written JavaScript now and saves it nowhere; the code must return an in-memory temporary Plugin tracked as `dyn-<n>`.
+- `cordis_unmount` — unmounts one `dyn-<n>` temporary Plugin and returns only after its owned effects reach quiescence. It cannot remove Loader, configured, or installed Plugins.
 
 Exact model-facing schemas: [the generated tool catalog](../../../docs/tool-catalog.md).
 
-Canonical successes are the inspection string, mount `{ id, pluginName, state, provides, waitingFor }`, and unmount `{ id, pluginName }`. Native renderers preserve the existing prose, so programs can use `mounted.id` while ordinary function calling still sees `mounted dyn-1 (...)`.
+Canonical successes are the inspection string, mount `{ id, pluginName, state, provides, waitingFor }`, and unmount `{ id, pluginName }`. Native rendering says whether the temporary Plugin is running or pending and that it remains available until unmounted or DSH restarts; unmount confirms that it was removed.
+
+Temporary Plugins live only in the shared DSH process memory. They remain active across later turns and may affect other sessions in that process, but disappear after `cordis_unmount`, toolset unload, or DSH restart. They create no Plugin file, install no package, change no `cordis.yml` or personal/project configuration, do not survive restart, and cannot be promoted automatically. To keep an experiment, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow.
 
 ## Trust stance
 
@@ -22,7 +24,7 @@ The sandbox isolates globals but is not a security boundary. Node globals are ab
 
 | Field | Default | Meaning |
 |---|---|---|
-| `vmTimeoutMs` | `5000` | Bound on the SYNCHRONOUS portion of mount-code evaluation; an async body escapes it |
+| `vmTimeoutMs` | `5000` | Bound on the SYNCHRONOUS portion of temporary-Plugin code evaluation; an async body escapes it |
 
 ## The generated API catalog
 
@@ -30,7 +32,7 @@ The sandbox isolates globals but is not a security boundary. Node globals are ab
 
 ## Rendering
 
-All three tools render `generic` cards (`read` / `execute` / `delete`); `cordis_mount` carries the mount code as `rawInput`. Presenters are pure functions of the args; results keep the default text rendering.
+All three tools render `generic` cards (`read` / `execute` / `delete`); `cordis_mount` carries the temporary-Plugin code as `rawInput`. Presenters are pure functions of the args; results keep the default text rendering.
 
 ## Export shape
 
@@ -56,7 +58,7 @@ Prefix-stable while this tool view is unchanged. Scoping or plugin lifecycle cha
 
 #### What the model sees
 
-Inspect joins selected sections exactly as `## <section>` then a newline and the data-dependent body, with one blank line between sections. Its broad API/event reports omit JSDoc; `name` with `what: "api"` or `what: "events"` returns one exact target with its original JSDoc. Mount returns `mounted <id> (plugin "<name>", state: <state>)`, optionally inserting ` — waiting for service(s): <names> (activates when provided)` before the closing parenthesis. Unmount returns `unmounted <id> (plugin "<name>")`; an unknown id becomes `Error: no dynamic plugin with id "<id>" (list mounts with cordis_inspect what:"dynamic")`. The submitted mount program remains in the assistant tool-call history.
+Inspect joins selected sections exactly as `## <section>` then a newline and the data-dependent body, with one blank line between sections; `what: "temporary"` uses the `## Temporary Plugins` heading. Each temporary-Plugin row reports running/pending state, provided and awaited services, and its lifetime until unmounted or DSH restart. The empty state explains that `cordis_mount` Plugins disappear on restart. Broad API/event reports omit JSDoc; `name` with `what: "api"` or `what: "events"` returns one exact target with its original JSDoc. Mount returns `Temporary Plugin <id> is running (...)` or `Temporary Plugin <id> is pending (...)`; unmount returns `Temporary Plugin <id> was unmounted and removed.` The submitted program remains in assistant tool-call history.
 
 #### Token effect
 
@@ -66,19 +68,19 @@ Inspect output and mount code are data-dependent and resent until compaction; li
 
 Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
 
-### Later requests after a mount
+### Later requests after cordis_mount
 
 #### What the model sees
 
-A mounted plugin may register tools, prompt contributions, or listeners that change later requests for the scopes it targets; unmount removes those contributions after quiescence.
+A temporary Plugin may register tools, prompt contributions, or listeners that change later requests for the scopes it targets; `cordis_unmount` removes those contributions after quiescence.
 
 #### Token effect
 
-Indirect token impact equals the mounted plugin's contributions and lasts only for the mount lifetime.
+Indirect token impact equals the temporary Plugin's contributions and lasts only for its process-local lifetime.
 
 #### KV Cache effect
 
-Mounting or unmounting a prompt or tool contribution changes later request prefixes and may invalidate reuse from the first changed contribution; an unchanged mount set remains prefix-stable.
+Mounting or unmounting a prompt or tool contribution changes later request prefixes and may invalidate reuse from the first changed contribution; an unchanged temporary-Plugin set remains prefix-stable.
 
 ## Known Limitations and Deferred Work
 

packages/cordis/tool-cordis/README.zh.md

@@ -2,17 +2,19 @@
 
 [English](README.md) | 中文
 
-自引用 cordis 工具集：三个面向模型的工具，操作 agent 所处的存活运行时。设计归属（沙箱语义、挂载生命周期、跨挂载组合、生成的 API 目录、既定决策）见[工具集 Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)。
+自引用 Cordis 工具集：三个面向模型的工具，操作当前 DSH 进程中的存活运行时。设计归属（沙箱语义、临时 Plugin 生命周期与组合、生成的 API 目录、既定决策）见[工具集 Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)。
 
 ## 功能
 
-- `cordis_inspect`：运行时的只读报告，包括服务、已加载插件列表、已注册工具、动态挂载表，以及目录支持的 `api`／`events` 参考。精确的 `name` 配合 `what: "api"` 或 `what: "events"` 可缩窄报告，并附上原始源代码 JSDoc。
-- `cordis_mount`：在 `node:vm` 沙箱中求值模型编写的 JavaScript（一个 async 函数的主体）；代码必须 `return` 一个 cordis 插件，系统将其挂载在 `cordis-dynamic` 分组 fiber 下，并以 `dyn-<n>` 跟踪。
-- `cordis_unmount`：按 id 释放一项挂载，只在完全停稳后返回。
+- `cordis_inspect`：当前进程运行时的只读报告，包括服务、全部存活 Plugin fiber、已注册工具、`cordis_mount` 临时 Plugin 子集，以及目录支持的 `api`／`events` 参考。精确的 `name` 配合 `what: "api"` 或 `what: "events"` 可缩窄报告，并附上原始源代码 JSDoc。
+- `cordis_mount`：立即求值模型编写的 JavaScript 且不保存到任何位置；代码必须返回一个以 `dyn-<n>` 跟踪、仅存于内存的临时 Plugin。
+- `cordis_unmount`：卸载一个 `dyn-<n>` 临时 Plugin，并只在其自有效果完全停稳后返回；它不能删除 Loader、配置或已安装的 Plugin。
 
 精确的面向模型 schema 见[生成的工具目录](../../../docs/tool-catalog.md)。
 
-规范成功值分别为检查字符串、挂载 `{ id, pluginName, state, provides, waitingFor }`，以及卸载 `{ id, pluginName }`。原生 renderer 保留现有文本，因此程序可以使用 `mounted.id`，普通 Function Calling 仍会看到 `mounted dyn-1 (...)`。
+规范成功值分别为检查字符串、挂载 `{ id, pluginName, state, provides, waitingFor }`，以及卸载 `{ id, pluginName }`。原生 renderer 会说明临时 Plugin 正在运行还是等待中，并说明它可用至被卸载或 DSH 重启；卸载结果确认它已移除。
+
+临时 Plugin 只存在于共享 DSH 进程内存中。它可跨后续 turn 保持活跃，也可能影响同一进程中的其他 session，但会在 `cordis_unmount`、工具集卸载或 DSH 重启后消失。它不会创建 Plugin 文件、安装 package、修改 `cordis.yml` 或个人／项目配置、跨重启存续，也不能自动转为正式 Plugin。若要保留实验结果，应让 Agent 通过常规开发流程实现普通的本地、项目或仓库 Plugin。
 
 ## 信任立场
 
@@ -22,7 +24,7 @@
 
 | 字段 | 默认值 | 含义 |
 |---|---|---|
-| `vmTimeoutMs` | `5000` | 挂载代码求值中同步部分的边界；async 主体可逃出该边界 |
+| `vmTimeoutMs` | `5000` | 临时 Plugin 代码求值中同步部分的边界；async 主体可逃出该边界 |
 
 ## 生成的 API 目录
 
@@ -30,7 +32,7 @@
 
 ## 渲染
 
-三个工具都渲染 `generic` 卡片（`read`／`execute`／`delete`）；`cordis_mount` 以 `rawInput` 携带挂载代码。presenter 是 args 的纯函数；结果保留默认文本渲染。
+三个工具都渲染 `generic` 卡片（`read`／`execute`／`delete`）；`cordis_mount` 以 `rawInput` 携带临时 Plugin 代码。presenter 是 args 的纯函数；结果保留默认文本渲染。
 
 ## 导出形状
 
@@ -56,7 +58,7 @@ Namespace 插件：命名导出 `name`／`inject`／`Config`／`apply`，无默
 
 #### 模型看到的内容
 
-检查会精确地用 `## <section>` 加换行及数据相关主体来拼接选中区段，各区段之间留一个空行。宽泛的 API／事件报告省略 JSDoc；`name` 配合 `what: "api"` 或 `what: "events"` 返回一个精确目标及其原始 JSDoc。挂载返回 `mounted <id> (plugin "<name>", state: <state>)`，并可在右括号前插入 ` — waiting for service(s): <names> (activates when provided)`。卸载返回 `unmounted <id> (plugin "<name>")`；未知 id 会变成 `Error: no dynamic plugin with id "<id>" (list mounts with cordis_inspect what:"dynamic")`。提交的挂载程序保留在 assistant 工具调用历史中。
+检查会精确地用 `## <section>` 加换行及数据相关主体来拼接选中区段，各区段之间留一个空行；`what: "temporary"` 使用 `## Temporary Plugins` 标题。每个临时 Plugin 行都会报告 running／pending 状态、提供与等待的服务，以及持续至卸载或 DSH 重启的生命周期；空状态说明 `cordis_mount` Plugin 会在重启时消失。宽泛的 API／事件报告省略 JSDoc；`name` 配合 `what: "api"` 或 `what: "events"` 返回一个精确目标及其原始 JSDoc。挂载返回 `Temporary Plugin <id> is running (...)` 或 `Temporary Plugin <id> is pending (...)`；卸载返回 `Temporary Plugin <id> was unmounted and removed.`。提交的程序保留在 assistant 工具调用历史中。
 
 #### Token 影响
 
@@ -66,19 +68,19 @@ Namespace 插件：命名导出 `name`／`inject`／`Config`／`apply`，无默
 
 仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 配置项失效。
 
-### 挂载后的后续请求
+### cordis_mount 后的后续请求
 
 #### 模型看到的内容
 
-已挂载插件可以注册工具、提示词贡献或监听器，改变其目标 scope 的后续请求；卸载会在完全停稳后移除这些贡献。
+临时 Plugin 可以注册工具、提示词贡献或监听器，改变其目标 scope 的后续请求；`cordis_unmount` 会在完全停稳后移除这些贡献。
 
 #### Token 影响
 
-间接 token 影响等于已挂载插件的贡献，且只在挂载生命周期内持续。
+间接 token 影响等于临时 Plugin 的贡献，且只在其进程内生命周期内持续。
 
 #### KV Cache 影响
 
-挂载或卸载提示词／工具贡献会改变后续请求前缀，并可能使从第一个变化的贡献起的复用失效；挂载集合不变时，前缀保持稳定。
+挂载或卸载提示词／工具贡献会改变后续请求前缀，并可能使从第一个变化的贡献起的复用失效；临时 Plugin 集合不变时，前缀保持稳定。
 
 ## 已知限制与暂缓事项
 

packages/cordis/tool-cordis/src/api-catalog.ts

@@ -376,6 +376,10 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         signature: 'listProviders(): LlmProviderInfo[]',
         jsDoc: '/**\n * Describe provider routes with a registered adapter.\n * @returns detached provider metadata in registration order.\n */',
       },
+      {
+        signature: 'providerRetryPolicy(provider: string): ResolvedRetryPolicy',
+        jsDoc: '/**\n * Resolve the retry policy captured when one provider route was registered.\n * @param provider - registered provider route to inspect.\n * @returns the provider-owned policy, with normal defaults already resolved.\n */',
+      },
       {
         signature: 'async listModels(provider: string): Promise<LlmModelInfo[]>',
         jsDoc: '/**\n * Discover models advertised by one registered provider. Catalog membership\n * is advisory and never changes routing or request validation.\n * @param provider - registered provider route to inspect.\n * @returns detached model metadata in adapter-preferred order.\n */',
@@ -430,7 +434,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'set(agent: Agent, active: boolean): void',
-        jsDoc: '/**\n * Select whether plan mode should be active from the next turn boundary.\n * Repeated selection of the current or already-pending state is a no-op.\n *\n * @param agent The agent to switch.\n * @param active Whether plan mode should be active.\n */',
+        jsDoc: '/**\n * Select whether plan mode should be active from the next request boundary.\n * Repeated selection of the current or already-pending state is a no-op.\n *\n * @param agent The agent to switch.\n * @param active Whether plan mode should be active.\n */',
       },
     ],
   },
@@ -1065,8 +1069,8 @@ export const EVENT_API: readonly EventApiEntry[] = [
   {
     name: 'agent/request-error',
     mode: 'waterfall',
-    signature: '\'agent/request-error\'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: RequestError, failure: LlmFailure, signal: AbortSignal, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>',
-    jsDoc: '/**\n * Handle a model-request failure after its failed step has closed but\n * before the failed turn closes. A listener returns `{ kind: \'retry\' }`\n * without calling `next()` when it owns the error, or calls `next()` to\n * delegate. The default `undefined` leaves the failure terminal.\n * @param agent - the agent whose request failed.\n * @param turn - the open turn number.\n * @param step - the failed step number.\n * @param error - the original model-request failure.\n * @param failure - serializable facts normalized at the final adapter boundary.\n * @param signal - the turn abort signal.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode waterfall\n */',
+    signature: '\'agent/request-error\'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: RequestError, failure: LlmFailure, priorFailures: readonly LlmFailure[], retryPolicy: ResolvedRetryPolicy | undefined, signal: AbortSignal, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>',
+    jsDoc: '/**\n * Handle a model-request failure after its failed step has closed but\n * before the failed turn closes. A listener returns `{ kind: \'retry\' }`\n * without calling `next()` when it owns the error, or calls `next()` to\n * delegate. The default `undefined` leaves the failure terminal.\n * @param agent - the agent whose request failed.\n * @param turn - the open turn number.\n * @param step - the failed step number.\n * @param error - the original model-request failure.\n * @param failure - serializable facts normalized at the final adapter boundary.\n * @param priorFailures - immutable failures that already authorized another\n * retry turn in this consecutive sequence.\n * @param retryPolicy - immutable policy of the adapter registration that served\n * the failed request, or `undefined` if no final adapter served it.\n * @param signal - the turn abort signal.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode waterfall\n */',
     summary: 'Handle a model-request failure after its failed step has closed but before the failed turn closes.',
   },
   {
@@ -1751,7 +1755,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'LlmAdapter',
-    declaration: 'export abstract class LlmAdapter {\n    providerInfo(provider: string): LlmProviderInfo;\n    listModels(_provider: string): Promise<readonly LlmModelInfo[]>;\n    resolveModel(provider: string, model: string, _signal?: AbortSignal): Promise<LlmResolvedModelInfo>;\n    abstract stream(options: GenerateOptions): AsyncIterable<StreamChunk>;\n}',
+    declaration: 'export abstract class LlmAdapter {\n    providerInfo(provider: string): LlmProviderInfo;\n    providerRetryPolicy(_provider: string): ResolvedRetryPolicy | undefined;\n    listModels(_provider: string): Promise<readonly LlmModelInfo[]>;\n    resolveModel(provider: string, model: string, _signal?: AbortSignal): Promise<LlmResolvedModelInfo>;\n    abstract stream(options: GenerateOptions): AsyncIterable<StreamChunk>;\n}',
   },
   {
     name: 'LlmCallConfig',
@@ -1929,6 +1933,22 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'RequestHeaderReason',
     declaration: 'export type RequestHeaderReason = \'initial\' | \'resume\' | \'change\';',
   },
+  {
+    name: 'ResolvedAlwaysRetryPolicy',
+    declaration: 'export interface ResolvedAlwaysRetryPolicy extends ResolvedRetryBackoff {\n    readonly mode: \'always\';\n}',
+  },
+  {
+    name: 'ResolvedNormalRetryPolicy',
+    declaration: 'export interface ResolvedNormalRetryPolicy extends ResolvedRetryBackoff {\n    readonly mode: \'normal\';\n    readonly maxRetries: number;\n    readonly retryableCodes: readonly string[];\n}',
+  },
+  {
+    name: 'ResolvedRetryBackoff',
+    declaration: 'export interface ResolvedRetryBackoff {\n    readonly initialDelayMs: number;\n    readonly maxDelayMs: number;\n    readonly jitterRatio: number;\n}',
+  },
+  {
+    name: 'ResolvedRetryPolicy',
+    declaration: 'export type ResolvedRetryPolicy = ResolvedNormalRetryPolicy | ResolvedAlwaysRetryPolicy;',
+  },
   {
     name: 'ResumeAgentOptions',
     declaration: 'export interface ResumeAgentOptions {\n    readonly resumeSessionId: SessionId;\n    readonly agentOptions?: AgentOptions;\n    readonly signal?: AbortSignal;\n    readonly setup?: (agentCtx: Context) => Promise<void> | void;\n}',
@@ -2199,7 +2219,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SkillSource',
-    declaration: 'export type SkillSource = \'project-dsh\' | \'project-agents\' | \'runtime\' | \'user-dsh\' | \'user-agents\' | \'custom\' | (string & {});',
+    declaration: 'export type SkillSource = \'project-dsh\' | \'project-agents\' | \'runtime\' | \'user-dsh\' | \'user-agents\' | \'custom\' | \'bundled\' | (string & {});',
   },
   {
     name: 'SkillSummary',
@@ -2485,58 +2505,6 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'ToolSchema',
     declaration: 'export interface ToolSchema {\n    name: string;\n    description: string;\n    parameters: Record<string, unknown>;\n}',
   },
-  {
-    name: 'TuiComponent',
-    declaration: 'export interface TuiComponent {\n    render(width: number): string[];\n    handleInput?(data: string): void;\n    wantsKeyRelease?: boolean;\n    invalidate(): void;\n}',
-  },
-  {
-    name: 'TuiFocusable',
-    declaration: 'export interface TuiFocusable {\n    focused: boolean;\n}',
-  },
-  {
-    name: 'TuiOverlayAnchor',
-    declaration: 'export type TuiOverlayAnchor = \'center\' | \'top-left\' | \'top-right\' | \'bottom-left\' | \'bottom-right\' | \'top-center\' | \'bottom-center\' | \'left-center\' | \'right-center\';',
-  },
-  {
-    name: 'TuiOverlayCloseReason',
-    declaration: 'export type TuiOverlayCloseReason = \'closed\' | \'aborted\' | \'owner-disposed\' | \'tui-disposed\' | \'error\';',
-  },
-  {
-    name: 'TuiOverlayHost',
-    declaration: 'export interface TuiOverlayHost {\n    readonly signal: AbortSignal;\n    readonly viewport: TuiViewport;\n    readonly theme: TuiTheme;\n    display(value: string): string;\n    invalidate(): void;\n    close(): void;\n}',
-  },
-  {
-    name: 'TuiOverlayMargin',
-    declaration: 'export interface TuiOverlayMargin {\n    readonly top?: number;\n    readonly right?: number;\n    readonly bottom?: number;\n    readonly left?: number;\n}',
-  },
-  {
-    name: 'TuiOverlayOptions',
-    declaration: 'export interface TuiOverlayOptions {\n    readonly width?: number | `${number}%`;\n    readonly minWidth?: number;\n    readonly maxHeight?: number | `${number}%`;\n    readonly anchor?: TuiOverlayAnchor;\n    readonly margin?: number | TuiOverlayMargin;\n}',
-  },
-  {
-    name: 'TuiOverlayOutcome',
-    declaration: 'export type TuiOverlayOutcome = {\n    readonly reason: Exclude<TuiOverlayCloseReason, \'error\'>;\n} | {\n    readonly reason: \'error\';\n    readonly error: unknown;\n};',
-  },
-  {
-    name: 'TuiOverlayRequest',
-    declaration: 'export interface TuiOverlayRequest {\n    readonly create: (host: TuiOverlayHost) => TuiComponent & Partial<TuiFocusable>;\n    readonly options?: TuiOverlayOptions;\n    readonly signal?: AbortSignal;\n}',
-  },
-  {
-    name: 'TuiOverlaySession',
-    declaration: 'export interface TuiOverlaySession {\n    readonly state: TuiOverlayState;\n    readonly closed: Promise<TuiOverlayOutcome>;\n    close(): Promise<TuiOverlayOutcome>;\n}',
-  },
-  {
-    name: 'TuiOverlayState',
-    declaration: 'export type TuiOverlayState = \'queued\' | \'active\' | \'closed\';',
-  },
-  {
-    name: 'TuiTheme',
-    declaration: 'export interface TuiTheme {\n    readonly text: (value: string) => string;\n    readonly muted: (value: string) => string;\n    readonly dim: (value: string) => string;\n    readonly accent: (value: string) => string;\n    readonly success: (value: string) => string;\n    readonly warning: (value: string) => string;\n    readonly error: (value: string) => string;\n    readonly bold: (value: string) => string;\n}',
-  },
-  {
-    name: 'TuiViewport',
-    declaration: 'export interface TuiViewport {\n    readonly columns: number;\n    readonly rows: number;\n}',
-  },
   {
     name: 'TurnEndReason',
     declaration: 'export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap];',

packages/cordis/tool-cordis/src/guard.ts

@@ -684,7 +684,7 @@ function sandboxContext(ctx: Context): Context {
     if (ctx.get(prop) !== undefined) {
       throw new Error(
         `service "${prop}" is not injected. Declare it: inject: ['${prop}', …] on your plugin, `
-        + 'so cordis parks this mount if the provider is later unmounted.',
+        + 'so cordis parks this temporary Plugin if the provider is later unmounted.',
       )
     }
     throw new Error(

packages/cordis/tool-cordis/src/index.ts

@@ -1,6 +1,6 @@
 /**
- * Self-referential runtime tools: inspect live services/plugins/tools, mount a returned plugin
- * under an owned dynamic fiber, and unmount it to quiescence. Registrations are fiber effects,
+ * Self-referential runtime tools: inspect live services/plugins/tools, mount a returned temporary
+ * plugin under an owned dynamic fiber, and unmount it to quiescence. Registrations are fiber effects,
  * so plugin disposal removes the entire dynamic subtree. The VM and context façade prevent
  * accidental misuse, not hostile code: an allowed service such as `ctx.bash` reaches the real
  * runtime. Named exports preserve loader injection metadata.
@@ -40,8 +40,8 @@ export const Config: z<Config> = z.object({
 type ResolvedConfig = Required<Config>
 
 /**
- * Mount the three cordis tools on `ctx.tools` and create the `cordis-dynamic`
- * group fiber every dynamic mount hangs under.
+ * Register the three cordis tools and own every temporary plugin under one
+ * `cordis-dynamic` group fiber.
  * @param ctx - the plugin context (`tools` injected).
  * @param config - the schemastery-resolved {@link Config}.
  */
@@ -56,19 +56,21 @@ export function apply(ctx: Context, config: Config): void {
   ctx.tools.register(defineTool({
     name: 'cordis_inspect',
     description:
-      'Inspect the live cordis runtime that is running THIS agent. Read-only. '
+      'Inspect the live Cordis runtime in the current DSH process. Read-only. '
       + 'Sections: `services` (every provided ctx service and the plugin fiber that owns it), '
-      + '`plugins` (a flat list of the loaded plugins with their lifecycle states), '
+      + '`plugins` (all live plugin fibers with their lifecycle states), '
       + '`tools` (the model-facing tools currently registered, i.e. what you can call), '
-      + '`dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), '
+      + '`temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), '
       + '`api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), '
       + '`events` (every harness event with its dispatch mode and exact signature — pick listener targets here). '
-      + 'Omit `what` to get all six sections. With `what:"api"` or `what:"events"`, pass an exact `name` '
+      + 'Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. '
+      + 'The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. '
+      + 'With `what:"api"` or `what:"events"`, pass an exact `name` '
       + 'to narrow to one service/event and include its original source JSDoc.',
     parameters: {
       what: {
         type: 'string',
-        enum: ['services', 'plugins', 'tools', 'dynamic', 'api', 'events'],
+        enum: ['services', 'plugins', 'tools', 'temporary', 'api', 'events'],
         description: 'Limit the report to one section. Omit for all sections.',
       },
       name: {
@@ -84,19 +86,19 @@ export function apply(ctx: Context, config: Config): void {
       if (args.name !== undefined && args.what !== 'api' && args.what !== 'events') {
         throw new Error('name is valid only with what:"api" or what:"events"')
       }
-      const sections: [heading: string, body: () => string[]][] = [
-        ['services', () => describeServices(ctx)],
-        ['plugins', () => describePlugins(ctx)],
+      const sections: [key: string, heading: string, body: () => string[]][] = [
+        ['services', 'services', () => describeServices(ctx)],
+        ['plugins', 'plugins', () => describePlugins(ctx)],
         // The calling agent's view: scoped/shadowed tools included, restricted
         // globals absent — "what you can call", not the global registry.
-        ['tools', () => describeTools(ctx, exec.agent)],
-        ['dynamic', () => describeDynamic(ctx, mounts)],
-        ['api', () => describeApi(ctx, SERVICE_API, INHERITED_CTX_API, TYPE_API, args.name)],
-        ['events', () => describeEvents(EVENT_API, args.name)],
+        ['tools', 'tools', () => describeTools(ctx, exec.agent)],
+        ['temporary', 'Temporary Plugins', () => describeDynamic(ctx, mounts)],
+        ['api', 'api', () => describeApi(ctx, SERVICE_API, INHERITED_CTX_API, TYPE_API, args.name)],
+        ['events', 'events', () => describeEvents(EVENT_API, args.name)],
       ]
-      const selected = sections.filter(([heading]) => args.what === undefined || args.what === heading)
+      const selected = sections.filter(([key]) => args.what === undefined || args.what === key)
       const text = selected
-        .map(([heading, body]) => `## ${heading}\n${body().join('\n')}`)
+        .map(([, heading, body]) => `## ${heading}\n${body().join('\n')}`)
         .join('\n\n')
       return Promise.resolve(text)
     },
@@ -106,8 +108,13 @@ export function apply(ctx: Context, config: Config): void {
   ctx.tools.register(defineTool({
     name: 'cordis_mount',
     description:
-      'Mount a NEW cordis plugin into the live runtime that is running THIS agent '
-      + '(self-modification). `code` runs as the body of an async JavaScript function '
+      'Mount a temporary Cordis Plugin in the current DSH process. '
+      + 'This creates an in-memory runtime Plugin, not an installed or configured Plugin. '
+      + 'It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. '
+      + 'It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. '
+      + 'To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. '
+      + 'It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. '
+      + '`code` runs now as the body of an async JavaScript function '
       + 'in an isolated sandbox and MUST `return` a plugin. Two forms: '
       + 'FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register '
       + 'tools, listen to events, and provide services, but reaching ANY service (e.g. '
@@ -131,10 +138,10 @@ export function apply(ctx: Context, config: Config): void {
       + 'oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: \'object\', properties, required?: […] } wrapper is also accepted with open-by-default objects. A '
       + 'tool\'s `execute` MUST return the lossless JSON value declared by `output.schema`; '
       + '`output.render(args, value)` separately returns Native/model content blocks. '
-      + 'Mounts can COMPOSE: one plugin may `ctx.provide(\'name\', value)` a service and '
+      + 'Temporary Plugins can COMPOSE: one Plugin may `ctx.provide(\'name\', value)` a service and '
       + 'another may declare `inject: [\'name\']` to consume it — the consumer stays pending '
       + 'until the provider exists and returns to pending when the provider is unmounted. '
-      + 'Everything registered inside `apply` is cleaned up automatically on unmount. '
+      + 'Everything registered inside `apply` is cleaned up automatically by cordis_unmount. '
       + 'Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness '
       + 'terminal), `harness.defineTool`, `harness.registerTool`, '
       + '`btoa`, `atob`, `TextEncoder`, `TextDecoder`. '
@@ -143,7 +150,7 @@ export function apply(ctx: Context, config: Config): void {
       + 'errors; `process` and `Buffer` are undefined. Instead use inject: [\'fs\'] + ctx.fs for '
       + 'files, inject: [\'web\'] + ctx.web for HTTP, inject: [\'bash\'] + ctx.bash for processes, '
       + 'and inject: [\'timer\'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, '
-      + 'auto-cleaned on unmount) — cordis_inspect what:"api" shows what THIS runtime provides. '
+      + 'auto-cleaned when unmounted) — cordis_inspect what:"api" shows what THIS runtime provides. '
       + 'Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). '
       + 'Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a '
       + 'trailing `next` callback which MUST be called — returning without `next()` '
@@ -159,7 +166,7 @@ export function apply(ctx: Context, config: Config): void {
       code: {
         type: 'string',
         required: true,
-        description: 'Body of an async JS function; must `return` the plugin to mount.',
+        description: 'JavaScript body returning a temporary Plugin; evaluated now and saved nowhere.',
       },
     },
     output: {
@@ -179,12 +186,12 @@ export function apply(ctx: Context, config: Config): void {
         },
       },
       render: (_args, value) => {
-        const note = value.waitingFor.length > 0
-          ? ` — waiting for service(s): ${value.waitingFor.join(', ')} (activates when provided)`
-          : ''
+        const status = value.waitingFor.length > 0
+          ? `is pending (plugin "${value.pluginName}"; missing services: ${value.waitingFor.join(', ')}`
+          : `is running (plugin "${value.pluginName}"`
         return [{
           type: 'text',
-          text: `mounted ${value.id} (plugin "${value.pluginName}", state: ${value.state}${note})`,
+          text: `Temporary Plugin ${value.id} ${status}; available until unmounted or DSH restarts).`,
         }]
       },
     },
@@ -195,13 +202,13 @@ export function apply(ctx: Context, config: Config): void {
       if (!isPlugin(evaluated)) {
         if (evaluated === undefined) {
           throw new Error(
-            'mount code returned `undefined` — did you forget `return`?\n'
+            'temporary Plugin code returned `undefined` — did you forget `return`?\n'
             + '  ✓ return (ctx) => { … }\n'
             + '  ✓ return { name: \'…\', inject: […], apply(ctx) { … } }',
           )
         }
         throw new Error(
-          'mount code must `return` a plugin: a function, or an object with an `apply(ctx)` method',
+          'temporary Plugin code must `return` a Plugin: a function, or an object with an `apply(ctx)` method',
         )
       }
       const fiber = await mountDynamic(group, evaluated)
@@ -225,15 +232,13 @@ export function apply(ctx: Context, config: Config): void {
   ctx.tools.register(defineTool({
     name: 'cordis_unmount',
     description:
-      'Dispose a plugin previously mounted with cordis_mount, by id. All its '
-      + 'registrations (event listeners, tools, services) are cleaned up through '
-      + 'the cordis effect lifecycle. Returns only after disposal has fully '
-      + 'completed (quiescence, not just a request to stop).',
+      'Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. '
+      + 'Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins.',
     parameters: {
       id: {
         type: 'string',
         required: true,
-        description: 'The dynamic mount id returned by cordis_mount (e.g. "dyn-1").',
+        description: 'The temporary Plugin id returned by cordis_mount (for example "dyn-1"); valid only in this process and invalid after unmount or restart.',
       },
     },
     output: {
@@ -245,12 +250,12 @@ export function apply(ctx: Context, config: Config): void {
           pluginName: { type: 'string', required: true },
         },
       },
-      render: (_args, value) => [{ type: 'text', text: `unmounted ${value.id} (plugin "${value.pluginName}")` }],
+      render: (_args, value) => [{ type: 'text', text: `Temporary Plugin ${value.id} was unmounted and removed.` }],
     },
     async execute(args) {
       const mount = mounts.get(args.id)
       if (!mount) {
-        throw new Error(`no dynamic plugin with id "${args.id}" (list mounts with cordis_inspect what:"dynamic")`)
+        throw new Error(`no temporary Plugin with id "${args.id}" (list them with cordis_inspect what:"temporary")`)
       }
       await mount.fiber.dispose()
       mounts.delete(args.id)

packages/cordis/tool-cordis/src/inspect.ts

@@ -1,6 +1,6 @@
 /**
  * Read-only renderers over the live runtime for `cordis_inspect`: the service list, the flat
- * plugin list, the registered tools, the dynamic-mount table (with per-mount provides/waits),
+ * plugin list, the registered tools, the temporary-plugin table (with per-plugin provides/waits),
  * and the catalog-backed `api` / `events` sections. Exact-name lookups add the
  * original source JSDoc without inflating the default reports.
  * @module @deepseek-ai/dsh-tool-cordis/inspect
@@ -63,8 +63,8 @@ export function describeServices(ctx: Context): string[] {
 /**
  * The `plugins` section: a flat list of every fiber the registry knows, one
  * line per fiber with its lifecycle state, sorted by plugin name (a plugin
- * mounted more than once repeats — one line per instance). Dynamic mounts are
- * listed like any other plugin; their ids live in the `dynamic` section.
+ * mounted more than once repeats — one line per instance). Temporary plugins are
+ * listed like any other plugin; their ids live in the `temporary` section.
  * @param ctx - the runtime whose registry is enumerated.
  * @returns one line per loaded plugin fiber.
  */
@@ -91,7 +91,7 @@ export function describeTools(ctx: Context, scope?: ScopeKey): string[] {
 }
 
 /**
- * The `dynamic` section: one line per mount with id, plugin name, lifecycle
+ * The `temporary` section: one line per temporary plugin with id, plugin name, lifecycle
  * state, the services its subtree provides, and — for a pending mount — the
  * services it waits for.
  * @param ctx - the runtime the mounts live in.
@@ -99,13 +99,14 @@ export function describeTools(ctx: Context, scope?: ScopeKey): string[] {
  * @returns one line per mount, or a single placeholder line when none exist.
  */
 export function describeDynamic(ctx: Context, mounts: ReadonlyMap<string, DynamicMount>): string[] {
-  if (mounts.size === 0) return ['(no dynamic plugins mounted)']
+  if (mounts.size === 0) {
+    return ['No temporary Plugins are running. Temporary Plugins created with cordis_mount disappear when DSH restarts.']
+  }
   return [...mounts].map(([id, mount]) => {
     const provides = providedServices(ctx, mount.fiber)
     const waiting = missingServices(ctx, mount.fiber)
-    const providesNote = provides.length > 0 ? ` — provides: ${provides.join(', ')}` : ''
-    const waitingNote = waiting.length > 0 ? ` — waiting for: ${waiting.join(', ')}` : ''
-    return `- ${id}: ${mount.pluginName} [${STATE_LABELS[mount.fiber.state]}]${providesNote}${waitingNote}`
+    const state = mount.fiber.state === FiberState.ACTIVE ? 'running' : STATE_LABELS[mount.fiber.state]
+    return `- Temporary Plugin ${id}: ${mount.pluginName} [${state}] — provides: ${provides.join(', ') || 'none'}; waiting for: ${waiting.join(', ') || 'none'}; lifetime: until unmounted or DSH restarts`
   })
 }
 

packages/cordis/tool-cordis/src/mount.ts

@@ -39,8 +39,8 @@ export async function mountDynamic(group: Fiber, plugin: Plugin): Promise<Fiber>
     // while the old mount still holds the name — teach the replace recipe.
     if (message.includes('already registered')) {
       throw new Error(
-        `${message} — to REPLACE something an earlier mount registered, first cordis_unmount that mount's id `
-        + '(find it with cordis_inspect what:"dynamic"), then mount the new version.',
+        `${message} — to REPLACE something an earlier temporary Plugin registered, first cordis_unmount that Plugin's id `
+        + '(find it with cordis_inspect what:"temporary"), then mount the new version.',
       )
     }
     throw error instanceof Error ? error : new Error(message)

packages/cordis/tool-cordis/src/present.ts

@@ -25,7 +25,7 @@ export function presentInspectCall(args: { what?: string; name?: string }): Gene
 }
 
 /**
- * The `cordis_mount` call card: an execute carrying the mount code as raw input.
+ * The `cordis_mount` call card: an execute carrying the temporary-plugin code as raw input.
  * @param args - the validated call arguments.
  * @returns the generic call card.
  */
@@ -33,13 +33,13 @@ export function presentMountCall(args: { code: string }): GenericCallView {
   return {
     card: 'generic',
     kind: 'execute',
-    title: 'Mount plugin into live cordis runtime',
+    title: 'Mount temporary Cordis Plugin',
     rawInput: { code: args.code },
   }
 }
 
 /**
- * The `cordis_unmount` call card: a delete, titled with the mount id.
+ * The `cordis_unmount` call card: a delete, titled with the temporary-plugin id.
  * @param args - the validated call arguments.
  * @returns the generic call card.
  */
@@ -47,6 +47,6 @@ export function presentUnmountCall(args: { id: string }): GenericCallView {
   return {
     card: 'generic',
     kind: 'delete',
-    title: `Unmount ${args.id}`,
+    title: `Unmount temporary Cordis Plugin ${args.id}`,
   }
 }

packages/cordis/tool-cordis/src/sandbox.ts

@@ -52,7 +52,7 @@ function patchDualRealmInstanceof(sandbox: object): void {
 
 const TIMER_REDIRECT
   = 'Node timers are unavailable. Use the cordis timer service instead: declare inject: [\'timer\'] on your plugin '
-    + 'and call ctx.setTimeout / ctx.setInterval — those are fiber effects, cleaned up automatically on unmount.'
+    + 'and call ctx.setTimeout / ctx.setInterval — those are fiber effects, cleaned up automatically when unmounted.'
 
 /**
  * The callable Node APIs the sandbox deliberately disables, each mapped to the
@@ -80,7 +80,7 @@ function nodeApiTraps(): Record<string, () => never> {
   const traps: Record<string, () => never> = {}
   for (const [name, redirect] of Object.entries(NODE_API_REDIRECTS)) {
     traps[name] = () => {
-      throw new Error(`${name} is not available in the mount sandbox — ${redirect}`)
+      throw new Error(`${name} is not available in the temporary Plugin sandbox — ${redirect}`)
     }
   }
   return traps
@@ -163,14 +163,14 @@ export async function evaluateMountCode(sandbox: object, code: string, id: strin
     const offendingLine = context.split('\n')[1] ?? ''
     if (/\bas\b/.test(offendingLine)) {
       throw new Error(
-        `mount code failed to parse:\n${context}\n`
+        `temporary Plugin code failed to parse:\n${context}\n`
         + 'The sandbox runs plain JavaScript, not TypeScript. Remove type annotations:\n'
         + '  ✗ { type: \'text\' as const, text: x }\n'
         + '  ✓ { type: \'text\', text: x }',
       )
     }
     throw new Error(
-      `mount code failed to parse:\n${context}\n`
+      `temporary Plugin code failed to parse:\n${context}\n`
       + 'Note: `code` runs as the BODY of an async function (line numbers are offset by the 1-line wrapper). '
       + 'Check bracket balance — ending the returned plugin object with `});` closes a call that was never opened; '
       + 'a plain `return { … }` ends with `}` (an optional `;`), never `)`.',

packages/cordis/tool-cordis/tests/cross-mount.spec.ts

@@ -12,11 +12,11 @@ describe('cross-mount provide/inject', () => {
   it('provider first: the consumer activates immediately and its tool reaches the provided service', async () => {
     const ctx = await setup()
     const provider = await call(ctx, 'cordis_mount', { code: PROVIDER_CODE })
-    expect(text(provider)).toContain('state: active')
+    expect(text(provider)).toContain('is running')
 
     const consumer = await call(ctx, 'cordis_mount', { code: CONSUMER_CODE })
     expect(consumer.isError).toBe(false)
-    expect(text(consumer)).toContain('state: active')
+    expect(text(consumer)).toContain('is running')
 
     // The vm-realm service value is callable across mounts, and the result
     // normalizes into the host realm like any dynamic tool result.
@@ -29,9 +29,9 @@ describe('cross-mount provide/inject', () => {
     const ctx = await setup()
     const consumer = await call(ctx, 'cordis_mount', { code: CONSUMER_CODE })
     expect(consumer.isError).toBe(false)
-    expect(text(consumer)).toContain('state: pending')
-    expect(text(consumer)).toContain('waiting for service(s): greeter')
-    expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('waiting for: greeter')
+    expect(text(consumer)).toContain('is pending')
+    expect(text(consumer)).toContain('missing services: greeter')
+    expect(text(await call(ctx, 'cordis_inspect', { what: 'temporary' }))).toContain('waiting for: greeter')
     expect(ctx.tools.get('greet')).toBeUndefined()
 
     await call(ctx, 'cordis_mount', { code: PROVIDER_CODE })
@@ -48,8 +48,8 @@ describe('cross-mount provide/inject', () => {
     const unmounted = await call(ctx, 'cordis_unmount', { id: 'dyn-1' })
     expect(unmounted.isError).toBe(false)
     expect(ctx.tools.get('greet')).toBeUndefined()
-    const report = text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))
-    expect(report).toContain('dyn-2: greeter-consumer [pending] — waiting for: greeter')
+    const report = text(await call(ctx, 'cordis_inspect', { what: 'temporary' }))
+    expect(report).toContain('Temporary Plugin dyn-2: greeter-consumer [pending] — provides: none; waiting for: greeter; lifetime: until unmounted or DSH restarts')
   })
 
   it('re-providing the service re-runs the consumer through the same guard (active again, tool back)', async () => {
@@ -62,7 +62,7 @@ describe('cross-mount provide/inject', () => {
     await call(ctx, 'cordis_mount', { code: PROVIDER_CODE })   // dyn-3
     expect(ctx.tools.get('greet')).toBeDefined()
     expect(text(await call(ctx, 'greet', { name: 'again' }))).toBe('hi again')
-    expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('dyn-2: greeter-consumer [active]')
+    expect(text(await call(ctx, 'cordis_inspect', { what: 'temporary' }))).toContain('Temporary Plugin dyn-2: greeter-consumer [running]')
   })
 
   it('a duplicate provide fails loud with the owning fiber named, and the failed mount is disposed', async () => {
@@ -71,8 +71,8 @@ describe('cross-mount provide/inject', () => {
     const duplicate = await call(ctx, 'cordis_mount', { code: PROVIDER_CODE })
     expect(duplicate.isError).toBe(true)
     expect(text(duplicate)).toContain('has been registered')
-    const report = text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))
-    expect(report).toContain('dyn-1: greeter-provider')
+    const report = text(await call(ctx, 'cordis_inspect', { what: 'temporary' }))
+    expect(report).toContain('Temporary Plugin dyn-1: greeter-provider')
     expect(report).not.toContain('dyn-2')
   })
 
@@ -81,8 +81,8 @@ describe('cross-mount provide/inject', () => {
     await call(ctx, 'cordis_mount', { code: PROVIDER_CODE })
     await call(ctx, 'cordis_mount', { code: CONSUMER_CODE })
 
-    const dynamic = text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))
-    expect(dynamic).toContain('dyn-1: greeter-provider [active] — provides: greeter')
+    const dynamic = text(await call(ctx, 'cordis_inspect', { what: 'temporary' }))
+    expect(dynamic).toContain('Temporary Plugin dyn-1: greeter-provider [running] — provides: greeter; waiting for: none; lifetime: until unmounted or DSH restarts')
 
     const services = text(await call(ctx, 'cordis_inspect', { what: 'services' }))
     expect(services).toContain('- greeter (provided by greeter-provider)')
@@ -126,7 +126,7 @@ describe('cross-mount provide/inject', () => {
       `,
     })
     expect(consumer.isError).toBe(false)
-    expect(text(consumer)).toContain('state: active')
+    expect(text(consumer)).toContain('is running')
     expect(text(await call(ctx, 'answer', {}))).toBe('42/42/null')
   })
 
@@ -139,6 +139,6 @@ describe('cross-mount provide/inject', () => {
     expect(ctx.tools.get('greet')).toBeUndefined()
     const services = text(await call(ctx, 'cordis_inspect', { what: 'services' }))
     expect(services).toContain('- greeter (provided by greeter-provider)')
-    expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('dyn-1: greeter-provider [active]')
+    expect(text(await call(ctx, 'cordis_inspect', { what: 'temporary' }))).toContain('Temporary Plugin dyn-1: greeter-provider [running]')
   })
 })

packages/cordis/tool-cordis/tests/inspect.spec.ts

@@ -18,7 +18,7 @@ describe('cordis_inspect', () => {
     const report = text(result)
     if (result.isError) throw new Error('expected cordis_inspect success')
     expect(result.value).toBe(report)
-    for (const heading of ['services', 'plugins', 'tools', 'dynamic', 'api', 'events']) {
+    for (const heading of ['services', 'plugins', 'tools', 'Temporary Plugins', 'api', 'events']) {
       expect(report).toContain(`## ${heading}`)
     }
     // The services section sees the real providers; the plugins list shows
@@ -28,7 +28,7 @@ describe('cordis_inspect', () => {
     expect(report).toContain('- tool-cordis [active]')
     expect(report).toContain('- cordis-dynamic [active]')
     expect(report).toContain('- cordis_mount')
-    expect(report).toContain('(no dynamic plugins mounted)')
+    expect(report).toContain('No temporary Plugins are running. Temporary Plugins created with cordis_mount disappear when DSH restarts.')
   })
 
   it('limits the report to one section via `what`', async () => {
@@ -40,11 +40,12 @@ describe('cordis_inspect', () => {
     expect(report).not.toContain('## plugins')
   })
 
-  it('shows a mount in the dynamic section and in the flat plugins list', async () => {
+  it('shows a temporary Plugin in its exact section and in the flat plugins list', async () => {
     const ctx = await setup()
     await call(ctx, 'cordis_mount', { code: LISTENER_CODE })
     const report = text(await call(ctx, 'cordis_inspect', {}))
-    expect(report).toContain('- dyn-1: change-logger [active]')
+    expect(report).toContain('## Temporary Plugins')
+    expect(report).toContain('- Temporary Plugin dyn-1: change-logger [running] — provides: none; waiting for: none; lifetime: until unmounted or DSH restarts')
     expect(report).toContain('- change-logger [active]')
   })
 

packages/cordis/tool-cordis/tests/integration.spec.ts

@@ -1,12 +1,13 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
+import { CallId } from '@deepseek-ai/dsh-llm'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
 import * as ToolCordis from '../src/index.ts'
 import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
-import { REVERSE_TOOL_CODE } from './helpers.ts'
+import { call, REVERSE_TOOL_CODE, setup, text } from './helpers.ts'
 
 /**
  * Full-loop integration: a scripted mock model mounts a plugin that registers
@@ -65,4 +66,36 @@ describe('cordis tools through the agent loop', () => {
     // After the unmount the self-made tool is gone from the registry.
     expect(ctx.tools.get('reverse_text')).toBeUndefined()
   })
+
+  it('keeps a temporary Plugin across turns, unmounts it, and does not restore it in a new runtime', async () => {
+    const adapter = new MockAdapter([
+      toolCallResponse('mount-1', 'cordis_mount', { code: 'return { name: \'turn-marker\', apply() {} }' }),
+      toolCallResponse('inspect-1', 'cordis_inspect', { what: 'temporary' }),
+      textResponse('Turn one complete.'),
+      toolCallResponse('inspect-2', 'cordis_inspect', { what: 'temporary' }),
+      toolCallResponse('unmount-1', 'cordis_unmount', { id: 'dyn-1' }),
+      toolCallResponse('inspect-3', 'cordis_inspect', { what: 'temporary' }),
+      textResponse('Turn two complete.'),
+    ])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('it-cordis-turn-lifetime'), { provider: 'mock', model: 'mock' })
+
+    agent.followup({ content: [{ type: 'text', text: 'Mount the marker and inspect it.' }], source: { kind: 'user' } })
+    await waitForIdle(ctx, agent)
+    agent.followup({ content: [{ type: 'text', text: 'On this later turn, inspect the marker, unmount it, then inspect again.' }], source: { kind: 'user' } })
+    await waitForIdle(ctx, agent)
+
+    const resultText = new Map(
+      agent.session.events
+        .filter(event => event.type === 'tool/result')
+        .map(event => [event.data.callId, event.data.content.filter(block => block.type === 'text').map(block => block.text).join('')]),
+    )
+    expect(resultText.get(CallId('inspect-1'))).toContain('Temporary Plugin dyn-1: turn-marker [running]')
+    expect(resultText.get(CallId('inspect-2'))).toContain('Temporary Plugin dyn-1: turn-marker [running]')
+    expect(resultText.get(CallId('unmount-1'))).toBe('Temporary Plugin dyn-1 was unmounted and removed.')
+    expect(resultText.get(CallId('inspect-3'))).toContain('No temporary Plugins are running.')
+
+    const restarted = await setup()
+    expect(text(await call(restarted, 'cordis_inspect', { what: 'temporary' }))).toContain('No temporary Plugins are running.')
+  })
 })

packages/cordis/tool-cordis/tests/mount.spec.ts

@@ -57,7 +57,7 @@ describe('cordis_mount', () => {
       provides: [],
       waitingFor: [],
     })
-    expect(text(result)).toContain('mounted dyn-1 (plugin "change-logger", state: active)')
+    expect(text(result)).toBe('Temporary Plugin dyn-1 is running (plugin "change-logger"; available until unmounted or DSH restarts).')
 
     // Fire a REAL tools/change by registering a tool; the mounted listener logs.
     ctx.tools.register(dummyTool('trigger_a'))
@@ -665,8 +665,7 @@ describe('cordis_mount', () => {
       provides: [],
       waitingFor: ['no-such-service'],
     })
-    expect(text(result)).toContain('state: pending')
-    expect(text(result)).toContain('waiting for service(s): no-such-service')
+    expect(text(result)).toBe('Temporary Plugin dyn-1 is pending (plugin "waiter"; missing services: no-such-service; available until unmounted or DSH restarts).')
     // Unmounting a pending mount works like any other.
     const unmounted = await call(ctx, 'cordis_unmount', { id: 'dyn-1' })
     expect(unmounted.isError).toBe(false)
@@ -677,7 +676,7 @@ describe('cordis_mount', () => {
     const result = await call(ctx, 'cordis_mount', { code: 'throw new Error(\'boom in sandbox\')' })
     expect(result.isError).toBe(true)
     expect(text(result)).toContain('boom in sandbox')
-    expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('(no dynamic plugins mounted)')
+    expect(text(await call(ctx, 'cordis_inspect', { what: 'temporary' }))).toContain('No temporary Plugins are running.')
   })
 
   it('passes non-Error and null throws through untouched (no SyntaxError misclassification)', async () => {
@@ -693,7 +692,7 @@ describe('cordis_mount', () => {
     const ctx = await setup()
     const result = await call(ctx, 'cordis_mount', { code: 'return 42' })
     expect(result.isError).toBe(true)
-    expect(text(result)).toContain('must `return` a plugin')
+    expect(text(result)).toContain('must `return` a Plugin')
   })
 
   it('answers a missing return with the two valid plugin forms', async () => {
@@ -710,7 +709,7 @@ describe('cordis_mount', () => {
     })
     expect(result.isError).toBe(true)
     expect(text(result)).toContain('apply exploded')
-    expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('(no dynamic plugins mounted)')
+    expect(text(await call(ctx, 'cordis_inspect', { what: 'temporary' }))).toContain('No temporary Plugins are running.')
   })
 
   it('rolls back a plugin that collides with an existing tool name, keeping the original tool intact', async () => {
@@ -754,16 +753,16 @@ describe('cordis_mount', () => {
   })
 
   it.each([
-    ['require(\'fs\')', 'require is not available in the mount sandbox', 'inject: [\'fs\']'],
-    ['setTimeout(() => {}, 5)', 'setTimeout is not available in the mount sandbox', 'ctx.setTimeout'],
-    ['fetch(\'https://example.com\')', 'fetch is not available in the mount sandbox', 'ctx.web'],
+    ['require(\'fs\')', 'require is not available in the temporary Plugin sandbox', 'inject: [\'fs\']'],
+    ['setTimeout(() => {}, 5)', 'setTimeout is not available in the temporary Plugin sandbox', 'ctx.setTimeout'],
+    ['fetch(\'https://example.com\')', 'fetch is not available in the temporary Plugin sandbox', 'ctx.web'],
   ])('traps the Node API call %s with a redirect to the cordis alternative', async (invocation, trapMessage, redirect) => {
     const ctx = await setup()
     const result = await call(ctx, 'cordis_mount', { code: `${invocation}\nreturn (ctx) => {}` })
     expect(result.isError).toBe(true)
     expect(text(result)).toContain(trapMessage)
     expect(text(result)).toContain(redirect)
-    expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('(no dynamic plugins mounted)')
+    expect(text(await call(ctx, 'cordis_inspect', { what: 'temporary' }))).toContain('No temporary Plugins are running.')
   })
 
   it('lets a mounted plugin schedule through the cordis timer service (inject: [\'timer\'])', async () => {
@@ -781,7 +780,7 @@ describe('cordis_mount', () => {
       `,
     })
     expect(result.isError).toBe(false)
-    expect(text(result)).toContain('state: active')
+    expect(text(result)).toContain('is running')
     await new Promise(resolve => setTimeout(resolve, 50))
     expect(log).toHaveBeenCalledWith('[cordis:dyn-1]', 'tick')
   })
@@ -854,7 +853,7 @@ describe('cordis_mount', () => {
     const result = await call(ctx, 'cordis_mount', { code: 'while (true) {}' })
     expect(result.isError).toBe(true)
     expect(text(result)).toMatch(/timed? ?out/i)
-    expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('(no dynamic plugins mounted)')
+    expect(text(await call(ctx, 'cordis_inspect', { what: 'temporary' }))).toContain('No temporary Plugins are running.')
   })
 
   it('makes instanceof inside the sandbox see BOTH realms (patched vm constructors, host untouched)', async () => {

packages/cordis/tool-cordis/tests/present.spec.ts

@@ -22,13 +22,13 @@ describe('presenters', () => {
     expect(presentMountCall({ code: 'return (ctx) => {}' })).toEqual({
       card: 'generic',
       kind: 'execute',
-      title: 'Mount plugin into live cordis runtime',
+      title: 'Mount temporary Cordis Plugin',
       rawInput: { code: 'return (ctx) => {}' },
     })
   })
 
   it('cordis_unmount renders a generic delete card titled with the id', () => {
-    expect(presentUnmountCall({ id: 'dyn-1' })).toEqual({ card: 'generic', kind: 'delete', title: 'Unmount dyn-1' })
+    expect(presentUnmountCall({ id: 'dyn-1' })).toEqual({ card: 'generic', kind: 'delete', title: 'Unmount temporary Cordis Plugin dyn-1' })
   })
 
   it('is wired onto the registered definitions through the defineTool soft-validation path', async () => {
@@ -42,7 +42,7 @@ describe('presenters', () => {
       title: 'Inspect cordis runtime: api: tools',
     })
     expect(ctx.tools.get('cordis_mount')!.presentCall!({ code: 'return 1' })).toMatchObject({ kind: 'execute' })
-    expect(ctx.tools.get('cordis_unmount')!.presentCall!({ id: 'dyn-2' })).toMatchObject({ title: 'Unmount dyn-2' })
+    expect(ctx.tools.get('cordis_unmount')!.presentCall!({ id: 'dyn-2' })).toMatchObject({ title: 'Unmount temporary Cordis Plugin dyn-2' })
     // Soft validation: presenter args that fail the schema render as no card, never a throw.
     expect(ctx.tools.get('cordis_unmount')!.presentCall!({ id: 42 })).toBeUndefined()
   })

packages/cordis/tool-cordis/tests/sandbox-context.spec.ts

@@ -186,7 +186,7 @@ describe('sandbox context façade — inject gate on services', () => {
       `,
     })
     expect(result.isError).toBe(false)
-    expect(text(result)).toContain('state: active')
+    expect(text(result)).toContain('is running')
   })
 
   it('a cross-mount consumer must declare the provider — the undeclared path is refused, not left as a zombie tool', async () => {

packages/cordis/tool-cordis/tests/tool-cordis.spec.ts

@@ -31,9 +31,10 @@ describe('tool registration', () => {
     const ctx = await setup()
     const names = ctx.tools.schemas().map(schema => schema.name)
     expect(names).toEqual(expect.arrayContaining(['cordis_inspect', 'cordis_mount', 'cordis_unmount']))
+    expect(names).not.toEqual(expect.arrayContaining(['cordis_try', 'cordis_stop']))
     const inspect = ctx.tools.schemas().find(schema => schema.name === 'cordis_inspect')!
     const props = (inspect.parameters as { properties: Record<string, { enum?: string[]; type?: string }> }).properties
-    expect(props.what?.enum).toEqual(['services', 'plugins', 'tools', 'dynamic', 'api', 'events'])
+    expect(props.what?.enum).toEqual(['services', 'plugins', 'tools', 'temporary', 'api', 'events'])
     expect(props.name?.type).toBe('string')
   })
 })

packages/cordis/tool-cordis/tests/unmount-hmr.spec.ts

@@ -28,13 +28,13 @@ describe('cordis_unmount', () => {
     expect(result.isError).toBe(false)
     if (result.isError) throw new Error('expected cordis_unmount success')
     expect(result.value).toEqual({ id: 'dyn-1', pluginName: 'change-logger' })
-    expect(text(result)).toContain('unmounted dyn-1')
+    expect(text(result)).toBe('Temporary Plugin dyn-1 was unmounted and removed.')
 
     // Immediately after the awaited unmount, the listener must be gone — no
     // grace period, no eventual consistency.
     ctx.tools.register(dummyTool('trigger_after'))
     expect(log).toHaveBeenCalledTimes(1)
-    expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('(no dynamic plugins mounted)')
+    expect(text(await call(ctx, 'cordis_inspect', { what: 'temporary' }))).toContain('No temporary Plugins are running.')
   })
 
   it('unregisters a self-made tool on unmount', async () => {
@@ -50,7 +50,7 @@ describe('cordis_unmount', () => {
     const ctx = await setup()
     const unknown = await call(ctx, 'cordis_unmount', { id: 'dyn-99' })
     expect(unknown.isError).toBe(true)
-    expect(text(unknown)).toContain('no dynamic plugin with id "dyn-99"')
+    expect(text(unknown)).toContain('no temporary Plugin with id "dyn-99"')
 
     await call(ctx, 'cordis_mount', { code: LISTENER_CODE })
     await call(ctx, 'cordis_unmount', { id: 'dyn-1' })

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)
       }
@@ -422,8 +428,8 @@ export class ReactLoopAgent implements Agent {
       signal.removeEventListener('abort', cancelRetry)
     }
 
-    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
@@ -483,7 +489,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
     }
@@ -493,7 +499,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])
   })

packages/core/agent/src/types.ts

@@ -8,7 +8,7 @@
 import type { Context } from 'cordis'
 import type { Branded } from '@deepseek-ai/dsh-brand'
 import type { Scoped } from '@deepseek-ai/dsh-scope'
-import type { ContentBlock, LlmCallConfig, LlmFailure, MessageSource } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock, LlmCallConfig, LlmFailure, MessageSource, ResolvedRetryPolicy } from '@deepseek-ai/dsh-llm'
 import type { Session, SessionId, UserMessageData } from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 declare module '@deepseek-ai/dsh-system-prompt' {
@@ -370,11 +370,15 @@ declare module 'cordis' {
      * @param step - the failed step number.
      * @param error - the original model-request failure.
      * @param failure - serializable facts normalized at the final adapter boundary.
+     * @param priorFailures - immutable failures that already authorized another
+     * retry turn in this consecutive sequence.
+     * @param retryPolicy - immutable policy of the adapter registration that served
+     * the failed request, or `undefined` if no final adapter served it.
      * @param signal - the turn abort signal.
      * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @mode waterfall
      */
-    'agent/request-error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: RequestError, failure: LlmFailure, signal: AbortSignal, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
+    'agent/request-error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: RequestError, failure: LlmFailure, priorFailures: readonly LlmFailure[], retryPolicy: ResolvedRetryPolicy | undefined, signal: AbortSignal, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
     /**
      * The turn is about to close: the model owes no response (no live tool
      * calls, no fresh steering). Awaited before the boundary commits — a

packages/core/scope/tests/invariant.spec.ts

@@ -55,6 +55,8 @@ describe('scoped-dispatch invariants', () => {
         1,
         new Error('request'),
         { message: 'request', code: 'UNKNOWN' },
+        [],
+        undefined,
         signal,
         () => Promise.resolve(undefined),
       ],

packages/examples/acp-demo/README.i18n.yaml

@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # 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
-README.md: bbc41f1e0aa0c98a6e70ee54357675f1d7f05dbc
-README.zh.md: 03e1246d5358138c633d2b19a9c186a3beec5a1e
+#   pnpm run verify-translation-pairing --write packages/examples/acp-demo/README.md
+README.md: 395ab230146568989c4e6d1361218efb72d857e7
+README.zh.md: 1dfd2d99f4ab80953df77feba19649b934775d68

packages/examples/acp-demo/README.md

@@ -36,7 +36,6 @@ The app does not install commands, user interaction, session navigation, configu
 | `toolBash` | owner defaults | Model-facing bash tool config. |
 | `toolTasks` | owner defaults | Generic background-task control config, or `false`. |
 | `goals` | owner defaults | Persisted same-session goal domain and model tools, or `false`. |
-| `llmRetry` | owner defaults | Bounded transient model-request retry policy. |
 
 The shipped [`examples/acp-agent/cordis.yml`](../../../examples/acp-agent/cordis.yml) adds the DeepSeek adapter, sandboxed bash and filesystem providers, one-shot approval policy, compaction, subagents, workflows, hooks, and model-facing tools. The app supplies the derived session-query index, while the model-facing query consumer remains an explicit leaf opt-in. Snapshot overlays replace only nondeterministic providers or policy values.
 

packages/examples/acp-demo/README.zh.md

@@ -36,7 +36,6 @@ ACP 自动化服务器应用：默认 agent 主干、客户端通过 [`@deepseek
 | `toolBash` | 拥有者默认值 | 面向模型的 bash 工具配置。 |
 | `toolTasks` | 拥有者默认值 | 通用后台任务控制配置，或 `false`。 |
 | `goals` | 拥有者默认值 | 持久的同会话目标领域与模型工具，或 `false`。 |
-| `llmRetry` | 拥有者默认值 | 有界的瞬时模型请求重试策略。 |
 
 已交付的 [`examples/acp-agent/cordis.yml`](../../../examples/acp-agent/cordis.yml) 添加 DeepSeek 适配器、沙箱化 bash 与文件系统提供方、一次性批准策略、压缩、subagent、工作流、钩子，以及面向模型的工具。应用提供派生会话查询索引，而面向模型的查询消费方仍由叶节点显式选用。快照 overlay 只替换非确定性提供方或策略值。
 

packages/examples/acp-demo/src/index.ts

@@ -69,8 +69,6 @@ export interface Config {
   toolTasks?: NonNullable<agentCore.Config['toolTasks']>
   /** Persisted same-session goals; owner defaults enable them, or false disables the stack and tools. */
   goals?: agentCore.GoalConfig | false
-  /** Bounded transient model-request retry policy forwarded through agent-core. */
-  llmRetry?: NonNullable<agentCore.Config['llmRetry']>
 }
 
 // Each front door owns a complete, directly readable config schema; extracting
@@ -96,7 +94,6 @@ export const Config: z<Config> = z.object({
   toolBash: agentCore.ToolBashConfigSchema,
   toolTasks: z.union([z.const(false), agentCore.ToolTasksConfigSchema]),
   goals: z.union([z.const(false), agentCore.GoalConfigSchema]),
-  llmRetry: agentCore.LlmRetryConfigSchema,
 })
 /* jscpd:ignore-end */
 

packages/examples/acp-demo/tests/built-bin.e2e.ts

@@ -210,6 +210,7 @@ describe.skipIf(!existsSync(acpBin))('dsh-acp-demo BUILT bin (node lib/bin.js, n
     expect(code).not.toBe(0)
     expect(stderr).toContain('config file not found')
   }, 30_000)
+
 })
 
 /** Spawn the built acp bin against `configArg` (stdin closed at EOF) and resolve with its exit code + stderr. */

packages/examples/agent-spine-demo/README.i18n.yaml

@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # 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
-README.md: 32874bf2839c194572ddde8c4ed007297f763ccc
-README.zh.md: 57a06a00203b8e67f2f33c87d7450d1a0789d7e6
+#   pnpm run verify-translation-pairing --write packages/examples/agent-spine-demo/README.md
+README.md: 359e7153be2f480ba3fea4b06782acdc9f89ebb9
+README.zh.md: 57fec3f32f5bbc8f3d82ff8971d36d376d722753

packages/examples/agent-spine-demo/README.md

@@ -23,7 +23,7 @@ Read this package for the whole plugin tree and its composition order.
 @deepseek-ai/dsh-goal             optional persisted same-session goal domain
 @deepseek-ai/dsh-tool-goal        optional model-facing goal controls
 @deepseek-ai/dsh-goal-session     optional same-session goal-round driver
-@deepseek-ai/dsh-llm-retry        bounded transient request retry policy
+@deepseek-ai/dsh-llm-retry        provider-routed request retry policy
 @deepseek-ai/dsh-tasks-local      generic background-task registry
 @deepseek-ai/dsh-invariants       configurable invariant registry service
 @deepseek-ai/dsh-session/invariant
@@ -55,11 +55,11 @@ This is the [interface/implementation/consumer seam](../../../.agents/notes/impl
 
 ```ts
 import type { Config } from '@deepseek-ai/dsh-agent-spine-demo'
-// { agents?, maxParallelToolCalls?, persona?, toolOrder?, tools?, dshHome?, sessionTitle?, skills?, workspaceContext, toolBash?, toolTasks?, goals?, invariants?, llmRetry? }
+// { agents?, maxParallelToolCalls?, persona?, toolOrder?, tools?, dshHome?, sessionTitle?, skills?, workspaceContext, toolBash?, toolTasks?, goals?, invariants? }
 // workspaceContext requires { maxBytes } or false; the other owner schemas supply defaults.
 ```
 
-The bundle FORWARDS each field to the child that owns it: `agents` and `maxParallelToolCalls` to `agent-loop` (`agents` defaults to `[]`; the cap defaults there), so each app supplies its own pre-created agents — TUI and headless apps pre-create `main`, while the ACP app creates agents on demand at `session/new`; `llmRetry` to the bounded retry policy; `persona` and `toolOrder` to `dsh-system-prompt`; `tools` to the tool registry for its presentation mode; `sessionTitle` to the fallback title service; `skills.registry`, `skills.local`, and `skills.tool` to the skill registry, local provider, and model-facing consumer; the required `workspaceContext` choice to `dsh-workspace-context` (`{ maxBytes }` enables loading and `false` disables it); `invariants` to the invariant service; and `toolBash`/`toolTasks` to the two model-facing tool plugins the bundle owns. Omitted `sessionTitle` uses the explicit example policy of 5 words, 40 fallback bytes, and 80 accepted-title bytes. A `goals` object opts into the persisted domain, model tools, and same-session driver while forwarding `goals.domain` and `goals.tool` to their owners; omission or `false` leaves the stack absent so headless callers retain one-turn settlement. Set `skills.enabled: false` to omit both the local provider and model-facing skill tool, and set `toolTasks: false` to retain the task service for foreground producers without exposing `task_output` / `task_list` / `task_kill`. It resolves `dshHome` once through [`@deepseek-ai/dsh-paths`](../../util/paths/README.md) and forwards that absolute value to tool-bash's managed environment and enabled local skill discovery. An absent top-level `dshHome` adopts `skills.local.dshHome`; supplying both with different resolved paths fails loudly. `toolBash.enableRunInBackground` controls only the bash producer; independently loaded producers keep their own config. Workspace instructions register before the skill catalog so their session-prefix message renders first. App packages use `pickSpineConfig()` to copy only these bundle-owned fields.
+The bundle FORWARDS each field to the child that owns it: `agents` and `maxParallelToolCalls` to `agent-loop` (`agents` defaults to `[]`; the cap defaults there), so each app supplies its own pre-created agents — TUI and headless apps pre-create `main`, while the ACP app creates agents on demand at `session/new`; `persona` and `toolOrder` to `dsh-system-prompt`; `tools` to the tool registry for its presentation mode; `sessionTitle` to the fallback title service; `skills.registry`, `skills.local`, and `skills.tool` to the skill registry, local provider, and model-facing consumer; the required `workspaceContext` choice to `dsh-workspace-context` (`{ maxBytes }` enables loading and `false` disables it); `invariants` to the invariant service; and `toolBash`/`toolTasks` to the two model-facing tool plugins the bundle owns. It always mounts `dsh-llm-retry`, while each leaf adapter owns its nested `retryPolicy`. Omitted `sessionTitle` uses the explicit example policy of 5 words, 40 fallback bytes, and 80 accepted-title bytes. A `goals` object opts into the persisted domain, model tools, and same-session driver while forwarding `goals.domain` and `goals.tool` to their owners; omission or `false` leaves the stack absent so headless callers retain one-turn settlement. Set `skills.enabled: false` to omit both the local provider and model-facing skill tool, and set `toolTasks: false` to retain the task service for foreground producers without exposing `task_output` / `task_list` / `task_kill`. It resolves `dshHome` once through [`@deepseek-ai/dsh-paths`](../../util/paths/README.md) and forwards that absolute value to tool-bash's managed environment and enabled local skill discovery. An absent top-level `dshHome` adopts `skills.local.dshHome`; supplying both with different resolved paths fails loudly. `toolBash.enableRunInBackground` controls only the bash producer; independently loaded producers keep their own config. Workspace instructions register before the skill catalog so their session-prefix message renders first. App packages use `pickSpineConfig()` to copy only these bundle-owned fields.
 
 For example, `{ invariants: { enabled: true, package_allowlist: ['^@deepseek-ai/dsh-'], package_blocklist: ['agent-loop$'] } }` keeps the package-owned companions mounted but suppresses the blocked owner. Blocklist matches override allowlist matches; see [`dsh-invariants`](../../support/invariants/README.md) for regex and lifecycle rules.
 
@@ -67,7 +67,7 @@ For example, `{ invariants: { enabled: true, package_allowlist: ['^@deepseek-ai/
 
 A YAML include can deduplicate config but cannot own a bin or provide front-door defaults. The ACP app package makes protocol-pure stdout wiring the default, though a leaf can still add an unsafe logger. Bundle children register services in the root isolate-keyed store, so injected leaf siblings see them without load-order coupling.
 
-The bounded retry policy may repeat a transiently failed request in a new numbered step. Retry status and failed partial chunks stay outside model history, each provider attempt can still incur billing, front doors derive usage across every logged step, and the reconstructed request preserves the prior prefix for provider cache reuse.
+The retry policy may repeat a failed request in a new numbered step. Retry status, provider errors, and failed partial chunks stay outside model history; each provider attempt can still incur billing, always mode has no attempt limit, front doors derive usage across every logged step, and the reconstructed request preserves the prior prefix for provider cache reuse.
 
 ## Model Experience
 

packages/examples/agent-spine-demo/README.zh.md

@@ -23,7 +23,7 @@
 @deepseek-ai/dsh-goal             optional persisted same-session goal domain
 @deepseek-ai/dsh-tool-goal        optional model-facing goal controls
 @deepseek-ai/dsh-goal-session     optional same-session goal-round driver
-@deepseek-ai/dsh-llm-retry        bounded transient request retry policy
+@deepseek-ai/dsh-llm-retry        provider-routed request retry policy
 @deepseek-ai/dsh-tasks-local      generic background-task registry
 @deepseek-ai/dsh-invariants       configurable invariant registry service
 @deepseek-ai/dsh-session/invariant
@@ -55,11 +55,11 @@
 
 ```ts
 import type { Config } from '@deepseek-ai/dsh-agent-spine-demo'
-// { agents?, maxParallelToolCalls?, persona?, toolOrder?, tools?, dshHome?, sessionTitle?, skills?, workspaceContext, toolBash?, toolTasks?, goals?, invariants?, llmRetry? }
+// { agents?, maxParallelToolCalls?, persona?, toolOrder?, tools?, dshHome?, sessionTitle?, skills?, workspaceContext, toolBash?, toolTasks?, goals?, invariants? }
 // workspaceContext requires { maxBytes } or false; the other owner schemas supply defaults.
 ```
 
-组合包将每个字段转发给拥有它的子节点：`agents` 与 `maxParallelToolCalls` 交给 `agent-loop`（`agents` 默认为 `[]`，上限在该处默认），因此每个应用提供自己的预创建 agent；TUI 和无头应用预创建 `main`，ACP 应用则在 `session/new` 按需创建 agent；`llmRetry` 交给有界重试策略；`persona` 与 `toolOrder` 交给 `dsh-system-prompt`；`tools` 交给工具注册表以配置呈现 mode；`sessionTitle` 交给后备标题服务；`skills.registry`、`skills.local` 与 `skills.tool` 分别交给 skill 注册表、本地提供方和面向模型的消费方；必填的 `workspaceContext` 选择交给 `dsh-workspace-context`（`{ maxBytes }` 启用加载，`false` 禁用）；`invariants` 交给不变式服务；`toolBash`/`toolTasks` 交给组合包拥有的两个面向模型工具插件。省略 `sessionTitle` 时采用显式示例策略：5 个词、40 个后备字节、80 个可接受标题字节。`goals` 对象会选用持久领域、模型工具和同会话驱动器，并将 `goals.domain` 与 `goals.tool` 转发给各自拥有者；省略或设为 `false` 会让整个栈缺席，使无头调用方继续以一轮结算。设置 `skills.enabled: false` 会同时省略本地提供方和面向模型的 skill 工具；设置 `toolTasks: false` 会保留供前台生产方使用的任务服务，但不公开 `task_output`/`task_list`/`task_kill`。它对 `dshHome` 只解析一次，解析通过 [`@deepseek-ai/dsh-paths`](../../util/paths/README.md) 完成，并将所得绝对值转发给 tool-bash 的托管环境和已启用的本地 skill 发现。顶层 `dshHome` 缺席时采用 `skills.local.dshHome`；两者同时提供但解析后的路径不同会明确失败。`toolBash.enableRunInBackground` 只控制 bash 生产方；独立加载的生产方保留各自配置。Workspace 指令先于 skill 目录注册，因此其会话前缀消息先渲染。应用包使用 `pickSpineConfig()`，只复制这些由组合包拥有的字段。
+组合包将每个字段转发给拥有它的子节点：`agents` 与 `maxParallelToolCalls` 交给 `agent-loop`（`agents` 默认为 `[]`，上限在该处默认），因此每个应用提供自己的预创建 agent；TUI 和无头应用预创建 `main`，ACP 应用则在 `session/new` 按需创建 agent；`persona` 与 `toolOrder` 交给 `dsh-system-prompt`；`tools` 交给工具注册表以配置呈现 mode；`sessionTitle` 交给后备标题服务；`skills.registry`、`skills.local` 与 `skills.tool` 分别交给 skill 注册表、本地提供方和面向模型的消费方；必填的 `workspaceContext` 选择交给 `dsh-workspace-context`（`{ maxBytes }` 启用加载，`false` 禁用）；`invariants` 交给不变式服务；`toolBash`/`toolTasks` 交给组合包拥有的两个面向模型工具插件。组合包始终挂载 `dsh-llm-retry`，而每个叶节点适配器拥有自己的嵌套 `retryPolicy`。省略 `sessionTitle` 时采用显式示例策略：5 个词、40 个后备字节、80 个可接受标题字节。`goals` 对象会选用持久领域、模型工具和同会话驱动器，并将 `goals.domain` 与 `goals.tool` 转发给各自拥有者；省略或设为 `false` 会让整个栈缺席，使无头调用方继续以一轮结算。设置 `skills.enabled: false` 会同时省略本地提供方和面向模型的 skill 工具；设置 `toolTasks: false` 会保留供前台生产方使用的任务服务，但不公开 `task_output`/`task_list`/`task_kill`。它对 `dshHome` 只解析一次，解析通过 [`@deepseek-ai/dsh-paths`](../../util/paths/README.md) 完成，并将所得绝对值转发给 tool-bash 的托管环境和已启用的本地 skill 发现。顶层 `dshHome` 缺席时采用 `skills.local.dshHome`；两者同时提供但解析后的路径不同会明确失败。`toolBash.enableRunInBackground` 只控制 bash 生产方；独立加载的生产方保留各自配置。Workspace 指令先于 skill 目录注册，因此其会话前缀消息先渲染。应用包使用 `pickSpineConfig()`，只复制这些由组合包拥有的字段。
 
 例如，`{ invariants: { enabled: true, package_allowlist: ['^@deepseek-ai/dsh-'], package_blocklist: ['agent-loop$'] } }` 会让包拥有的配套插件保持挂载，但抑制被阻止的拥有者。Blocklist 匹配优先于 allowlist 匹配；正则表达式与生命周期规则见 [`dsh-invariants`](../../support/invariants/README.md)。
 
@@ -67,7 +67,7 @@ import type { Config } from '@deepseek-ai/dsh-agent-spine-demo'
 
 YAML include 可以去重配置，却无法拥有 bin 或提供前端入口默认值。ACP 应用包默认接出协议纯净的 stdout，但叶节点仍可添加不安全的 logger。组合包子节点把服务注册到根 isolate-keyed store，因此注入这些服务的叶节点同级插件无需依赖加载顺序即可看到它们。
 
-有界重试策略可能在新的编号步骤中重复瞬时失败的请求。重试状态和失败的部分 chunk 不进入模型历史；每次提供方尝试仍可能产生计费；前端入口从所有已记录步骤推导用量；重建的请求保留先前前缀，以便复用提供方 cache。
+重试策略可能在新的编号步骤中重复失败的请求。重试状态、提供方错误和失败的部分 chunk 不进入模型历史；每次提供方尝试仍可能产生计费；always mode 没有尝试次数上限；前端入口从所有已记录步骤推导用量；重建的请求保留先前前缀，以便复用提供方 cache。
 
 ## 模型体验
 

packages/examples/agent-spine-demo/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-agent-spine-demo",
-  "description": "The default executor-less/UI-less agent spine with fallback session titles, bounded retry, and optional persisted goals",
+  "description": "The default executor-less/UI-less agent spine with fallback session titles, provider-routed retry, and optional persisted goals",
   "version": "0.0.1",
   "private": true,
   "type": "module",

packages/examples/agent-spine-demo/src/index.ts

@@ -74,8 +74,9 @@ export interface GoalConfig {
  * `dshHome` to bash environment and local skill discovery, `sessionTitle` to
  * the fallback title service, `skills` to the
  * skill registry/local provider/tool consumer, `workspaceContext` to the
- * workspace-context loader, `llmRetry` to the bounded request-recovery policy,
- * and `toolBash`/`toolTasks` to the model-facing tool plugins this bundle owns.
+ * workspace-context loader, and `toolBash`/`toolTasks` to the model-facing tool
+ * plugins this bundle owns. Provider adapters own their `retryPolicy`; this
+ * bundle always mounts its executor.
  * `goals` opts into and configures the persisted goal domain plus its model tool
  * and same-session driver; `invariants` configures global and package-filtered
  * relational checks. Owner schemas supply defaults for optional input;
@@ -111,8 +112,6 @@ export interface Config {
   invariants?: InvariantConfig
   /** Opt-in persisted same-session goal stack; set false or omit to leave it unmounted. */
   goals?: GoalConfig | false
-  /** Bounded transient model-request retry policy. */
-  llmRetry?: llmRetry.Config
 }
 
 /** The skill config schema exported for app packages that forward `skills`. */
@@ -139,9 +138,6 @@ export const GoalConfigSchema: z<GoalConfig> = z.object({
   tool: toolGoal.Config,
 })
 
-/** The bounded LLM retry schema exported for app packages that forward `llmRetry`. */
-export const LlmRetryConfigSchema: z<llmRetry.Config> = llmRetry.Config
-
 /** Intersect the owners' schemas so validation + defaulting stay identical. */
 export const Config = z.intersect([
   AgentLoop.Config,
@@ -156,8 +152,7 @@ export const Config = z.intersect([
     toolTasks: z.union([z.const(false), ToolTasksConfigSchema]),
     invariants: InvariantService.Config,
     goals: z.union([z.const(false), GoalConfigSchema]),
-    llmRetry: LlmRetryConfigSchema,
-  }) as unknown as z<Pick<Config, 'tools' | 'dshHome' | 'sessionTitle' | 'skills' | 'workspaceContext' | 'toolBash' | 'toolTasks' | 'invariants' | 'goals' | 'llmRetry'>>,
+  }) as unknown as z<Pick<Config, 'tools' | 'dshHome' | 'sessionTitle' | 'skills' | 'workspaceContext' | 'toolBash' | 'toolTasks' | 'invariants' | 'goals'>>,
 ]) as unknown as z<Config>
 
 /**
@@ -179,7 +174,6 @@ export function pickSpineConfig(config: Omit<Config, 'agents'>): Omit<Config, 'a
     ...config.toolTasks !== undefined ? { toolTasks: config.toolTasks } : {},
     ...config.invariants !== undefined ? { invariants: config.invariants } : {},
     ...config.goals !== undefined ? { goals: config.goals } : {},
-    ...config.llmRetry !== undefined ? { llmRetry: config.llmRetry } : {},
   }
 }
 
@@ -217,7 +211,7 @@ export function apply(ctx: Context, config: Config): void {
     ctx.plugin(SkillLocal, Object.assign({}, config.skills?.local, { dshHome }))
   }
   ctx.plugin(AgentRegistry)
-  ctx.plugin(llmRetry, config.llmRetry ?? {})
+  ctx.plugin(llmRetry)
   if (config.goals !== undefined && config.goals !== false) {
     ctx.plugin(GoalService, config.goals.domain ?? {})
     ctx.plugin(toolGoal, config.goals.tool ?? {})

packages/examples/agent-spine-demo/tests/agent-core.spec.ts

@@ -10,7 +10,16 @@ import { agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
 import { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
-import { CallId, LlmAdapter, LlmError, type GenerateOptions, type Message, type StreamChunk } from '@deepseek-ai/dsh-llm'
+import {
+  CallId,
+  LlmAdapter,
+  LlmError,
+  resolveRetryPolicy,
+  type GenerateOptions,
+  type Message,
+  type ResolvedRetryPolicy,
+  type StreamChunk,
+} from '@deepseek-ai/dsh-llm'
 import type { ToolExecution } from '@deepseek-ai/dsh-tools'
 import * as sessionInvariant from '@deepseek-ai/dsh-session/invariant'
 import * as agentInvariant from '@deepseek-ai/dsh-agent/invariant'
@@ -106,6 +115,15 @@ function messageText(message: Message | undefined): string {
 
 class TransientOnceAdapter extends LlmAdapter {
   requests = 0
+  private readonly retryPolicy = resolveRetryPolicy({
+    mode: 'normal',
+    maxRetries: 1,
+    backoff: { initialDelayMs: 1, maxDelayMs: 1, jitterRatio: 0 },
+  }, 'agent-spine test provider retryPolicy')
+
+  override providerRetryPolicy(_provider: string): ResolvedRetryPolicy {
+    return this.retryPolicy
+  }
 
   async * stream(_options: GenerateOptions): AsyncIterable<StreamChunk> {
     this.requests += 1
@@ -209,15 +227,7 @@ describe('dsh-agent-spine-demo bundle', () => {
 
   it('loads and configures bounded request recovery for every bundled front door', async () => {
     const adapter = new TransientOnceAdapter()
-    const ctx = await mount({
-      workspaceContext: false,
-      llmRetry: {
-        maxTransientRetries: 1,
-        initialDelayMs: 1,
-        maxDelayMs: 1,
-        jitterRatio: 0,
-      },
-    })
+    const ctx = await mount({ workspaceContext: false })
     ctx.llm.registerAdapter(['mock'], adapter)
     const handle = await ctx.agents.create({
       sessionId: SessionId('bundled-retry-session'),
@@ -232,7 +242,7 @@ describe('dsh-agent-spine-demo bundle', () => {
     const retryEvents = handle.agent.session.events.filter(event => event.type === 'llm/retry')
     expect(retryEvents).toHaveLength(1)
     expect(retryEvents[0]?.data.retry).toBe(1)
-    expect(retryEvents[0]?.data.maxRetries).toBe(1)
+    expect(retryEvents[0]?.data).toMatchObject({ provider: 'mock', mode: 'normal', maxRetries: 1 })
     expect(handle.agent.session.events.find(event => event.type === 'session/title')?.data.title).toBe('recover')
     expect(messageText(handle.agent.session.deriveMessages().at(-1))).toBe('recovered by bundled policy')
     await handle.dispose()
@@ -513,7 +523,6 @@ describe('dsh-agent-spine-demo bundle', () => {
       toolBash: { enableRunInBackground: false },
       toolTasks: false as const,
       invariants: { enabled: false },
-      llmRetry: { maxTransientRetries: 1, jitterRatio: 0 },
     }
 
     expect(agentCore.pickSpineConfig(appConfig)).toEqual({
@@ -527,7 +536,6 @@ describe('dsh-agent-spine-demo bundle', () => {
       toolBash: appConfig.toolBash,
       toolTasks: appConfig.toolTasks,
       invariants: appConfig.invariants,
-      llmRetry: appConfig.llmRetry,
     })
     expect(agentCore.pickSpineConfig({ workspaceContext: false })).toEqual({ workspaceContext: false })
   })

packages/examples/cli-demo/README.i18n.yaml

@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # 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
-README.md: 4e8e5388e17ab2879582286adf593c72fb2cf78f
-README.zh.md: 3cad72071184403a78b7906d637bba67bea1a64a
+#   pnpm run verify-translation-pairing --write packages/examples/cli-demo/README.md
+README.md: b8f2bde962738a1a23f0e57218ab0f90e8e0b705
+README.zh.md: 322ba3fb3b253d867832534bd33f65df3a5b8d37

packages/examples/cli-demo/README.md

@@ -21,7 +21,6 @@ The package mounts no console logger, interactive UI, user-interaction service,
 | `skills` | owner defaults | skill registry, local provider, and model-facing skill tool |
 | `toolBash` | owner defaults | model-facing bash config, including this producer's background opt-in |
 | `toolTasks` | owner defaults | generic `task_output` wait bounds |
-| `llmRetry` | owner defaults | bounded transient model-request retry policy |
 | `persistenceRoot` | `./.sessions` | JSONL session root |
 | `persistenceCompression` | `'zstd'` | JSONL artifact encoding (`'zstd'` or raw `'none'`) |
 | `workspaceContext` | required | workspace-instruction byte budget, or `false` to disable loading |

packages/examples/cli-demo/README.zh.md

@@ -21,7 +21,6 @@
 | `skills` | 拥有者默认值 | Skill 注册表、本地提供方和面向模型的 skill 工具 |
 | `toolBash` | 拥有者默认值 | 面向模型的 bash 配置，包括此生产方对后台任务的选用 |
 | `toolTasks` | 拥有者默认值 | 通用 `task_output` 等待边界 |
-| `llmRetry` | 拥有者默认值 | 有界的瞬时模型请求重试策略 |
 | `persistenceRoot` | `./.sessions` | JSONL 会话根目录 |
 | `persistenceCompression` | `'zstd'` | JSONL 工件编码（`'zstd'` 或原始 `'none'`） |
 | `workspaceContext` | 必填 | Workspace 指令字节预算，或以 `false` 禁用加载 |

packages/examples/cli-demo/src/index.ts

@@ -50,8 +50,6 @@ export interface Config {
   toolBash?: NonNullable<agentCore.Config['toolBash']>
   /** Generic background-task control-tool config forwarded through agent-spine-demo. */
   toolTasks?: NonNullable<agentCore.Config['toolTasks']>
-  /** Bounded transient model-request retry policy forwarded through agent-spine-demo. */
-  llmRetry?: NonNullable<agentCore.Config['llmRetry']>
   /** Controls automatic AGENTS.md/CLAUDE.md loading; configure a byte budget or set `false`. */
   workspaceContext: agentCore.Config['workspaceContext']
 }
@@ -74,7 +72,6 @@ export const Config: z<Config> = z.object({
   tools: ToolRegistry.Config,
   toolBash: agentCore.ToolBashConfigSchema,
   toolTasks: z.union([z.const(false), agentCore.ToolTasksConfigSchema]),
-  llmRetry: agentCore.LlmRetryConfigSchema,
   workspaceContext: z.union([z.const(false), workspaceContext.Config]).required(),
 })
 /* jscpd:ignore-end */

packages/examples/cli-demo/tests/cli.spec.ts

@@ -3,7 +3,15 @@ import { tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
 import { Context } from 'cordis'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import { CallId, LlmAdapter, type GenerateOptions, type StreamChunk, type TokenUsage } from '@deepseek-ai/dsh-llm'
+import {
+  CallId,
+  LlmAdapter,
+  resolveRetryPolicy,
+  type GenerateOptions,
+  type ResolvedRetryPolicy,
+  type StreamChunk,
+  type TokenUsage,
+} from '@deepseek-ai/dsh-llm'
 import { SessionId, type SessionEvent, type TurnEndReason } from '@deepseek-ai/dsh-session'
 import { afterEach, describe, expect, it } from 'vitest'
 import * as cliDemo from '../src/index.ts'
@@ -20,11 +28,19 @@ type ScriptEntry = readonly StreamChunk[] | 'hang'
 class ScriptedAdapter extends LlmAdapter {
   readonly requests: GenerateOptions[] = []
   private cursor = 0
+  private readonly retryPolicy = resolveRetryPolicy({
+    mode: 'normal',
+    backoff: { initialDelayMs: 1, maxDelayMs: 1, jitterRatio: 0 },
+  }, 'cli test provider retryPolicy')
 
   constructor(private readonly script: readonly ScriptEntry[]) {
     super()
   }
 
+  override providerRetryPolicy(_provider: string): ResolvedRetryPolicy {
+    return this.retryPolicy
+  }
+
   async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
     this.requests.push(options)
     const entry = this.script[this.cursor++]
@@ -107,7 +123,6 @@ async function harness(script: readonly ScriptEntry[]): Promise<Harness> {
     persistenceRoot: root,
     skills: { local: { dshHome: join(skillHome, '.dsh'), agentsHome: join(skillHome, '.agents') } },
     workspaceContext: false,
-    llmRetry: { initialDelayMs: 1, maxDelayMs: 1, jitterRatio: 0 },
   })
   await new Promise(resolve => setTimeout(resolve, 80))
   ctx.llm.registerAdapter(['mock'], new ScriptedAdapter(script))

packages/examples/tui-demo/src/index.ts

@@ -131,6 +131,7 @@ export function composeTuiApp(ctx: Context, config: Config): void {
   ctx.plugin(SessionQuerySqlite, { path: join(persistenceRoot, 'session-query.db') })
   ctx.plugin(SessionReferenceService, config.sessionReferences ?? {})
   ctx.plugin(UserInteractionService)
+  ctx.plugin(uiTui.TuiPromptService)
   ctx.plugin(uiTui, {
     ...config.ui,
     ...config.welcome === undefined ? {} : { welcome: config.welcome },

packages/examples/tui-demo/tests/tui-agent.spec.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { join } from 'node:path'
-import type { Context } from 'cordis'
+import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
 import * as tuiAgent from '../src/index.ts'
@@ -40,7 +40,7 @@ describe('dsh-tui-demo app', () => {
       },
       welcome: 'TUI ready',
       resumeCommand: 'dsh --resume {session}',
-      ui: { color: false, maxToolOutputLines: 3 },
+      ui: { theme: { color: false }, maxToolOutputLines: 3 },
       skills: { tool: { catalogDescriptionMaxLength: 8 } },
       toolBash: { enableRunInBackground: false },
       toolTasks: { waitTimeoutMs: 7, maxWaitTimeoutMs: 11 },
@@ -55,6 +55,7 @@ describe('dsh-tui-demo app', () => {
       'SessionQuerySqlite',
       'SessionReferenceService',
       'UserInteractionService',
+      'TuiPromptService',
       'ui-tui',
       'agent-spine-demo',
       'tool-ask-user',
@@ -67,15 +68,15 @@ describe('dsh-tui-demo app', () => {
       candidateLimit: 7,
       maxReferenceBytes: 1234,
     })
-    const tuiConfig = calls[7]?.config as { sessionId: string }
+    const tuiConfig = calls[8]?.config as { sessionId: string }
     expect(tuiConfig).toMatchObject({
       welcome: 'TUI ready',
       resumeCommand: 'dsh --resume {session}',
-      color: false,
+      theme: { color: false },
       maxToolOutputLines: 3,
     })
     expect(tuiConfig.sessionId).toMatch(/^main-session-[0-9a-f-]{36}$/)
-    const spineConfig = calls[8]?.config as {
+    const spineConfig = calls[9]?.config as {
       readonly agents: Array<Record<string, unknown>>
       readonly goals: Record<string, never>
       readonly maxParallelToolCalls: number
@@ -111,8 +112,8 @@ describe('dsh-tui-demo app', () => {
     expect(calls[2]?.config).toEqual({ root: './.sessions' })
     expect(calls[5]?.config).toEqual({})
     // No configured welcome forwards none: the TUI banner sweeps in without a subtitle.
-    expect(calls[7]?.config).toEqual({ sessionId: 'persisted-session' })
-    expect((calls[8]?.config as { agents: Array<Record<string, unknown>> }).agents[0]).toMatchObject({
+    expect(calls[8]?.config).toEqual({ sessionId: 'persisted-session' })
+    expect((calls[9]?.config as { agents: Array<Record<string, unknown>> }).agents[0]).toMatchObject({
       id: 'main',
       resumeSessionId: 'persisted-session',
     })
@@ -128,12 +129,12 @@ describe('dsh-tui-demo app', () => {
       workspaceContext: false,
     })
 
-    const tuiConfig = calls[6]?.config as { sessionId: string }
+    const tuiConfig = calls[7]?.config as { sessionId: string }
     expect(tuiConfig.sessionId).toMatch(/^main-session-[0-9a-f-]{36}$/)
-    expect((calls[7]?.config as { agents: Array<Record<string, unknown>> }).agents[0])
+    expect((calls[8]?.config as { agents: Array<Record<string, unknown>> }).agents[0])
       .toMatchObject({ sessionId: tuiConfig.sessionId })
     expect(calls.map(call => call.name)).not.toContain('command-goal')
-    expect(calls[7]?.config).toMatchObject({ goals: false })
+    expect(calls[8]?.config).toMatchObject({ goals: false })
   })
 
   it('has the namespace-plugin export shape so the Loader keeps its schema', () => {

packages/fs/tool-fs/src/read.ts

@@ -6,7 +6,7 @@
 
 import type { Context } from 'cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { GenericCallView } from '@deepseek-ai/dsh-tools'
+import type { GenericCallView, GenericResultView, ToolResult } from '@deepseek-ai/dsh-tools'
 import { FsError } from '@deepseek-ai/dsh-fs'
 import type {} from '@deepseek-ai/dsh-fs'
 import type {} from '@deepseek-ai/dsh-system-prompt'
@@ -154,6 +154,16 @@ export function applyReadTool(ctx: Context, caps: ReadToolCaps): void {
       ctx.emit('fs/observed', target, info.version, exec)
       return outcome
     },
+    presentResult(_args, result: ToolResult): GenericResultView | undefined {
+      if (result.isError) return undefined
+      const only = result.content.length === 1 ? result.content[0] : undefined
+      const text = only?.type === 'text' ? only.text : undefined
+      if (text === undefined) return undefined
+      // Group 1 always captures (possibly empty) when the envelope matches.
+      const body = /^<path>[^\n]*<\/path>\n<type>file<\/type>\n<content>\n([\s\S]*)\n<\/content>$/u.exec(text)?.[1]
+      if (body === undefined) return undefined
+      return { card: 'generic', content: [{ type: 'text', text: body }] }
+    },
     // Pure display: a generic card titled by the file with the read window appended (`Read
     // foo.txt (5 - 8)`), `read` kind (icon), and a follow-along location whose line is the
     // read's offset (defaulting to 1). The window reflects raw args, so an omitted limit keeps

packages/fs/tool-fs/tests/tools.spec.ts

@@ -10,7 +10,7 @@ import { tmpdir } from 'node:os'
 import { join, resolve, sep } from 'node:path'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import SystemPrompt, { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { type ToolResult } from '@deepseek-ai/dsh-tools'
 import { FileSystem, FsError, FsTargetKey, FsVersion } from '@deepseek-ai/dsh-fs'
 import type {
   FsDirEntry,
@@ -432,6 +432,11 @@ describe('tool-owned presentation (pure presentCall)', () => {
     return ctx.tools.get(name)?.presentCall?.(args)
   }
 
+  const presentResult = async (name: string, args: unknown, result: ToolResult) => {
+    const { ctx } = await setup()
+    return ctx.tools.get(name)?.presentResult?.(args, result)
+  }
+
   it('read: generic card titled by file with the read window, read kind, location with the offset line', async () => {
     expect(await presentCall('read', { file_path: 'src/a.ts', offset: 12, limit: 40 })).toEqual({
       card: 'generic', title: 'Read src/a.ts (12 - 51)', kind: 'read',
@@ -445,6 +450,36 @@ describe('tool-owned presentation (pure presentCall)', () => {
     })
   })
 
+  it('read: completed presentation removes the model-facing XML envelope', async () => {
+    expect(await presentResult('read', { file_path: 'a.txt' }, {
+      content: [{ type: 'text', text: '<path>/tmp/a.txt</path>\n<type>file</type>\n<content>\n1: hello\n\n(End of file - total 1 lines)\n</content>' }],
+      isError: false,
+    })).toEqual({
+      card: 'generic',
+      content: [{ type: 'text', text: '1: hello\n\n(End of file - total 1 lines)' }],
+    })
+    expect(await presentResult('read', { file_path: 'a.txt' }, {
+      content: [{ type: 'text', text: 'malformed replay' }],
+      isError: false,
+    })).toBeUndefined()
+  })
+
+  it('read: completed presentation declines errors and non-single-text content', async () => {
+    const envelope = '<path>/tmp/a.txt</path>\n<type>file</type>\n<content>\nbody\n</content>'
+    expect(await presentResult('read', { file_path: 'a.txt' }, {
+      content: [{ type: 'text', text: envelope }],
+      isError: true,
+    })).toBeUndefined()
+    expect(await presentResult('read', { file_path: 'a.txt' }, {
+      content: [{ type: 'text', text: envelope }, { type: 'text', text: 'second' }],
+      isError: false,
+    })).toBeUndefined()
+    expect(await presentResult('read', { file_path: 'a.txt' }, {
+      content: [{ type: 'reasoning', text: envelope }],
+      isError: false,
+    })).toBeUndefined()
+  })
+
   it('read: "from line N" window when only offset is set', async () => {
     expect(await presentCall('read', { file_path: 'a.txt', offset: 5 })).toEqual({
       card: 'generic', title: 'Read a.txt (from line 5)', kind: 'read', locations: [{ path: 'a.txt', line: 5 }],

packages/llm/README.i18n.yaml

@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # 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
-README.md: 13a04aa9f73fec5824069644449009989d6fd924
-README.zh.md: 3e417c5f8be1f7831b99940c2a4aec815dc2c5b6
+#   pnpm run verify-translation-pairing --write packages/llm/README.md
+README.md: 66b7beabd73cc3fec7230f209a9da0da48a37c95
+README.zh.md: 48c54358ce3e8e21e33a6ef5b75a7e095b6581d5

packages/llm/README.md

@@ -8,8 +8,8 @@ The LLM seam and its provider adapters. The interface package (`llm`) owns the a
 |---|---|---|
 | `llm/` | Abstract LLM service + content-block vocabulary + chunk assembler | `ctx.llm` |
 | `token-meter/` | Replay-aware request and surface token measurement | `ctx.tokenMeter` |
-| `llm-retry/` | Bounded transient request retry policy | (listens to `agent/request-error`) |
+| `llm-retry/` | Exact-provider normal or unbounded request retry policy | (listens to `agent/request-error`) |
 | `llm-deepseek/` | DeepSeek API adapter (direct fetch + eventsource-parser SSE) | (registers on `ctx.llm`) |
 | `llm-pi-ai/` | Multi-provider adapter via `@earendil-works/pi-ai` | (registers on `ctx.llm`) |
 
-The interface lives at `llm/llm/`; adapters, retry policy, and the reusable token meter are flat siblings under the group. Requests route by `provider`, while `model` is passed through to the selected adapter. The route-owning adapter optionally resolves exact provider/model context capacity; the token meter remains model-agnostic. A new provider adapter registers one or more provider routes on `ctx.llm` without touching the interface or consumers. See [twin LLM adapters](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md) for the two shipping implementations, the [replay token meter Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md) for measurement ownership, and the [routed model context Agent Note](../../.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md) for capacity and compaction-policy ownership.
+The interface lives at `llm/llm/`; adapters, retry policy, and the reusable token meter are flat siblings under the group. Requests route by `provider`, while `model` is passed through to the selected adapter. The route-owning adapter supplies retry policy and resolves available exact-model identity, context capacity, and reasoning metadata; the retry executor and token meter remain provider-agnostic. A new provider adapter registers one or more provider routes on `ctx.llm` without touching the consumers. See [twin LLM adapters](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md) for the two shipping implementations, the [replay token meter Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md) for measurement ownership, and the [routed model context Agent Note](../../.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md) for capacity and compaction-policy ownership.

packages/llm/README.zh.md

@@ -8,8 +8,8 @@ LLM seam 及其提供方适配器。接口包（`llm`）拥有抽象服务、内
 |---|---|---|
 | `llm/` | 抽象 LLM 服务 + 内容块词汇 + 分片组装器 | `ctx.llm` |
 | `token-meter/` | 感知回放的请求与表层 token 测量 | `ctx.tokenMeter` |
-| `llm-retry/` | 有界的暂时性请求重试策略 | （监听 `agent/request-error`） |
+| `llm-retry/` | 确切提供方的 normal 或无界请求重试策略 | （监听 `agent/request-error`） |
 | `llm-deepseek/` | DeepSeek API 适配器（直接 fetch + eventsource-parser SSE） | （注册到 `ctx.llm`） |
 | `llm-pi-ai/` | 通过 `@earendil-works/pi-ai` 实现的多提供方适配器 | （注册到 `ctx.llm`） |
 
-接口位于 `llm/llm/`；适配器、重试策略和可复用的 token 计量器都是该分组下的扁平兄弟包。请求按 `provider` 路由，而 `model` 会原样传给选中的适配器。拥有路由的适配器可以解析精确的提供方／模型上下文容量；token 计量器仍与模型无关。新的提供方适配器只需在 `ctx.llm` 上注册一个或多个提供方路由，无需改动接口或消费方。两个已交付实现见[双生 LLM 适配器](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)，测量归属见[回放 token 计量器 Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md)，容量与压缩策略归属见[路由模型上下文 Agent Note](../../.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md)。
+接口位于 `llm/llm/`；适配器、重试策略和可复用的 token 计量器都是该分组下的扁平兄弟包。请求按 `provider` 路由，而 `model` 会原样传给选中的适配器。拥有路由的适配器提供重试策略，并解析可用的确切模型身份、上下文容量和推理元数据；重试执行器与 token 计量器仍与提供方无关。新的提供方适配器只需在 `ctx.llm` 上注册一个或多个提供方路由，无需改动消费方。两个已交付实现见[双生 LLM 适配器](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)，测量归属见[回放 token 计量器 Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md)，容量与压缩策略归属见[路由模型上下文 Agent Note](../../.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md)。

packages/llm/llm-deepseek/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/llm/llm-deepseek/README.md
-README.md: 4358620295547248ca87c42e07022c5eab0c947b
-README.zh.md: 4ecc5dd2e5980751ca6e724b5041efefc8114077
+README.md: a7f2fcb9c21d45a95fc81abd3dc1424d4336966d
+README.zh.md: bca56e700c0067b644adb4d1460a47901db28209

packages/llm/llm-deepseek/README.md

@@ -19,6 +19,12 @@ The package root exposes the Cordis plugin contract and `DeepSeekAdapter`; wire
     thinking: enabled        # optional; provider default is enabled
     reasoningEffort: high    # optional; off | high | max — omitted ⇒ high
     streamIdleTimeoutMs: 300000 # optional; positive finite Node timer delay; five-minute default
+    retryPolicy:             # optional; omission uses bounded normal defaults
+      mode: always           # normal | always
+      backoff:
+        initialDelayMs: 500
+        maxDelayMs: 10000
+        jitterRatio: 0.1
     defaultContextWindow: 256000 # optional positive-integer fallback for models without an exact value
     models:                  # optional; defaults to V4 Flash and V4 Pro
       - id: deepseek-v4-flash
@@ -28,7 +34,7 @@ The package root exposes the Cordis plugin contract and `DeepSeekAdapter`; wire
         contextWindow: 64000
 ```
 
-The plugin registers the single provider route `deepseek`. A request selects it with `provider: deepseek`; its `model` is passed through as the wire `model` string, so changing DeepSeek models does not require lifecycle-time registration. Omitting `models` advertises `deepseek-v4-flash` and `deepseek-v4-pro`, each with a 128,000-token context window; an explicit list replaces those defaults, while `models: []` advertises none. Catalog entries are exposed through `ctx.llm.listModels('deepseek')` for UI selectors and deployment introspection, but remain advisory: unlisted model ids still pass through unchanged. An omitted entry name defaults to its id.
+The plugin registers the single provider route `deepseek` together with its resolved `retryPolicy`. A request selects it with `provider: deepseek`; its `model` is passed through as the wire `model` string, so changing DeepSeek models does not require lifecycle-time registration. Omitting `models` advertises `deepseek-v4-flash` and `deepseek-v4-pro`, each with a 128,000-token context window; an explicit list replaces those defaults, while `models: []` advertises none. Catalog entries are exposed through `ctx.llm.listModels('deepseek')` for UI selectors and deployment introspection, but remain advisory: unlisted model ids still pass through unchanged. An omitted entry name defaults to its id.
 
 `contextWindow` is optional per configured model and is not exposed through the advisory catalog. `ctx.llm.resolveModelInfo('deepseek', model).context` returns an exact model value first, then `defaultContextWindow` for an entry without capacity or an unlisted pass-through id. When neither value exists, `context` is absent without invalidating routing. Pressure-sensitive plugins therefore get deployment-owned capacity without treating the model selector as authoritative. Registering another adapter for `deepseek` throws `LlmError('DUPLICATE_ADAPTER')`.
 
@@ -36,7 +42,7 @@ The same exact-model result exposes ordered `off`, `high`, and `max` efforts und
 
 `thinking: disabled` is a deployment lock that publishes only `off` with `off` as its default. Omitting `reasoningEffort` or configuring it as `off` is valid; configuring `high` or `max` fails plugin loading, and a direct per-request attempt to enable thinking fails before network I/O. A request with `GenerateOptions.purpose: 'session-title'` also forces thinking disabled and omits the already-resolved effort, reserving its bounded output for visible title text without changing conversation or compaction defaults.
 
-`streamIdleTimeoutMs` bounds each outstanding provider read, including the initial `fetch`, without counting time the consumer spends between chunks. One stable abort signal reaches the request and body reader for the whole call; expiry stops the transport and throws `LlmError('TIMEOUT')`, while an earlier caller abort throws `LlmError('ABORTED')`. The adapter makes exactly one provider request per `stream()` call; agent-level retry is a separate plugin policy.
+`streamIdleTimeoutMs` bounds each outstanding provider read, including the initial `fetch`, without counting time the consumer spends between chunks. One stable abort signal reaches the request and body reader for the whole call; expiry stops the transport and throws `LlmError('TIMEOUT')`, while an earlier caller abort throws `LlmError('ABORTED')`. The adapter makes exactly one provider request per `stream()` call; it registers the configured policy as provider metadata, and `dsh-llm-retry` separately executes it at durable agent-step boundaries.
 
 ## App attribution
 

packages/llm/llm-deepseek/README.zh.md

@@ -19,6 +19,12 @@ harness LLM seam 的 DeepSeek chat-completions 适配器：直接 `fetch` + SSE
     thinking: enabled        # optional; provider default is enabled
     reasoningEffort: high    # optional; off | high | max — omitted ⇒ high
     streamIdleTimeoutMs: 300000 # optional; positive finite Node timer delay; five-minute default
+    retryPolicy:             # optional; omission uses bounded normal defaults
+      mode: always           # normal | always
+      backoff:
+        initialDelayMs: 500
+        maxDelayMs: 10000
+        jitterRatio: 0.1
     defaultContextWindow: 256000 # optional positive-integer fallback for models without an exact value
     models:                  # optional; defaults to V4 Flash and V4 Pro
       - id: deepseek-v4-flash
@@ -28,7 +34,7 @@ harness LLM seam 的 DeepSeek chat-completions 适配器：直接 `fetch` + SSE
         contextWindow: 64000
 ```
 
-该插件注册唯一提供方路由 `deepseek`。请求使用 `provider: deepseek` 选择该路由；其 `model` 会作为协议 `model` 字符串原样传递，因此更改 DeepSeek 模型不需要生命周期时注册。省略 `models` 会公布 `deepseek-v4-flash` 和 `deepseek-v4-pro`，两者的上下文窗口均为 128,000 token；显式列表会替换这些默认值，`models: []` 则不公布任何模型。Catalog 配置项通过 `ctx.llm.listModels('deepseek')` 公开给 UI selector 与部署自省，但仍只提供建议：未列出模型 id 仍原样传递。省略配置项 name 默认为其 id。
+该插件注册唯一提供方路由 `deepseek`，同时注册解析后的 `retryPolicy`。请求使用 `provider: deepseek` 选择该路由；其 `model` 会作为协议 `model` 字符串原样传递，因此更改 DeepSeek 模型不需要生命周期时注册。省略 `models` 会公布 `deepseek-v4-flash` 和 `deepseek-v4-pro`，两者的上下文窗口均为 128,000 token；显式列表会替换这些默认值，`models: []` 则不公布任何模型。Catalog 配置项通过 `ctx.llm.listModels('deepseek')` 公开给 UI selector 与部署自省，但仍只提供建议：未列出模型 id 仍原样传递。省略配置项 name 默认为其 id。
 
 `contextWindow` 对每个已配置模型都可选，不会通过建议 catalog 公开。`ctx.llm.resolveModelInfo('deepseek', model).context` 先返回精确模型值，再对不含容量的配置项或未列出原样传递 id 返回 `defaultContextWindow`。两者都不存在时，`context` 字段缺失但不会使路由失效。因此，压力敏感插件可以获得部署拥有的容量，不会将模型 selector 视为权威。为 `deepseek` 注册另一个适配器会抛出 `LlmError('DUPLICATE_ADAPTER')`。
 
@@ -36,7 +42,7 @@ harness LLM seam 的 DeepSeek chat-completions 适配器：直接 `fetch` + SSE
 
 `thinking: disabled` 是部署锁定：它只公布 `off`，并以 `off` 为默认值。省略 `reasoningEffort` 或将其配置为 `off` 均有效；配置 `high` 或 `max` 会使插件加载失败，直接按请求启用思考也会在网络 I/O 前失败。携带 `GenerateOptions.purpose: 'session-title'` 的请求也会强制禁用思考并省略已解析的推理强度，将有界输出保留给可见标题文本，不改变会话或压缩默认值。
 
-`streamIdleTimeoutMs` 会限制每次未完成提供方读取，包括初始 `fetch`，但不计入消费方在 chunk 间花费的时间。一个稳定 abort 信号会在整个调用中达到请求与 body reader；过期会停止传输并抛出 `LlmError('TIMEOUT')`，较早的调用方 abort 则抛出 `LlmError('ABORTED')`。适配器每次 `stream()` 调用精确发起一次提供方请求；agent 级重试是独立插件策略。
+`streamIdleTimeoutMs` 会限制每次未完成提供方读取，包括初始 `fetch`，但不计入消费方在 chunk 间花费的时间。一个稳定 abort 信号会在整个调用中达到请求与 body reader；过期会停止传输并抛出 `LlmError('TIMEOUT')`，较早的调用方 abort 则抛出 `LlmError('ABORTED')`。适配器每次 `stream()` 调用精确发起一次提供方请求；它把已配置策略注册为提供方元数据，再由 `dsh-llm-retry` 在持久 agent 步骤边界单独执行该策略。
 
 ## 应用归因
 

packages/llm/llm-deepseek/src/adapter.ts

@@ -5,12 +5,14 @@
  * @module dsh-llm-deepseek/adapter
  */
 
-import { attributionHeaders, CONTEXT_WINDOW_EXCEEDED_CODE, isContextWindowExceededError, isQuotaExceededError, LlmAdapter, LlmError, ProviderRequestId, QUOTA_EXCEEDED_CODE, ReasoningEffortId } from '@deepseek-ai/dsh-llm'
+import { attributionHeaders, CONTEXT_WINDOW_EXCEEDED_CODE, isContextWindowExceededError, isQuotaExceededError, LlmAdapter, LlmError, ProviderRequestId, QUOTA_EXCEEDED_CODE, ReasoningEffortId, resolveRetryPolicy } from '@deepseek-ai/dsh-llm'
 import type {
   GenerateOptions,
   LlmModelInfo,
   LlmProviderInfo,
   LlmResolvedModelInfo,
+  ResolvedRetryPolicy,
+  RetryPolicyConfig,
   StreamChunk,
 } from '@deepseek-ai/dsh-llm'
 import { idleWatchdog, MAX_TIMER_DELAY_MS, timeoutOf } from '@deepseek-ai/dsh-timeout'
@@ -46,6 +48,8 @@ export interface DeepSeekAdapterOptions {
   models?: readonly DeepSeekCatalogModel[]
   /** Maximum provider idle time while one stream read is outstanding. */
   streamIdleTimeoutMs?: number
+  /** Provider-owned model-request retry policy; omission uses normal defaults. */
+  retryPolicy?: RetryPolicyConfig
 }
 
 /** Default maximum idle interval while an adapter stream read is outstanding. */
@@ -115,6 +119,7 @@ export function httpErrorCode(status: number, error?: WireError['error']): strin
  */
 export class DeepSeekAdapter extends LlmAdapter {
   private readonly streamIdleTimeoutMs: number
+  private readonly retryPolicy: ResolvedRetryPolicy
 
   constructor(private readonly options: DeepSeekAdapterOptions) {
     super()
@@ -135,12 +140,17 @@ export class DeepSeekAdapter extends LlmAdapter {
         `llm-deepseek: streamIdleTimeoutMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`,
       )
     }
+    this.retryPolicy = resolveRetryPolicy(options.retryPolicy, 'llm-deepseek: retryPolicy')
   }
 
   override providerInfo(provider: string): LlmProviderInfo {
     return { id: provider, name: 'DeepSeek' }
   }
 
+  override providerRetryPolicy(_provider: string): ResolvedRetryPolicy {
+    return this.retryPolicy
+  }
+
   override listModels(provider: string): Promise<readonly LlmModelInfo[]> {
     return Promise.resolve((this.options.models ?? []).map(model => modelInfo(provider, model)))
   }

packages/llm/llm-deepseek/src/index.ts

@@ -7,7 +7,8 @@
 
 import type { Context } from 'cordis'
 import z from 'schemastery'
-import type {} from '@deepseek-ai/dsh-llm'
+import { RetryPolicySchema } from '@deepseek-ai/dsh-llm'
+import type { RetryPolicyConfig } from '@deepseek-ai/dsh-llm'
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import { DEFAULT_STREAM_IDLE_TIMEOUT_MS, DeepSeekAdapter } from './adapter.ts'
 import type { DeepSeekCatalogModel } from './adapter.ts'
@@ -47,6 +48,8 @@ export interface Config {
   models?: DeepSeekCatalogModel[]
   /** Maximum provider idle time while one stream read is outstanding (default five minutes). */
   streamIdleTimeoutMs?: number
+  /** Provider-owned model-request retry policy; omission uses normal defaults. */
+  retryPolicy?: RetryPolicyConfig
 }
 
 const catalogModel: z<DeepSeekCatalogModel> = z.object({
@@ -64,6 +67,7 @@ export const Config: z<Config> = z.object({
   defaultContextWindow: z.number().step(1).min(1),
   models: z.array(catalogModel).default(DEFAULT_MODELS),
   streamIdleTimeoutMs: z.number().min(Number.MIN_VALUE).max(MAX_TIMER_DELAY_MS).default(DEFAULT_STREAM_IDLE_TIMEOUT_MS),
+  retryPolicy: RetryPolicySchema,
 })
 
 /** Public API default; the internal endpoint comes from $DEEPSEEK_BASE_URL. */
@@ -117,5 +121,6 @@ export function apply(ctx: Context, config: Config): void {
       : { defaultContextWindow: config.defaultContextWindow },
     models: resolveModels(config.models),
     streamIdleTimeoutMs: config.streamIdleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS,
+    ...config.retryPolicy === undefined ? {} : { retryPolicy: config.retryPolicy },
   }))
 }

packages/llm/llm-deepseek/tests/adapter.spec.ts

@@ -602,6 +602,26 @@ describe('plugin registration and config', () => {
     expect(ctx.llm.listProviders()).toEqual([])
   })
 
+  it('registers retryPolicy from the provider config', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    await ctx.plugin(LlmDeepSeek, {
+      apiKey: 'k',
+      baseURL: 'http://127.0.0.1:1',
+      retryPolicy: {
+        mode: 'always',
+        backoff: { initialDelayMs: 25, maxDelayMs: 100, jitterRatio: 0.2 },
+      },
+    })
+
+    expect(ctx.llm.providerRetryPolicy('deepseek')).toEqual({
+      mode: 'always',
+      initialDelayMs: 25,
+      maxDelayMs: 100,
+      jitterRatio: 0.2,
+    })
+  })
+
   it('owns the deepseek provider and advertises the default models', async () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
@@ -908,4 +928,16 @@ describe('plugin registration and config', () => {
       streamIdleTimeoutMs: MAX_TIMER_DELAY_MS + 1,
     })).rejects.toThrow(/streamIdleTimeoutMs/)
   })
+
+  it('rejects invalid nested retryPolicy before registering the provider', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+
+    await expect(ctx.plugin(LlmDeepSeek, {
+      apiKey: 'k',
+      baseURL: 'http://127.0.0.1:1',
+      retryPolicy: { mode: 'normal', maxRetries: -1 },
+    })).rejects.toThrow(/retryPolicy/)
+    expect(ctx.llm.listProviders()).toEqual([])
+  })
 })

packages/llm/llm-pi-ai/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/llm/llm-pi-ai/README.md
-README.md: 24a4762342f1ce8e71d1a5b1733fe02257823cb8
-README.zh.md: 557dc892c2eac10edc4e2fe4a0a142024942b1a9
+README.md: ac47cf6a21285fc887948a5a7798a9f1cb9157b0
+README.zh.md: a3d864ed9068d8bdaff4c5b73a4b7b339802ae05

packages/llm/llm-pi-ai/README.md

@@ -19,6 +19,13 @@ Configure credentials and deployment-specific transport settings per provider. O
         apiKey: !!js process.env.OPENAI_API_KEY
         baseURL: https://proxy.example.com:8443
         reasoning: high
+        retryPolicy:
+          mode: normal
+          maxRetries: 3
+          backoff:
+            initialDelayMs: 500
+            maxDelayMs: 10000
+            jitterRatio: 0.1
       - provider: anthropic
         apiKey: !!js process.env.ANTHROPIC_API_KEY
         streamIdleTimeoutMs: 300000
@@ -34,7 +41,7 @@ The adapter exposes each configured provider's installed pi-ai models through `c
 
 The `reasoning.efforts` list is pi-ai's ordered `getSupportedThinkingLevels(model)` result without filtering or normalization, including `off` and the model-specific availability of `xhigh` or `max`. The Harness exposes each canonical pi-ai level as an opaque ID; provider/model wire spellings remain inside pi-ai's `thinkingLevelMap`. A non-reasoning model therefore exposes pi-ai's `off` choice. The profile `reasoning` value, including `off`, is the deployment default when configured; omitting it preserves the provider default. Per-request `GenerateOptions.reasoningEffort` takes precedence, and any explicit value absent from the exact model capability fails with `UNSUPPORTED_REASONING_EFFORT` before network I/O instead of being clamped. pi-ai's common stream options represent `off` by omitting `reasoning`.
 
-Supported profile fields are `provider`, `apiKey`, `baseURL`, `headers`, `reasoning`, `thinkingBudgets`, `cacheRetention`, `transport`, `timeoutMs`, `websocketConnectTimeoutMs`, and `streamIdleTimeoutMs`. The stream-idle interval is a positive finite Node timer delay, defaults to five minutes, and covers only an outstanding provider read, not consumer think time. Harness app attribution wins a conflicting configured header name.
+Supported profile fields are `provider`, `apiKey`, `baseURL`, `headers`, `reasoning`, `thinkingBudgets`, `cacheRetention`, `transport`, `timeoutMs`, `websocketConnectTimeoutMs`, `streamIdleTimeoutMs`, and `retryPolicy`. Each profile's optional retry policy is captured with that provider route; omission uses bounded normal defaults. The stream-idle interval is a positive finite Node timer delay, defaults to five minutes, and covers only an outstanding provider read, not consumer think time. Harness app attribution wins a conflicting configured header name.
 
 The adapter forces pi-ai's SDK `maxRetries` to zero so one `stream()` call makes one provider request. The removed profile fields `maxRetries` and `maxRetryDelayMs` fail load instead of silently multiplying or hiding the separately composed agent-level retry budget. Idle expiry aborts the SDK's stable request signal and surfaces `TIMEOUT`; an earlier caller abort remains `ABORTED`.
 
@@ -102,4 +109,4 @@ Recorded response content appends to the next request and does not invalidate it
 - **`GenerateOptions.stop` is unsupported** — pi-ai's common stream options cannot guarantee stop-sequence behavior across providers, so the adapter rejects the field.
 - **In-history `system` messages use pi-ai's common context conversion** — provider-specific placement follows pi-ai rather than a harness-owned wire override.
 - **Provider HTTP status is unavailable** — pi-ai error events do not expose a stable HTTP status across providers; failures expose only stable harness error codes.
-- **Retry policy is not an adapter option** — SDK retries are disabled so durable agent steps and `llm/retry` events own every visible attempt; direct `ctx.llm.stream()` calls remain single-attempt.
+- **Retry policy is provider-owned, not an SDK retry** — each provider profile may configure nested `retryPolicy`, which `dsh-llm-retry` executes at the agent failed-step seam; pi-ai SDK retries stay disabled so durable agent steps and `llm/retry` events own every visible attempt, and direct `ctx.llm.stream()` calls remain single-attempt.

packages/llm/llm-pi-ai/README.zh.md

@@ -19,6 +19,13 @@
         apiKey: !!js process.env.OPENAI_API_KEY
         baseURL: https://proxy.example.com:8443
         reasoning: high
+        retryPolicy:
+          mode: normal
+          maxRetries: 3
+          backoff:
+            initialDelayMs: 500
+            maxDelayMs: 10000
+            jitterRatio: 0.1
       - provider: anthropic
         apiKey: !!js process.env.ANTHROPIC_API_KEY
         streamIdleTimeoutMs: 300000
@@ -34,7 +41,7 @@
 
 `reasoning.efforts` 列表是 pi-ai 有序的 `getSupportedThinkingLevels(model)` 结果，不经筛选或规范化，其中包括 `off`，以及模型对 `xhigh` 或 `max` 的特定支持。Harness 将每个规范 pi-ai 级别公开为不透明 ID；提供方／模型协议拼写仍保留在 pi-ai 的 `thinkingLevelMap` 中。因此，不具备推理（reasoning）能力的模型也会公开 pi-ai 的 `off` 选项。配置 profile 的 `reasoning` 值（包括 `off`）在存在时是部署默认值；省略它会保留提供方默认值。每次请求的 `GenerateOptions.reasoningEffort` 优先；任何未出现在确切模型能力中的显式值都会在网络 I/O 前以 `UNSUPPORTED_REASONING_EFFORT` 失败，而不会被自动调整。pi-ai 的通用流选项通过省略 `reasoning` 表示 `off`。
 
-受支持的 profile 字段是 `provider`、`apiKey`、`baseURL`、`headers`、`reasoning`、`thinkingBudgets`、`cacheRetention`、`transport`、`timeoutMs`、`websocketConnectTimeoutMs` 和 `streamIdleTimeoutMs`。流 idle 间隔必须是正的有限 Node 定时器延迟，默认为五分钟，且只覆盖未完成提供方读取，不包括消费方思考时间。Harness 应用归因会胜过名称冲突的已配置标头。
+受支持的 profile 字段是 `provider`、`apiKey`、`baseURL`、`headers`、`reasoning`、`thinkingBudgets`、`cacheRetention`、`transport`、`timeoutMs`、`websocketConnectTimeoutMs`、`streamIdleTimeoutMs` 和 `retryPolicy`。每个 profile 的可选重试策略都会与该提供方路由一同捕获；省略时使用有界的 normal 默认值。流 idle 间隔必须是正的有限 Node 定时器延迟，默认为五分钟，且只覆盖未完成提供方读取，不包括消费方思考时间。Harness 应用归因会胜过名称冲突的已配置标头。
 
 适配器强制 pi-ai SDK `maxRetries` 为零，因此一次 `stream()` 调用只会发起一次提供方请求。已移除 profile 字段 `maxRetries` 和 `maxRetryDelayMs` 会使加载失败，而不是静默倍增或隐藏单独组合的 agent 级重试预算。Idle 过期会 abort SDK 的稳定请求信号，并以 `TIMEOUT` 呈现；较早的调用方 abort 仍为 `ABORTED`。
 
@@ -102,4 +109,4 @@ pi-ai 事件会变为 harness reasoning、文本、工具调用、usage 与 fini
 - **不支持 `GenerateOptions.stop`**：pi-ai 的通用流选项无法保证所有提供方都支持 stop sequence，因此适配器会拒绝该字段。
 - **历史中的 `system` 消息使用 pi-ai 通用上下文转换**：提供方特定位置由 pi-ai 决定，而非由 harness 拥有的协议覆盖决定。
 - **无法获取提供方 HTTP 状态**：pi-ai 错误事件不会在所有提供方上公开稳定 HTTP 状态；失败只公开稳定 harness 错误 code。
-- **重试策略不是适配器选项**：SDK 重试已禁用，因此持久 agent 步骤与 `llm/retry` 事件拥有每次可见尝试；直接 `ctx.llm.stream()` 调用仍只尝试一次。
+- **重试策略由提供方持有，而不是 SDK 重试**：每个提供方 profile 都可以配置嵌套的 `retryPolicy`，由 `dsh-llm-retry` 在 agent 的失败步骤 seam 上执行；pi-ai SDK 重试仍保持禁用，因此持久 agent 步骤与 `llm/retry` 事件拥有每次可见尝试，直接 `ctx.llm.stream()` 调用仍只尝试一次。

packages/llm/llm-pi-ai/package.json

@@ -33,7 +33,7 @@
     "cordis": "^4.0.0-rc.7"
   },
   "dependencies": {
-    "@earendil-works/pi-ai": "^0.81.1",
+    "@earendil-works/pi-ai": "^0.82.1",
     "schemastery": "^3.18.0"
   },
   "devDependencies": {

packages/llm/llm-pi-ai/src/adapter.ts

@@ -26,6 +26,7 @@ import type {
   LlmModelInfo,
   LlmResolvedModelInfo,
   ReasoningEffortId as ReasoningEffortIdType,
+  ResolvedRetryPolicy,
   StreamChunk,
 } from '@deepseek-ai/dsh-llm'
 import { idleWatchdog, timeoutOf } from '@deepseek-ai/dsh-timeout'
@@ -44,7 +45,10 @@ export interface PiAiAdapterOptions {
  * Resolve a catalog model dynamically and apply only the configured endpoint
  * override, preserving the catalog's API/capability/compatibility metadata.
  */
-function resolvePiModel(profile: PiAiProviderProfile, modelId: string): Model<Api> {
+function resolvePiModel(
+  profile: Omit<PiAiProviderProfile, 'retryPolicy'>,
+  modelId: string,
+): Model<Api> {
   const model = getBuiltinModels(profile.provider as BuiltinProvider).find(candidate => candidate.id === modelId) as Model<Api> | undefined
   if (model === undefined) {
     throw new LlmError(`pi-ai provider "${profile.provider}" has no catalog model "${modelId}"`, 'UNKNOWN_MODEL')
@@ -54,7 +58,7 @@ function resolvePiModel(profile: PiAiProviderProfile, modelId: string): Model<Ap
 
 /** Copy profile stream knobs into pi-ai's common option vocabulary. */
 function profileOptions(
-  profile: PiAiProviderProfile,
+  profile: Omit<PiAiProviderProfile, 'retryPolicy'>,
   reasoning: ModelThinkingLevel | undefined,
 ): SimpleStreamOptions {
   const enabledReasoning: ThinkingLevel | undefined = reasoning === 'off' ? undefined : reasoning
@@ -107,6 +111,10 @@ export class PiAiAdapter extends LlmAdapter {
     this.profiles = new Map(resolveProfiles(options.profiles).map(profile => [profile.provider, profile]))
   }
 
+  override providerRetryPolicy(provider: string): ResolvedRetryPolicy | undefined {
+    return this.profiles.get(provider)?.retryPolicy
+  }
+
   override listModels(provider: string): Promise<readonly LlmModelInfo[]> {
     const profile = this.profiles.get(provider)
     if (profile === undefined) {

packages/llm/llm-pi-ai/src/config.ts

@@ -8,6 +8,8 @@ import { getBuiltinProviders } from '@earendil-works/pi-ai/providers/all'
 import type { CacheRetention, ModelThinkingLevel, ThinkingBudgets, Transport } from '@earendil-works/pi-ai'
 import z from 'schemastery'
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
+import { resolveRetryPolicy, RetryPolicySchema } from '@deepseek-ai/dsh-llm'
+import type { ResolvedRetryPolicy, RetryPolicyConfig } from '@deepseek-ai/dsh-llm'
 
 /** Default maximum idle interval while an adapter stream read is outstanding. */
 export const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 300_000
@@ -36,12 +38,16 @@ export interface PiAiProviderProfile {
   websocketConnectTimeoutMs?: number
   /** Maximum provider idle time while one stream read is outstanding. */
   streamIdleTimeoutMs?: number
+  /** Provider-owned model-request retry policy; omission uses normal defaults. */
+  retryPolicy?: RetryPolicyConfig
 }
 
 /** Validated profile with every adapter-owned default resolved. */
-export interface ResolvedPiAiProviderProfile extends PiAiProviderProfile {
+export interface ResolvedPiAiProviderProfile extends Omit<PiAiProviderProfile, 'retryPolicy'> {
   /** Positive finite provider-idle interval after defaulting. */
   streamIdleTimeoutMs: number
+  /** Immutable retry policy captured with this provider route. */
+  retryPolicy: ResolvedRetryPolicy
 }
 
 /** Plugin configuration: the non-empty provider profiles this instance owns. */
@@ -69,6 +75,7 @@ const profile = z.object({
   timeoutMs: z.natural(),
   websocketConnectTimeoutMs: z.natural(),
   streamIdleTimeoutMs: z.number().min(Number.MIN_VALUE).max(MAX_TIMER_DELAY_MS).default(DEFAULT_STREAM_IDLE_TIMEOUT_MS),
+  retryPolicy: RetryPolicySchema,
 })
 
 /** Runtime schema for {@link Config}. */
@@ -115,6 +122,10 @@ export function resolveProfiles(profiles: readonly PiAiProviderProfile[]): Resol
     return {
       ...source,
       streamIdleTimeoutMs,
+      retryPolicy: resolveRetryPolicy(
+        source.retryPolicy,
+        `llm-pi-ai: provider "${source.provider}" retryPolicy`,
+      ),
       ...source.headers === undefined ? {} : { headers: { ...source.headers } },
       ...source.thinkingBudgets === undefined ? {} : { thinkingBudgets: { ...source.thinkingBudgets } },
     }

packages/llm/llm-pi-ai/src/index.ts

@@ -10,6 +10,9 @@
  *     providers:
  *       - provider: openai
  *         apiKey: !!js process.env.OPENAI_API_KEY
+ *         retryPolicy:
+ *           mode: normal
+ *           maxRetries: 2
  *       - provider: anthropic
  *         apiKey: !!js process.env.ANTHROPIC_API_KEY
  *       - provider: openrouter
@@ -36,6 +39,6 @@ export const inject = ['llm']
 /** Register one generic pi-ai adapter for all configured provider routes. */
 export function apply(ctx: Context, config: Config): void {
   const profiles = resolveProfiles(config.providers)
-  const adapter = new PiAiAdapter({ profiles })
+  const adapter = new PiAiAdapter({ profiles: config.providers })
   ctx.llm.registerAdapter(profiles.map(entry => entry.provider), adapter)
 }

packages/llm/llm-pi-ai/src/stream.ts

@@ -28,6 +28,14 @@ export function mapUsage(usage: PiUsage): TokenUsage {
   }
 }
 
+// XXX(pi-ai upstream): pi-ai flattens the caught error to `error.message`
+// (api/anthropic-messages.js: `errorMessage = error instanceof Error ?
+// error.message : JSON.stringify(error)`), discarding the original Error and its
+// `cause` chain before it reaches us. undici carries the actionable transport
+// detail on `cause` (e.g. `SocketError: other side closed`) but hands the fetch
+// wrapper a bare `terminated`, so we are left pattern-matching terse words here.
+// If pi-ai ever forwards the original Error (or a fetch/dispatcher hook that lets
+// us capture the cause ourselves), classify on `code`/`cause` instead of text.
 function classifyPiAiError(message: string): string {
   if (/\b(?:401|403)\b/.test(message)) return 'AUTH'
   if (isQuotaExceededError(message)) return QUOTA_EXCEEDED_CODE
@@ -35,8 +43,19 @@ function classifyPiAiError(message: string): string {
   if (/\b400\b|invalid.?request/i.test(message)) return 'INVALID_REQUEST'
   if (/\b5\d\d\b/.test(message)) return 'SERVER'
   if (/\btime(?:d)?\s*out\b|timeout/i.test(message)) return 'TIMEOUT'
+  // A stream truncated before the provider's terminal event: each pi-ai provider
+  // throws its own wording when the wire closes mid-response without a terminal
+  // event (`… stream ended before message_stop`, `… before a terminal response
+  // event`, `… ended without a terminal event`, `Stream ended without
+  // finish_reason`). The connection dropped mid-response, so this is a transport
+  // truncation, not a model-level error.
+  if (/stream ended (?:before|without)\b/i.test(message)) return 'TRANSPORT'
   if (/\b(?:network|connection|socket|fetch)\b|\bECONN[A-Z]+\b/i.test(message)
-    || /\b(?:other side closed|HTTP2 request did not get a response|WebSocket closed unexpectedly)\b/i.test(message)) {
+    || /\b(?:other side closed|HTTP2 request did not get a response|WebSocket closed unexpectedly)\b/i.test(message)
+    // undici renders a mid-stream socket drop as a bare `terminated` (its
+    // `cause` — the real SocketError — was flattened away upstream); Node's
+    // stream layer says `Premature close`.
+    || /\bterminated\b|premature close/i.test(message)) {
     return 'TRANSPORT'
   }
   return 'PI_AI_ERROR'

packages/llm/llm-pi-ai/tests/adapter.spec.ts

@@ -330,12 +330,31 @@ describe('provider profile lifecycle', () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
     const fiber = await ctx.plugin(LlmPiAi, {
-      providers: [{ provider: 'openai' }, { provider: 'anthropic' }],
+      providers: [
+        {
+          provider: 'openai',
+          retryPolicy: {
+            mode: 'always',
+            backoff: { initialDelayMs: 25, maxDelayMs: 100, jitterRatio: 0.2 },
+          },
+        },
+        { provider: 'anthropic' },
+      ],
     })
     expect(ctx.llm.listProviders()).toEqual([
       { id: 'openai', name: 'openai' },
       { id: 'anthropic', name: 'anthropic' },
     ])
+    expect(ctx.llm.providerRetryPolicy('openai')).toEqual({
+      mode: 'always',
+      initialDelayMs: 25,
+      maxDelayMs: 100,
+      jitterRatio: 0.2,
+    })
+    expect(ctx.llm.providerRetryPolicy('anthropic')).toMatchObject({
+      mode: 'normal',
+      maxRetries: 2,
+    })
     await fiber.dispose()
     expect(ctx.llm.listProviders()).toEqual([])
   })
@@ -373,7 +392,6 @@ describe('provider profile lifecycle', () => {
     const extended = await ctx.llm.resolveModelInfo('openai', 'gpt-5.6-sol')
     expect(extended.reasoning?.efforts.map(effort => effort.id)).toEqual([
       ReasoningEffortId('off'),
-      ReasoningEffortId('minimal'),
       ReasoningEffortId('low'),
       ReasoningEffortId('medium'),
       ReasoningEffortId('high'),
@@ -460,6 +478,23 @@ describe('provider profile lifecycle', () => {
     }
   })
 
+  it('rejects invalid nested retryPolicy at the provider-profile boundary', async () => {
+    expect(() => resolveProfiles([{
+      provider: 'openai',
+      retryPolicy: { mode: 'always', backoff: { jitterRatio: -1 } },
+    }])).toThrow(/retryPolicy\.backoff\.jitterRatio/)
+
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    await expect(ctx.plugin(LlmPiAi, {
+      providers: [{
+        provider: 'openai',
+        retryPolicy: { mode: 'normal', maxRetries: -1 },
+      }],
+    })).rejects.toThrow(/retryPolicy/)
+    expect(ctx.llm.listProviders()).toEqual([])
+  })
+
   it('constructs the adapter directly and rejects routes it does not own', async () => {
     const adapter = new PiAiAdapter({ profiles: [{ provider: 'openai' }] })
     await expect(adapter.listModels('anthropic')).rejects.toMatchObject({ code: 'NO_ADAPTER' })

packages/llm/llm-pi-ai/tests/convert.spec.ts

@@ -578,6 +578,15 @@ describe('mapStopReason / mapUsage', () => {
     'other side closed',
     'HTTP2 request did not get a response',
     'WebSocket closed unexpectedly',
+    // undici flattens a mid-stream socket drop to this bare word (its SocketError
+    // cause is discarded upstream before it reaches us).
+    'terminated',
+    'Premature close',
+    // pi-ai's per-provider throws when the wire closes before the terminal event.
+    'Anthropic stream ended before message_stop',
+    'OpenAI Responses stream ended before a terminal response event',
+    'openrouter stream ended without a terminal event',
+    'Stream ended without finish_reason',
   ])('maps pi-ai transport wording %j', (errorMessage) => {
     expect(mapStopReason(assistant({ stopReason: 'error', errorMessage })))
       .toMatchObject({ kind: 'error', failure: { code: 'TRANSPORT' } })

packages/llm/llm-retry/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/llm/llm-retry/README.md
-README.md: 596a46e5395a4b5be9d400a85ee7c54d613ec2e6
-README.zh.md: a6a48f203e4701688816d4365b03da1ae2cfad82
+README.md: 7a86652a794e70c4dfd00ab7427730387e3ec949
+README.zh.md: 6255cca8c3b669ddec401496acb1e79ad54a8b3e

packages/llm/llm-retry/README.md

@@ -2,42 +2,52 @@
 
 English | [中文](README.zh.md)
 
-Function plugin that retries selected transient model-request failures through the `agent/request-error` waterfall. It does not wrap `ctx.llm.stream()`: every adapter call remains one provider attempt, and every retry opens a fresh numbered turn.
+Function plugin that applies exact-provider retry policy through the agent loop's closed-step `agent/request-error` waterfall. It does not wrap `ctx.llm.stream()`: every adapter call remains one provider attempt, and every retry opens a fresh numbered turn.
 
-The default policy permits two retries for `EMPTY_RESPONSE`, `RATE_LIMIT`, `SERVER`, `TIMEOUT`, and `TRANSPORT`, using bounded exponential backoff from 500 ms to 10 seconds with 10 percent jitter. `EMPTY_RESPONSE` is the adapters' classification of a degenerate provider completion (a terminal stop with zero content blocks); the attempt produced nothing durable, so repeating it is safe. Delay bounds must fit Node's supported timer range. A valid `providerRetryAfterMs` replaces local backoff when it is within the configured cap; an over-cap instruction delegates to the next recovery policy instead.
+Each provider adapter owns an optional nested `retryPolicy`, captured when its route registers on `ctx.llm` and carried with each call that reaches that registration's final adapter boundary. An in-flight failure retains that serving policy if the route is later disposed or replaced; a failure before any final adapter is selected has no provider policy and delegates. Omission uses normal mode: two retries for `EMPTY_RESPONSE`, `RATE_LIMIT`, `SERVER`, `TIMEOUT`, and `TRANSPORT`, with bounded exponential backoff from 500 ms to 10 seconds and 10 percent jitter. `EMPTY_RESPONSE` is the adapters' classification of a degenerate provider completion that produced no durable content, so repeating it is safe. A normal policy can change its finite budget, eligible codes, and backoff. Always mode asks downstream recovery first, then retries every model-request failure without an attempt limit; success, cancellation, or plugin disposal stops it after active delegated recovery reaches quiescence.
 
-The recovery listener appends a non-surface `llm/retry` event after the failed step, waits for the backoff while the failed turn's signal remains live, then returns `{ kind: 'retry' }`. The loop closes that failed turn and opens a retry turn over the same durable history. The policy keeps its own retry count across that uninterrupted recovery chain and clears it at terminal `agent/settled`. Turn cancellation and plugin disposal abort the wait.
+Both modes use bounded exponential backoff with symmetric jitter. A valid `providerRetryAfterMs` at or below `maxDelayMs` replaces local backoff without jitter. An over-cap provider delay makes normal mode delegate, while always mode uses its configured local backoff so it cannot terminate on that instruction.
 
-The separately published `./invariant` companion checks that every retry record appears inside an open turn after its failed step, matches its position in the current retry chain, and carries a positive bounded retry budget and non-negative bounded timer delay. Full jitter may schedule zero milliseconds at its lower boundary.
+Before waiting, the plugin appends a non-surface `llm/retry` event with the provider, mode, canonical resolved-policy key, failure, and scheduled delay. The key includes every behavior-affecting field and sorts normal-mode codes because eligibility uses set membership. Retry numbers continue only across events with the same provider and complete policy key, so a route replacement with different limits, code membership, or backoff starts its own history. Normal events include the finite maximum; always events omit it, and UIs render `∞`. After the wait, the listener returns `{ kind: 'retry' }`, and the loop closes the failed turn and opens a retry turn over the same durable history. Cancellation and plugin disposal abort active backoff, drain active delegated recovery before applying the abort, and make a callback captured before disposal fail closed.
+
+The separately published `./invariant` companion checks that every retry record names the current open turn and latest closed step, matches the failed request's durable provider, carries non-empty provider and policy identities, has mode-specific bounds, a unique step record, the correct provider-policy retry number, and a bounded timer delay. Full jitter may schedule zero milliseconds at its lower boundary.
 
 ```yaml
-- name: '@deepseek-ai/dsh-llm-retry'
+- name: '@deepseek-ai/dsh-llm-deepseek'
   config:
-    maxTransientRetries: 2
-    initialDelayMs: 500
-    maxDelayMs: 10000
-    jitterRatio: 0.1
-    retryableCodes: [EMPTY_RESPONSE, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT]
+    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    retryPolicy:
+      mode: always
+      backoff:
+        initialDelayMs: 1000
+        maxDelayMs: 30000
+        jitterRatio: 0.2
+
+- name: '@deepseek-ai/dsh-llm-retry'
 ```
 
+The executor has no policy config. Multi-provider adapters such as `dsh-llm-pi-ai` place `retryPolicy` inside each provider profile, avoiding a second provider-name list.
+
 ## Model Experience
 
-### Transient request recovery
+### Model-request recovery
 
 #### What the model sees
 
-No retry event, delay, or failure prose is model-visible. The retry turn reconstructs the same explicit provider/model request from durable session history; failed chunks never enter derived messages.
+No retry event, delay, provider error, or failed partial output is model-visible. The retry turn reconstructs the same explicit provider/model request from durable surface history unless a downstream recovery policy deliberately changes that surface; failed chunks never enter derived messages.
 
 #### Token effect
 
-Each retry is a new provider request and may repeat input-token billing. The finite budget caps attempts; `llm/retry` itself contributes no tokens.
+Each retry is a new provider request and may repeat input-token billing. Normal mode has a finite budget; always mode can consume unbounded requests until success or cancellation. `llm/retry` itself contributes no tokens.
 
 #### KV Cache effect
 
-The reconstructed request preserves the prior prefix and is eligible for provider cache reuse under that provider's rules. The non-surface status event does not change cache identity.
+The reconstructed request preserves the prior prefix and is eligible for provider cache reuse under that provider's rules. The non-surface retry event does not change cache identity.
 
 ## Known Limitations and Deferred Work
 
 - **Agent turns are the only retry boundary** — direct `ctx.llm.stream()` consumers remain single-attempt because a raw stream cannot separate already-emitted chunks durably.
-- **Finite plugin budgets add** — this policy counts only configured transient codes; context-overflow compaction counts only its own code. A future policy with overlapping codes must document and test registration-order behavior.
-- **`llm/retry` records completed backoff, not request completion** — later step and turn events establish success, exhaustion, or cancellation.
+- **Always mode retries permanent failures** — authentication, quota, invalid-request, protocol, and unrecoverable context errors continue until success, cancellation, or disposal; deployments own provider-specific cost and latency controls.
+- **Finite plugin budgets add** — normal mode counts only its configured codes and exact provider policy, while context-overflow compaction owns a separate budget. A future overlapping policy must document and test registration-order behavior.
+- **Recovery policies compose by waterfall order** — always mode accepts a downstream retry before applying its fallback. A later policy that ignores cancellation and never settles also prevents fallback, turn quiescence, and plugin disposal from completing.
+- **`llm/retry` records scheduling, not completion** — later step and turn events establish success, exhaustion, or cancellation.

packages/llm/llm-retry/README.zh.md

@@ -2,42 +2,52 @@
 
 [English](README.md) | 中文
 
-一个函数插件，通过 `agent/request-error` waterfall 重试特定的短暂模型请求失败。它不包装 `ctx.llm.stream()`：每次适配器调用仍是一次提供方尝试，每次重试都会开启新的编号轮次。
+一个函数插件，通过 agent loop（智能体循环）在已关闭步骤上触发的 `agent/request-error` waterfall（瀑布式事件）应用确切提供方重试策略。它不包装 `ctx.llm.stream()`：每次适配器调用仍是一次提供方尝试，每次重试都会开启新的编号轮次。
 
-默认策略允许为 `EMPTY_RESPONSE`、`RATE_LIMIT`、`SERVER`、`TIMEOUT` 和 `TRANSPORT` 重试两次，使用从 500 ms 到 10 秒的有界指数退避与 10% jitter。`EMPTY_RESPONSE` 是适配器对退化提供方完成的分类（携带零个内容块的终止 stop）；该尝试未产生持久内容，因此可安全重复。延迟边界必须适合 Node 支持的定时器范围。有效 `providerRetryAfterMs` 在已配置上限内时替换本地退避；超出上限的指令会委托给下一项恢复策略。
+每个提供方适配器都拥有可选的嵌套 `retryPolicy`；路由在 `ctx.llm` 上注册时会捕获该策略，任何到达该注册最终适配器边界的调用都会携带它。如果之后释放或替换路由，进行中的失败仍会保留为其提供服务的策略；在选中任何最终适配器前发生的失败没有提供方策略，会继续委托。省略策略时使用 normal mode：为 `EMPTY_RESPONSE`、`RATE_LIMIT`、`SERVER`、`TIMEOUT` 和 `TRANSPORT` 重试两次，并采用从 500 ms 到 10 秒的有界指数退避与 10% jitter。`EMPTY_RESPONSE` 是适配器对未产生任何持久内容的退化提供方完成所作的分类，因此可安全重复。normal 策略可以更改其有限预算、合格 code 和退避配置。always mode 会先请求下游恢复，再无次数上限地重试每个模型请求失败；成功、取消或插件 dispose（资源释放）会在活跃的委托恢复完全停稳后终止它。
 
-恢复 listener 会在失败步骤之后追加一个非表层 `llm/retry` 事件，在失败轮次的信号仍存活期间等待退避，然后返回 `{ kind: 'retry' }`。循环会关闭该失败轮次，并在同一持久历史上开启重试轮次。策略在这条不间断的恢复链中维护自己的重试计数，并在终态 `agent/settled` 时清零。轮次取消与插件 dispose 会中止等待。
+两种 mode 都使用带对称 jitter 的有界指数退避。有效 `providerRetryAfterMs` 不超过 `maxDelayMs` 时会替换本地退避，并且不加 jitter。超出上限的提供方延迟会使 normal mode 继续委托；always mode 则改用已配置的本地退避，避免该指令终止重试。
 
-单独发布的 `./invariant` 配套模块会检查每个重试记录是否出现在开启轮次内的失败步骤之后，是否与其在当前重试链中的位置匹配，以及是否携带正数有界重试预算和非负有界定时器延迟。完整 jitter 可以在下界调度为零毫秒。
+等待前，插件会追加一条不进入表层的 `llm/retry` 事件，其中包含提供方、mode、规范的解析策略 key、失败和计划延迟。该 key 包含所有影响行为的字段，并对 normal mode 的 code 排序，因为合格性采用集合成员关系判断。只有提供方与完整策略 key 都相同的事件才会延续重试编号；因此，用限制、code 成员关系或退避不同的路由替换后，会开始自己的历史。normal 事件包含有限上限；always 事件省略该上限，UI 会渲染 `∞`。等待结束后，监听器返回 `{ kind: 'retry' }`，循环关闭失败轮次，并在同一持久历史上开启重试轮次。取消与插件 dispose 会中止活跃退避，在应用中止前排空活跃的委托恢复，并使 dispose 前捕获的 callback 只能以失败结束。
+
+单独发布的 `./invariant` 配套模块会检查每个重试记录是否指向当前开启轮次及其最新已关闭步骤，是否与失败请求的持久提供方匹配，是否携带非空的提供方与策略身份，是否满足 mode 特定边界，是否拥有唯一步骤记录和正确的提供方策略重试编号，以及是否携带有界定时器延迟。完整 jitter 可以在下界调度为零毫秒。
 
 ```yaml
-- name: '@deepseek-ai/dsh-llm-retry'
+- name: '@deepseek-ai/dsh-llm-deepseek'
   config:
-    maxTransientRetries: 2
-    initialDelayMs: 500
-    maxDelayMs: 10000
-    jitterRatio: 0.1
-    retryableCodes: [EMPTY_RESPONSE, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT]
+    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    retryPolicy:
+      mode: always
+      backoff:
+        initialDelayMs: 1000
+        maxDelayMs: 30000
+        jitterRatio: 0.2
+
+- name: '@deepseek-ai/dsh-llm-retry'
 ```
 
+执行器没有策略配置。`dsh-llm-pi-ai` 等多提供方适配器会把 `retryPolicy` 放在每个提供方 profile 内，避免维护第二份提供方名称列表。
+
 ## 模型体验
 
-### 短暂请求恢复
+### 模型请求恢复
 
 #### 模型看到的内容
 
-模型不会看到重试事件、延迟或失败文本。重试轮次会从持久会话历史中重建相同的显式提供方／模型请求；失败 chunk 绝不会进入派生消息。
+模型不会看到重试事件、延迟、提供方错误或失败的部分输出。重试轮次会从持久表层历史中重建相同的显式提供方／模型请求，除非下游恢复策略有意更改该表层；失败分片绝不会进入派生消息。
 
 #### Token 影响
 
-每次重试都是新的提供方请求，可能重复计费输入 token。有限预算会限制尝试次数；`llm/retry` 自身不产生 token。
+每次重试都是新的提供方请求，可能重复计费输入 token。normal mode 具有有限预算；always mode 可以在成功或取消前消耗无界数量的请求。`llm/retry` 自身不产生 token。
 
 #### KV Cache 影响
 
-重建请求保留之前的前缀，并可根据该提供方的规则复用 cache。非表层状态事件不会改变 cache 身份。
+重建请求保留之前的前缀，并可根据该提供方的规则复用 cache。非表层重试事件不会改变 cache 身份。
 
 ## 已知限制与暂缓事项
 
 - **Agent 轮次是唯一重试边界**：直接 `ctx.llm.stream()` 消费方仍只尝试一次，因为原始流无法将已发出 chunk 持久分隔为不同尝试。
-- **有限插件预算可叠加**：该策略只统计已配置短暂 code；上下文溢出压缩只统计自身 code。未来如有 code 重叠的策略，必须记录并测试注册顺序行为。
-- **`llm/retry` 记录已完成的退避，不是请求完成**：后续步骤与轮次事件用于确立成功、耗尽或取消。
+- **always mode 会重试永久性失败**：身份验证、配额、无效请求、协议和无法恢复的上下文错误都会继续重试，直至成功、取消或 dispose；部署负责提供方特定的成本与延迟控制。
+- **有限插件预算可叠加**：normal mode 只统计已配置 code 和确切提供方策略，上下文溢出压缩则拥有独立预算。未来如有重叠策略，必须记录并测试注册顺序行为。
+- **恢复策略按 waterfall 顺序组合**：always mode 会先接受下游重试，再应用自己的回退。后续策略如果忽略取消且永不结算，也会阻止回退、轮次完全停稳和插件 dispose 完成。
+- **`llm/retry` 记录调度，不是完成**：后续步骤与轮次事件用于确立成功、耗尽或取消。

packages/llm/llm-retry/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-llm-retry",
-  "description": "Bounded transient LLM request retry policy for the DeepSeek Harness",
+  "description": "Provider-routed LLM request retry policy for the DeepSeek Harness",
   "version": "0.0.1",
   "private": true,
   "type": "module",

packages/llm/llm-retry/src/history.ts

@@ -0,0 +1,32 @@
+/** Durable request-route lookup for one closed model step. @module @deepseek-ai/dsh-llm-retry/history */
+
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+
+/**
+ * Find the provider in force when one step closed, excluding later recovery mutations.
+ * Request headers remain effective across turn boundaries until a newer full
+ * snapshot changes them; every provider change requires a newer full snapshot.
+ * @param events - session events containing the closed step.
+ * @param turn - turn that owns the failed step.
+ * @param step - failed step whose provider is required.
+ * @returns the provider from the request header in force at that step boundary.
+ */
+export function providerForClosedStep(
+  events: readonly SessionEvent[],
+  turn: number,
+  step: number,
+): string | undefined {
+  const stepEndIndex = events.findLastIndex(event =>
+    event.type === 'step/end'
+    && event.data.turn === turn
+    && event.data.step === step,
+  )
+  if (stepEndIndex < 0) return undefined
+  for (let index = stepEndIndex; index >= 0; index -= 1) {
+    // The loop bounds prove this indexed read exists.
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const event = events[index]!
+    if (event.type === 'request/header') return event.data.header.config.provider
+  }
+  return undefined
+}

packages/llm/llm-retry/src/index.ts

@@ -1,6 +1,6 @@
 /**
- * Bounded transient model-request retry policy on the agent request-recovery
- * seam. Each scheduled retry is durable before its cancellable wait.
+ * Provider-routed model-request retry policy on the agent loop's closed-step
+ * recovery seam. Each scheduled retry is durable before its cancellable wait.
  *
  * @module @deepseek-ai/dsh-llm-retry
  */
@@ -8,20 +8,32 @@
 import type { Context } from 'cordis'
 import z from 'schemastery'
 import type { Agent, RequestError, RequestErrorAction } from '@deepseek-ai/dsh-agent'
-import type { LlmFailure } from '@deepseek-ai/dsh-llm'
-import type {} from '@deepseek-ai/dsh-session'
-import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
+import type { LlmFailure, ResolvedRetryPolicy } from '@deepseek-ai/dsh-llm'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { providerForClosedStep } from './history.ts'
 
 declare module '@deepseek-ai/dsh-session' {
   interface SessionEventMap {
-    /** Durable, non-surface record of one transient retry scheduled after a closed failed step. */
+    /** Durable, non-surface record of one provider-routed retry scheduled after a closed failed step. */
     'llm/retry': {
       turn: number
       step: number
+      provider: string
+      mode: 'normal'
+      policyKey: string
       retry: number
       maxRetries: number
       delayMs: number
       failure: LlmFailure
+    } | {
+      turn: number
+      step: number
+      provider: string
+      mode: 'always'
+      policyKey: string
+      retry: number
+      delayMs: number
+      failure: LlmFailure
     }
   }
 }
@@ -29,82 +41,19 @@ declare module '@deepseek-ai/dsh-session' {
 export const name = 'llm-retry'
 export const inject = ['agents']
 
-const DEFAULT_MAX_TRANSIENT_RETRIES = 2
-const DEFAULT_INITIAL_DELAY_MS = 500
-const DEFAULT_MAX_DELAY_MS = 10_000
-const DEFAULT_JITTER_RATIO = 0.1
-const DEFAULT_RETRYABLE_CODES = Object.freeze(['EMPTY_RESPONSE', 'RATE_LIMIT', 'SERVER', 'TIMEOUT', 'TRANSPORT'])
-
-/** Deployment-owned limits and classification for transient request recovery. */
-export interface Config {
-  /** Maximum transient retries after the first request (default 2). */
-  maxTransientRetries?: number
-  /** Initial local exponential-backoff delay in milliseconds (default 500). */
-  initialDelayMs?: number
-  /** Maximum accepted or locally scheduled delay in milliseconds (default 10000). */
-  maxDelayMs?: number
-  /** Symmetric random multiplier range around one (default 0.1). */
-  jitterRatio?: number
-  /** Stable failure codes eligible for this policy. */
-  retryableCodes?: string[]
-}
+/** This policy executor has no config; providers own `retryPolicy`. */
+export type Config = Readonly<Record<string, never>>
 
 /** Runtime schema for {@link Config}. */
-export const Config: z<Config> = z.object({
-  maxTransientRetries: z.number().step(1).min(0).default(DEFAULT_MAX_TRANSIENT_RETRIES),
-  initialDelayMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_INITIAL_DELAY_MS),
-  maxDelayMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_MAX_DELAY_MS),
-  jitterRatio: z.number().min(0).max(1).default(DEFAULT_JITTER_RATIO),
-  retryableCodes: z.array(z.string()).default([...DEFAULT_RETRYABLE_CODES]),
-})
+export const Config = z.object({}) as unknown as z<Config>
 
-interface ResolvedConfig {
-  readonly maxTransientRetries: number
-  readonly initialDelayMs: number
-  readonly maxDelayMs: number
-  readonly jitterRatio: number
-  readonly retryableCodes: ReadonlySet<string>
-}
-
-function resolveConfig(config: Config): ResolvedConfig {
-  const maxTransientRetries = config.maxTransientRetries ?? DEFAULT_MAX_TRANSIENT_RETRIES
-  const initialDelayMs = config.initialDelayMs ?? DEFAULT_INITIAL_DELAY_MS
-  const maxDelayMs = config.maxDelayMs ?? DEFAULT_MAX_DELAY_MS
-  const jitterRatio = config.jitterRatio ?? DEFAULT_JITTER_RATIO
-  const codes = config.retryableCodes ?? [...DEFAULT_RETRYABLE_CODES]
-
-  if (!Number.isInteger(maxTransientRetries) || maxTransientRetries < 0) {
-    throw new Error('llm-retry: maxTransientRetries must be a non-negative integer')
+function validateConfig(config: Config): void {
+  const [key] = Object.keys(config)
+  if (key === undefined) return
+  if (key === 'retryPolicy') {
+    throw new Error('llm-retry: retryPolicy belongs under each provider configuration')
   }
-  if (!Number.isFinite(initialDelayMs) || initialDelayMs <= 0 || initialDelayMs > MAX_TIMER_DELAY_MS) {
-    throw new Error(`llm-retry: initialDelayMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`)
-  }
-  if (!Number.isFinite(maxDelayMs) || maxDelayMs <= 0 || maxDelayMs > MAX_TIMER_DELAY_MS) {
-    throw new Error(`llm-retry: maxDelayMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`)
-  }
-  if (initialDelayMs > maxDelayMs) {
-    throw new Error('llm-retry: initialDelayMs must be less than or equal to maxDelayMs')
-  }
-  if (!Number.isFinite(jitterRatio) || jitterRatio < 0 || jitterRatio > 1) {
-    throw new Error('llm-retry: jitterRatio must be between 0 and 1')
-  }
-  if (codes.length === 0) {
-    throw new Error('llm-retry: retryableCodes must not be empty')
-  }
-  if (codes.some(code => code.length === 0)) {
-    throw new Error('llm-retry: retryableCodes must contain only non-empty strings')
-  }
-  if (new Set(codes).size !== codes.length) {
-    throw new Error('llm-retry: retryableCodes must not contain duplicates')
-  }
-
-  return Object.freeze({
-    maxTransientRetries,
-    initialDelayMs,
-    maxDelayMs,
-    jitterRatio,
-    retryableCodes: new Set(codes),
-  })
+  throw new Error(`llm-retry: unknown key "${key}"`)
 }
 
 /** Non-serializable seams used to make timing policy deterministic in tests. */
@@ -113,13 +62,40 @@ export interface RetryInternals {
   random?: () => number
 }
 
-function localDelay(config: ResolvedConfig, retry: number, random: () => number): number {
+type DownstreamOutcome =
+  | { readonly type: 'decision'; readonly decision: RequestErrorAction }
+  | { readonly type: 'error'; readonly error: unknown }
+
+async function settleDownstream(
+  next: () => Promise<RequestErrorAction>,
+): Promise<DownstreamOutcome> {
+  try {
+    return { type: 'decision', decision: await next() }
+  } catch (error: unknown) {
+    return { type: 'error', error }
+  }
+}
+
+function localDelay(config: ResolvedRetryPolicy, retry: number, random: () => number): number {
   const exponent = Math.min(retry - 1, 1024)
   const exponential = Math.min(config.initialDelayMs * 2 ** exponent, config.maxDelayMs)
   const jitter = 1 - config.jitterRatio + 2 * config.jitterRatio * random()
   return Math.min(exponential * jitter, config.maxDelayMs)
 }
 
+function retryPolicyKey(policy: ResolvedRetryPolicy): string {
+  return policy.mode === 'always'
+    ? JSON.stringify([policy.mode, policy.initialDelayMs, policy.maxDelayMs, policy.jitterRatio])
+    : JSON.stringify([
+      policy.mode,
+      policy.maxRetries,
+      [...policy.retryableCodes].sort(),
+      policy.initialDelayMs,
+      policy.maxDelayMs,
+      policy.jitterRatio,
+    ])
+}
+
 function cancellableDelay(delayMs: number, signal: AbortSignal): Promise<boolean> {
   if (signal.aborted) return Promise.resolve(false)
   return new Promise((resolve) => {
@@ -136,60 +112,141 @@ function cancellableDelay(delayMs: number, signal: AbortSignal): Promise<boolean
 }
 
 /**
- * Install bounded transient request recovery.
+ * Install provider-routed normal or unbounded request recovery.
  * @param ctx - plugin context that owns the listener and active waits.
- * @param config - retry budget, delay bounds, jitter, and eligible codes.
+ * @param config - empty executor config; provider registrations own policy.
  * @param internals - non-serializable deterministic seams for tests.
  */
 export function apply(ctx: Context, config: Config = {}, internals: RetryInternals = {}): void {
-  const resolved = resolveConfig(config)
+  validateConfig(config)
   const random = internals.random ?? Math.random
   const lifetime = new AbortController()
   const active = new Set<Promise<RequestErrorAction>>()
-  const retries = new WeakMap<Agent, number>()
+
+  function track(operation: Promise<RequestErrorAction>): Promise<RequestErrorAction> {
+    const tracked = operation.finally(() => active.delete(tracked))
+    active.add(tracked)
+    return tracked
+  }
 
   async function backoff(
     agent: Agent,
     turn: number,
     step: number,
     failure: LlmFailure,
+    provider: string,
+    policy: ResolvedRetryPolicy,
+    policyKey: string,
     retry: number,
     delayMs: number,
     signal: AbortSignal,
   ): Promise<RequestErrorAction> {
     const fusedSignal = AbortSignal.any([signal, lifetime.signal])
     if (fusedSignal.aborted) return
-    agent.session.append('llm/retry', {
-      turn,
-      step,
-      retry,
-      maxRetries: resolved.maxTransientRetries,
-      delayMs,
-      failure,
-    })
-    retries.set(agent, retry)
+    const eventData = policy.mode === 'normal'
+      ? {
+        turn,
+        step,
+        provider,
+        mode: policy.mode,
+        policyKey,
+        retry,
+        maxRetries: policy.maxRetries,
+        delayMs,
+        failure,
+      }
+      : {
+        turn,
+        step,
+        provider,
+        mode: policy.mode,
+        policyKey,
+        retry,
+        delayMs,
+        failure,
+      }
+    agent.session.append('llm/retry', eventData)
     if (!await cancellableDelay(delayMs, fusedSignal)) return
     return { kind: 'retry' }
   }
 
-  ctx.on('agent/settled', (agent) => {
-    retries.delete(agent)
-  })
-
-  // A completed model response ends the consecutive-failure sequence even
-  // when its tool calls keep the turn running into another request.
-  ctx.on('session/event', (session, event) => {
-    if (event.type !== 'assistant/message') return
-    const agent = ctx.agents.get(session.id)
-    if (agent?.session === session) retries.delete(agent)
-  })
-
-  const disposeListener = ctx.on('agent/request-error', (
+  async function recover(
     agent: Agent,
     turn: number,
     step: number,
     _error: RequestError,
     failure: LlmFailure,
+    priorFailures: readonly LlmFailure[],
+    policy: ResolvedRetryPolicy | undefined,
+    signal: AbortSignal,
+    next: () => Promise<RequestErrorAction>,
+  ): Promise<RequestErrorAction> {
+    if (policy === undefined) return next()
+    // The call-local policy belongs to the registration that served this
+    // failure. Recover only the durable provider identity from the header;
+    // downstream recovery may append later state before an always fallback.
+    const provider = providerForClosedStep(agent.session.events, turn, step)
+    /* v8 ignore next 3 -- agent-loop closes only steps whose request header was recorded */
+    if (provider === undefined) {
+      throw new Error(`llm-retry: no request provider for closed turn ${turn}/step ${step}`)
+    }
+    if (policy.mode === 'always') {
+      if (signal.aborted || lifetime.signal.aborted) return
+      const fusedSignal = AbortSignal.any([signal, lifetime.signal])
+      // The loop and plugin lifetime stay open until delegated recovery settles.
+      // An abort then wins before the decision or fallback can mutate later state.
+      const downstream = await settleDownstream(next)
+      if (fusedSignal.aborted) return
+      if (downstream.type === 'error') {
+        ctx.logger.warn(
+          `llm-retry: provider "${provider}" always policy ignored a downstream recovery failure: %o`,
+          downstream.error,
+        )
+      }
+      if (downstream.type === 'decision' && downstream.decision?.kind === 'retry') {
+        return downstream.decision
+      }
+    } else if (!policy.retryableCodes.includes(failure.code)) {
+      return next()
+    }
+
+    const policyKey = retryPolicyKey(policy)
+    const firstPriorTurn = turn - priorFailures.length
+    const priorPolicyRetry = agent.session.events.findLast((event): event is SessionEvent<'llm/retry'> =>
+      event.type === 'llm/retry'
+      && event.data.turn >= firstPriorTurn
+      && event.data.turn < turn
+      && event.data.provider === provider
+      && event.data.policyKey === policyKey,
+    )
+    const previousRetry = priorPolicyRetry?.data.retry ?? 0
+    if (policy.mode === 'normal' && previousRetry >= policy.maxRetries) return next()
+    const retry = previousRetry + 1
+    let delayMs: number
+    if (failure.providerRetryAfterMs !== undefined
+      && Number.isFinite(failure.providerRetryAfterMs)
+      && failure.providerRetryAfterMs > 0) {
+      if (failure.providerRetryAfterMs > policy.maxDelayMs) {
+        if (policy.mode === 'normal') return next()
+        delayMs = localDelay(policy, retry, random)
+      } else {
+        delayMs = failure.providerRetryAfterMs
+      }
+    } else {
+      delayMs = localDelay(policy, retry, random)
+    }
+
+    return backoff(agent, turn, step, failure, provider, policy, policyKey, retry, delayMs, signal)
+  }
+
+  const disposeListener = ctx.on('agent/request-error', (
+    agent: Agent,
+    turn: number,
+    step: number,
+    error: RequestError,
+    failure: LlmFailure,
+    priorFailures: readonly LlmFailure[],
+    policy: ResolvedRetryPolicy | undefined,
     signal: AbortSignal,
     next: () => Promise<RequestErrorAction>,
   ) => {
@@ -197,30 +254,12 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna
     // removed. Lifetime cancellation must prevent that stale callback from
     // entering a downstream policy after disposal.
     if (lifetime.signal.aborted) return Promise.resolve<RequestErrorAction>(undefined)
-    if (!resolved.retryableCodes.has(failure.code)) return next()
-    const priorRetries = retries.get(agent) ?? 0
-    if (priorRetries >= resolved.maxTransientRetries) return next()
-
-    const retry = priorRetries + 1
-    let delayMs: number
-    if (failure.providerRetryAfterMs !== undefined
-      && Number.isFinite(failure.providerRetryAfterMs)
-      && failure.providerRetryAfterMs > 0) {
-      if (failure.providerRetryAfterMs > resolved.maxDelayMs) return next()
-      delayMs = failure.providerRetryAfterMs
-    } else {
-      delayMs = localDelay(resolved, retry, random)
-    }
-
-    const tracked = backoff(agent, turn, step, failure, retry, delayMs, signal)
-      .finally(() => active.delete(tracked))
-    active.add(tracked)
-    return tracked
+    return track(recover(agent, turn, step, error, failure, priorFailures, policy, signal, next))
   })
 
   ctx.effect(() => async () => {
     disposeListener()
     lifetime.abort(new Error('llm-retry plugin disposed'))
     await Promise.allSettled([...active])
-  }, 'llm-retry: abort and drain backoffs')
+  }, 'llm-retry: abort and drain active recovery')
 }

packages/llm/llm-retry/src/invariant.ts

@@ -2,8 +2,10 @@
 
 import type { Context } from 'cordis'
 import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import type { LlmFailure } from '@deepseek-ai/dsh-llm'
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import { providerForClosedStep } from './history.ts'
 import type {} from './index.ts'
 
 const PACKAGE_NAME = '@deepseek-ai/dsh-llm-retry'
@@ -13,6 +15,32 @@ export const name = 'llm-retry-invariant'
 /** Service required before the companion can reserve package ownership. */
 export const inject = ['invariants']
 
+/** Validate the complete provider-neutral failure payload at the durable boundary. */
+function validateFailure(value: unknown, fail: InvariantFailure): asserts value is LlmFailure {
+  if (typeof value !== 'object' || value === null) {
+    fail('llm/retry failure must be an object')
+  }
+  const failure = value as Partial<LlmFailure>
+  if (typeof failure.message !== 'string' || failure.message.length === 0) {
+    fail('llm/retry failure.message must be a non-empty string')
+  }
+  if (typeof failure.code !== 'string' || failure.code.length === 0) {
+    fail('llm/retry failure.code must be a non-empty string')
+  }
+  if (failure.status !== undefined
+    && (!Number.isInteger(failure.status) || failure.status < 100 || failure.status > 599)) {
+    fail('llm/retry failure.status must be an integer from 100 through 599 when present')
+  }
+  if (failure.providerRetryAfterMs !== undefined
+    && (!Number.isFinite(failure.providerRetryAfterMs) || failure.providerRetryAfterMs <= 0)) {
+    fail('llm/retry failure.providerRetryAfterMs must be a positive finite number when present')
+  }
+  if (failure.requestId !== undefined
+    && (typeof failure.requestId !== 'string' || failure.requestId.length === 0)) {
+    fail('llm/retry failure.requestId must be a non-empty string when present')
+  }
+}
+
 /** Find the first turn in the structured-failure retry chain containing `turn`. */
 function retryChainStart(history: readonly SessionEvent[], turn: number): number {
   let startIndex = history.findLastIndex(
@@ -47,15 +75,35 @@ function validateRetry(
   event: SessionEvent<'llm/retry'>,
   fail: InvariantFailure,
 ): void {
-  const { turn, step, retry, maxRetries, delayMs } = event.data
+  const { turn, step, provider, mode, policyKey, retry, delayMs } = event.data
+  const failure: unknown = event.data.failure
+  validateFailure(failure, fail)
   if (!Number.isSafeInteger(retry) || retry < 1) {
     fail('llm/retry retry must be a positive safe integer')
   }
-  if (!Number.isSafeInteger(maxRetries) || maxRetries < 1 || retry > maxRetries) {
-    fail(`llm/retry retry ${retry} must not exceed a positive safe maxRetries ${maxRetries}`)
+  if (typeof provider !== 'string' || provider.length === 0) {
+    fail('llm/retry provider must be a non-empty string')
   }
-  if (!(delayMs >= 0 && delayMs <= MAX_TIMER_DELAY_MS)) {
-    fail(`llm/retry delayMs must be within 0..${MAX_TIMER_DELAY_MS}`)
+  if (typeof policyKey !== 'string' || policyKey.length === 0) {
+    fail('llm/retry policyKey must be a non-empty string')
+  }
+  switch (mode) {
+    case 'normal': {
+      const { maxRetries } = event.data
+      if (!Number.isSafeInteger(maxRetries) || maxRetries < 1 || retry > maxRetries) {
+        fail(`llm/retry retry ${retry} must not exceed a positive safe maxRetries ${maxRetries}`)
+      }
+      break
+    }
+    case 'always':
+      if ('maxRetries' in event.data) fail('llm/retry always mode must omit maxRetries')
+      break
+    default:
+      fail(`llm/retry mode must be normal or always, got ${String(mode)}`)
+  }
+  if (typeof delayMs !== 'number' || !Number.isFinite(delayMs)
+    || delayMs < 0 || delayMs > MAX_TIMER_DELAY_MS) {
+    fail(`llm/retry delayMs must be a finite number within 0..${MAX_TIMER_DELAY_MS}`)
   }
 
   const currentTurnEvents: SessionEvent[] = []
@@ -86,6 +134,10 @@ function validateRetry(
   if (closedStep === undefined || step !== closedStep) {
     fail(`llm/retry names step ${step}, but the latest closed step is ${String(closedStep)}`)
   }
+  const routedProvider = providerForClosedStep(history, turn, step)
+  if (routedProvider !== provider) {
+    fail(`llm/retry provider ${provider} does not match the failed request provider ${String(routedProvider)}`)
+  }
 
   const chainStart = retryChainStart(history, turn)
   const chain = history.slice(Math.max(chainStart, 0))
@@ -95,9 +147,11 @@ function validateRetry(
   if (chainRetries.some(prior => prior.data.turn === turn && prior.data.step === step)) {
     fail(`llm/retry duplicates the retry record for turn ${turn}/step ${step}`)
   }
-  const expectedRetry = chainRetries.length + 1
+  const priorPolicyRetry = chainRetries.findLast(prior =>
+    prior.data.provider === provider && prior.data.policyKey === policyKey)
+  const expectedRetry = (priorPolicyRetry?.data.retry ?? 0) + 1
   if (retry !== expectedRetry) {
-    fail(`llm/retry retry ${retry} must equal retry-chain position ${expectedRetry}`)
+    fail(`llm/retry retry ${retry} must equal provider policy retry ${expectedRetry}`)
   }
 }
 

packages/llm/llm-retry/tests/invariant.spec.ts

@@ -1,9 +1,11 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
-import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, type Session } from '@deepseek-ai/dsh-session'
+import { ProviderRequestId } from '@deepseek-ai/dsh-llm'
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import InvariantService from '@deepseek-ai/dsh-invariants'
 import * as RetryInvariant from '@deepseek-ai/dsh-llm-retry/invariant'
+import { providerForClosedStep } from '../src/history.ts'
 
 async function setup(): Promise<Context> {
   const ctx = new Context()
@@ -13,207 +15,272 @@ async function setup(): Promise<Context> {
   return ctx
 }
 
-const failure = { message: 'provider busy', code: 'RATE_LIMIT', status: 429 }
-
 function closeStep(ctx: Context, id: string, turn = 1, step = 1) {
   const session = ctx.sessions.create(SessionId(id))
-  session.append('turn/start', {
-    turn,
-    trigger: turn === 1
-      ? { kind: 'message', source: { kind: 'user' } }
-      : { kind: 'retry' },
-  })
+  session.append('turn/start', { turn, trigger: { kind: 'message', source: { kind: 'user' } } })
   session.append('step/start', { turn, step })
+  session.append('request/header', {
+    header: { config: { provider: 'mock', model: 'mock' } },
+    reason: 'initial',
+  })
   session.append('step/end', { turn, step })
   return session
 }
 
+function appendRetryTurn(session: Session, turn: number) {
+  session.append('turn/start', { turn, trigger: { kind: 'retry' } })
+  session.append('step/start', { turn, step: 1 })
+  session.append('request/header', {
+    header: { config: { provider: 'mock', model: 'mock' } },
+    reason: 'initial',
+  })
+  session.append('step/end', { turn, step: 1 })
+  session.append('llm/retry', { turn, step: 1, ...normal })
+}
+
+const failure = { message: 'provider busy', code: 'RATE_LIMIT', status: 429 }
+const normal = {
+  provider: 'mock',
+  mode: 'normal' as const,
+  policyKey: 'normal-policy',
+  retry: 1,
+  maxRetries: 2,
+  delayMs: 1,
+  failure,
+}
+const always = {
+  provider: 'mock',
+  mode: 'always' as const,
+  policyKey: 'always-policy',
+  retry: 1,
+  delayMs: 1,
+  failure,
+}
+
 describe('llm-retry invariants', () => {
-  it('accepts increasing retry schedules for successive failed turns', async () => {
+  it('has no provider without the requested closed step or a route marker', () => {
+    expect(providerForClosedStep([], 1, 1)).toBeUndefined()
+    expect(providerForClosedStep([{
+      type: 'step/end',
+      data: { turn: 1, step: 1 },
+    }] as never, 1, 1)).toBeUndefined()
+  })
+
+  it('accepts bounded and unbounded records after successive closed steps', async () => {
     const ctx = await setup()
     const session = closeStep(ctx, 'retry-invariant-valid')
+
     expect(() => {
-      session.append('llm/retry', {
-        turn: 1, step: 1, retry: 1, maxRetries: 2, delayMs: 500, failure,
-      })
+      session.append('llm/retry', { turn: 1, step: 1, ...normal })
       session.append('turn/end', { turn: 1, reason: { kind: 'error', step: 1, failure } })
       session.append('turn/start', { turn: 2, trigger: { kind: 'retry' } })
       session.append('step/start', { turn: 2, step: 1 })
       session.append('step/end', { turn: 2, step: 1 })
       session.append('llm/retry', {
-        turn: 2, step: 1, retry: 2, maxRetries: 2, delayMs: 0, failure,
+        turn: 2, step: 1, ...normal, retry: 2, delayMs: 0,
       })
+      const unbounded = closeStep(ctx, 'retry-invariant-always')
+      unbounded.append('llm/retry', { turn: 1, step: 1, ...always })
     }).not.toThrow()
     expect(() => { ctx.emit('tools/change') }).not.toThrow()
   })
 
-  it.each([
-    [{ retry: 0, maxRetries: 2, delayMs: 1 }, /positive safe integer/],
-    [{ retry: 1.5, maxRetries: 2, delayMs: 1 }, /positive safe integer/],
-    [{ retry: 1, maxRetries: 0, delayMs: 1 }, /positive safe maxRetries/],
-    [{ retry: 1, maxRetries: 1.5, delayMs: 1 }, /positive safe maxRetries/],
-    [{ retry: 3, maxRetries: 2, delayMs: 1 }, /must not exceed/],
-    [{ retry: 1, maxRetries: 2, delayMs: -1 }, /delayMs/],
-    [{ retry: 1, maxRetries: 2, delayMs: MAX_TIMER_DELAY_MS + 1 }, /delayMs/],
-  ])('rejects invalid retry bounds %#', async (data, message) => {
+  it('validates the complete durable failure payload', async () => {
     const ctx = await setup()
-    const session = closeStep(ctx, `retry-invariant-bounds-${data.retry}-${data.maxRetries}-${data.delayMs}`)
+    const complete = closeStep(ctx, 'retry-invariant-complete-failure')
     expect(() => {
-      session.append('llm/retry', { turn: 1, step: 1, ...data, failure })
+      complete.append('llm/retry', {
+        turn: 1,
+        step: 1,
+        ...always,
+        failure: {
+          message: 'provider busy',
+          code: 'RATE_LIMIT',
+          status: 429,
+          providerRetryAfterMs: 25,
+          requestId: ProviderRequestId('request-1'),
+        },
+      })
+    }).not.toThrow()
+
+    const invalidFailures: readonly [string, unknown, RegExp][] = [
+      ['null', null, /failure must be an object/],
+      ['message-type', { message: 1, code: 'RATE_LIMIT' }, /failure\.message/],
+      ['message-empty', { message: '', code: 'RATE_LIMIT' }, /failure\.message/],
+      ['code-type', { message: 'failed', code: 1 }, /failure\.code/],
+      ['code-empty', { message: 'failed', code: '' }, /failure\.code/],
+      ['status-type', { message: 'failed', code: 'RATE_LIMIT', status: 429.5 }, /failure\.status/],
+      ['status-low', { message: 'failed', code: 'RATE_LIMIT', status: 99 }, /failure\.status/],
+      ['status-high', { message: 'failed', code: 'RATE_LIMIT', status: 600 }, /failure\.status/],
+      [
+        'retry-after-type',
+        { message: 'failed', code: 'RATE_LIMIT', providerRetryAfterMs: '25' },
+        /failure\.providerRetryAfterMs/,
+      ],
+      [
+        'retry-after-zero',
+        { message: 'failed', code: 'RATE_LIMIT', providerRetryAfterMs: 0 },
+        /failure\.providerRetryAfterMs/,
+      ],
+      ['request-id-type', { message: 'failed', code: 'RATE_LIMIT', requestId: 1 }, /failure\.requestId/],
+      ['request-id-empty', { message: 'failed', code: 'RATE_LIMIT', requestId: '' }, /failure\.requestId/],
+    ]
+    for (const [name, invalidFailure, message] of invalidFailures) {
+      const session = closeStep(ctx, `retry-invariant-failure-${name}`)
+      expect(() => {
+        session.append('llm/retry', {
+          turn: 1, step: 1, ...always, failure: invalidFailure,
+        } as never)
+      }).toThrow(message)
+    }
+  })
+
+  it.each([
+    ['retry-zero', { ...normal, retry: 0 }, /positive safe integer/],
+    ['retry-fraction', { ...normal, retry: 1.5 }, /positive safe integer/],
+    ['max-zero', { ...normal, maxRetries: 0 }, /positive safe maxRetries/],
+    ['max-fraction', { ...normal, maxRetries: 1.5 }, /positive safe maxRetries/],
+    ['over-budget', { ...normal, retry: 3 }, /must not exceed/],
+    ['always-maximum', { ...always, maxRetries: 2 }, /always mode must omit maxRetries/],
+    ['unknown-mode', { ...always, mode: 'sometimes' }, /mode must be normal or always/],
+    ['empty-provider', { ...always, provider: '' }, /provider must be a non-empty string/],
+    ['empty-policy-key', { ...always, policyKey: '' }, /policyKey must be a non-empty string/],
+    ['delay-negative', { ...normal, delayMs: -1 }, /delayMs/],
+    ['delay-overflow', { ...normal, delayMs: MAX_TIMER_DELAY_MS + 1 }, /delayMs/],
+    ['delay-type', { ...normal, delayMs: '1' }, /delayMs/],
+  ])('rejects invalid retry data: %s', async (name, data, message) => {
+    const ctx = await setup()
+    const session = closeStep(ctx, `retry-invariant-${name}`)
+    expect(() => {
+      session.append('llm/retry', { turn: 1, step: 1, ...data } as never)
     }).toThrow(message)
   })
 
-  it('rejects a retry record appended after its turn already closed', async () => {
-    const ctx = await setup()
-    const closed = closeStep(ctx, 'retry-invariant-closed-turn')
-    closed.append('turn/end', { turn: 1, reason: { kind: 'error', step: 1, failure } })
-    expect(() => {
-      closed.append('llm/retry', {
-        turn: 1, step: 1, retry: 1, maxRetries: 2, delayMs: 1, failure,
-      })
-    }).toThrow(/inside an open turn/)
-  })
-
-  it('starts a fresh chain when the turn before a retry trigger did not fail structurally', async () => {
-    const ctx = await setup()
-    const session = closeStep(ctx, 'retry-invariant-completed-predecessor')
-    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-    session.append('turn/start', { turn: 2, trigger: { kind: 'retry' } })
-    session.append('step/start', { turn: 2, step: 1 })
-    session.append('step/end', { turn: 2, step: 1 })
-    expect(() => {
-      session.append('llm/retry', {
-        turn: 2, step: 1, retry: 1, maxRetries: 2, delayMs: 1, failure,
-      })
-    }).not.toThrow()
-  })
-
-  it('walks the chain across non-boundary events and stops at an unmatched turn start', async () => {
-    const ctx = await setup()
-    // The failed predecessor's turn/start is outside this log prefix (e.g. a
-    // truncated replay): the chain walk must stop rather than loop or throw.
-    const session = ctx.sessions.create(SessionId('retry-invariant-unmatched-start'))
-    session.append('turn/end', { turn: 1, reason: { kind: 'error', step: 1, failure } })
-    // A durable non-boundary record between the turns exercises the walk over
-    // non-turn/end events.
-    session.append('todo/write', { todos: [] })
-    session.append('turn/start', { turn: 2, trigger: { kind: 'retry' } })
-    session.append('step/start', { turn: 2, step: 1 })
-    session.append('step/end', { turn: 2, step: 1 })
-    expect(() => {
-      session.append('llm/retry', {
-        turn: 2, step: 1, retry: 1, maxRetries: 2, delayMs: 1, failure,
-      })
-    }).not.toThrow()
-  })
-
-  it('requires an open turn and its latest closed step', async () => {
+  it('rejects records outside the latest closed step of an open turn', async () => {
     const ctx = await setup()
     const absent = ctx.sessions.create(SessionId('retry-invariant-no-turn'))
     expect(() => {
-      absent.append('llm/retry', {
-        turn: 1, step: 1, retry: 1, maxRetries: 2, delayMs: 1, failure,
-      })
+      absent.append('llm/retry', { turn: 1, step: 1, ...normal })
     }).toThrow(/inside an open turn/)
 
     const wrongTurn = closeStep(ctx, 'retry-invariant-wrong-turn')
     expect(() => {
-      wrongTurn.append('llm/retry', {
-        turn: 2, step: 1, retry: 1, maxRetries: 2, delayMs: 1, failure,
-      })
+      wrongTurn.append('llm/retry', { turn: 2, step: 1, ...normal })
     }).toThrow(/open turn is 1/)
 
     const openStep = ctx.sessions.create(SessionId('retry-invariant-open-step'))
     openStep.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     openStep.append('step/start', { turn: 1, step: 1 })
     expect(() => {
-      openStep.append('llm/retry', {
-        turn: 1, step: 1, retry: 1, maxRetries: 2, delayMs: 1, failure,
-      })
+      openStep.append('llm/retry', { turn: 1, step: 1, ...normal })
     }).toThrow(/step 1 is still open/)
 
+    const noStep = ctx.sessions.create(SessionId('retry-invariant-no-step'))
+    noStep.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    expect(() => {
+      noStep.append('llm/retry', { turn: 1, step: 1, ...normal })
+    }).toThrow(/latest closed step is undefined/)
+
     const wrongStep = closeStep(ctx, 'retry-invariant-wrong-step')
     expect(() => {
-      wrongStep.append('llm/retry', {
-        turn: 1, step: 2, retry: 1, maxRetries: 2, delayMs: 1, failure,
-      })
+      wrongStep.append('llm/retry', { turn: 1, step: 2, ...normal })
     }).toThrow(/latest closed step is 1/)
+
+    const closedTurn = closeStep(ctx, 'retry-invariant-closed-turn')
+    closedTurn.append('turn/end', { turn: 1, reason: { kind: 'aborted' } })
+    expect(() => {
+      closedTurn.append('llm/retry', { turn: 1, step: 1, ...normal })
+    }).toThrow(/inside an open turn/)
   })
 
-  it('rejects duplicate and out-of-sequence retry schedules', async () => {
+  it('rejects a second retry record for the same step', async () => {
     const ctx = await setup()
-    const duplicate = closeStep(ctx, 'retry-invariant-duplicate')
-    duplicate.append('llm/retry', {
-      turn: 1, step: 1, retry: 1, maxRetries: 3, delayMs: 1, failure,
-    })
-    expect(() => {
-      duplicate.append('llm/retry', {
-        turn: 1, step: 1, retry: 2, maxRetries: 3, delayMs: 1, failure,
-      })
-    }).toThrow(/duplicates/)
+    const session = closeStep(ctx, 'retry-invariant-duplicate')
+    session.append('llm/retry', { turn: 1, step: 1, ...normal })
 
-    const nonIncreasing = closeStep(ctx, 'retry-invariant-non-increasing')
-    nonIncreasing.append('llm/retry', {
-      turn: 1, step: 1, retry: 1, maxRetries: 3, delayMs: 1, failure,
-    })
-    nonIncreasing.append('turn/end', { turn: 1, reason: { kind: 'error', step: 1, failure } })
-    nonIncreasing.append('turn/start', { turn: 2, trigger: { kind: 'retry' } })
-    nonIncreasing.append('step/start', { turn: 2, step: 1 })
-    nonIncreasing.append('step/end', { turn: 2, step: 1 })
     expect(() => {
-      nonIncreasing.append('llm/retry', {
-        turn: 2, step: 1, retry: 1, maxRetries: 3, delayMs: 1, failure,
-      })
-    }).toThrow(/retry-chain position 2/)
+      session.append('llm/retry', { turn: 1, step: 1, ...normal, retry: 2 })
+    }).toThrow(/duplicates the retry record/)
   })
 
-  it('resets retry numbering after a completed chain', async () => {
+  it('binds retry numbering to the provider policy and resets it after success', async () => {
     const ctx = await setup()
-    const session = closeStep(ctx, 'retry-invariant-reset')
-    session.append('llm/retry', {
-      turn: 1, step: 1, retry: 1, maxRetries: 2, delayMs: 1, failure,
-    })
-    session.append('turn/end', { turn: 1, reason: { kind: 'error', step: 1, failure } })
-    session.append('turn/start', { turn: 2, trigger: { kind: 'retry' } })
-    session.append('step/start', { turn: 2, step: 1 })
-    session.append('step/end', { turn: 2, step: 1 })
-    session.append('turn/end', { turn: 2, reason: { kind: 'completed' } })
-    session.append('turn/start', {
-      turn: 3,
-      trigger: { kind: 'message', source: { kind: 'user' } },
-    })
-    session.append('step/start', { turn: 3, step: 1 })
-    session.append('step/end', { turn: 3, step: 1 })
-
+    const mismatch = closeStep(ctx, 'retry-invariant-numbering')
+    mismatch.append('llm/retry', { turn: 1, step: 1, ...normal })
+    mismatch.append('turn/end', { turn: 1, reason: { kind: 'error', step: 1, failure } })
+    mismatch.append('turn/start', { turn: 2, trigger: { kind: 'retry' } })
+    mismatch.append('step/start', { turn: 2, step: 1 })
+    mismatch.append('step/end', { turn: 2, step: 1 })
     expect(() => {
-      session.append('llm/retry', {
-        turn: 3, step: 1, retry: 1, maxRetries: 2, delayMs: 1, failure,
-      })
+      mismatch.append('llm/retry', { turn: 2, step: 1, ...normal, retry: 1 })
+    }).toThrow(/must equal provider policy retry 2/)
+
+    const reset = closeStep(ctx, 'retry-invariant-reset')
+    reset.append('llm/retry', { turn: 1, step: 1, ...normal })
+    reset.append('turn/end', { turn: 1, reason: { kind: 'error', step: 1, failure } })
+    reset.append('turn/start', { turn: 2, trigger: { kind: 'retry' } })
+    reset.append('step/start', { turn: 2, step: 1 })
+    reset.append('assistant/message', {
+      turn: 2,
+      step: 1,
+      content: [{ type: 'text', text: 'success' }],
+      provenance: { provider: 'mock', model: 'mock' },
+    }, { surfaceOp: 'append' })
+    reset.append('step/end', { turn: 2, step: 1 })
+    reset.append('turn/end', { turn: 2, reason: { kind: 'completed' } })
+    reset.append('turn/start', { turn: 3, trigger: { kind: 'message', source: { kind: 'user' } } })
+    reset.append('step/start', { turn: 3, step: 1 })
+    reset.append('step/end', { turn: 3, step: 1 })
+    expect(() => {
+      reset.append('llm/retry', { turn: 3, step: 1, ...normal })
     }).not.toThrow()
   })
 
+  it('starts a fresh retry chain after incomplete predecessor boundaries', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+
+    const missingEnd = ctx.sessions.create(SessionId('retry-invariant-missing-end'))
+    missingEnd.append('user/message', {
+      content: [{ type: 'text', text: 'idle context' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    appendRetryTurn(missingEnd, 2)
+
+    const nonFailureEnd = ctx.sessions.create(SessionId('retry-invariant-non-failure-end'))
+    nonFailureEnd.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    nonFailureEnd.append('user/message', {
+      content: [{ type: 'text', text: 'idle context' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    appendRetryTurn(nonFailureEnd, 2)
+
+    const missingStart = ctx.sessions.create(SessionId('retry-invariant-missing-start'))
+    missingStart.append('turn/end', {
+      turn: 1,
+      reason: { kind: 'error', step: 1, failure },
+    })
+    appendRetryTurn(missingStart, 2)
+
+    await ctx.plugin(InvariantService)
+    await expect(ctx.plugin(RetryInvariant)).resolves.toBeDefined()
+  })
+
+  it('rejects a provider that does not match the failed request route', async () => {
+    const ctx = await setup()
+    const session = closeStep(ctx, 'retry-invariant-provider')
+    expect(() => {
+      session.append('llm/retry', { turn: 1, step: 1, ...always, provider: 'other' })
+    }).toThrow(/does not match the failed request provider mock/)
+  })
+
   it('validates existing histories on late registration', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const session = ctx.sessions.create(SessionId('retry-invariant-late'))
-    session.append('llm/retry', {
-      turn: 1, step: 1, retry: 1, maxRetries: 2, delayMs: 1, failure,
-    })
+    session.append('step/end', { turn: 1, step: 1 })
+    session.append('llm/retry', { turn: 1, step: 1, ...normal })
     await ctx.plugin(InvariantService)
     await expect(ctx.plugin(RetryInvariant)).rejects.toThrow(/inside an open turn/)
   })
-
-  it('accepts a valid mixed pre-existing history on late registration', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const session = ctx.sessions.create(SessionId('retry-invariant-late-valid'))
-    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    session.append('step/start', { turn: 1, step: 1 })
-    session.append('step/end', { turn: 1, step: 1 })
-    session.append('llm/retry', {
-      turn: 1, step: 1, retry: 1, maxRetries: 2, delayMs: 1, failure,
-    })
-    await ctx.plugin(InvariantService)
-    await expect(ctx.plugin(RetryInvariant)).resolves.toBeDefined()
-  })
 })

packages/llm/llm-retry/tests/loader-composition.spec.ts

@@ -8,8 +8,8 @@ import Loader from '@cordisjs/plugin-loader'
 import Include from '@cordisjs/plugin-include'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
-import LlmService, { LlmAdapter, LlmError } from '@deepseek-ai/dsh-llm'
-import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
+import LlmService, { LlmAdapter, LlmError, resolveRetryPolicy } from '@deepseek-ai/dsh-llm'
+import type { GenerateOptions, ResolvedRetryPolicy, StreamChunk } 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'
@@ -20,6 +20,16 @@ let context: Context | undefined
 
 class TransientOnceAdapter extends LlmAdapter {
   requests = 0
+  private readonly retryPolicy = resolveRetryPolicy({
+    mode: 'normal',
+    maxRetries: 1,
+    retryableCodes: ['RATE_LIMIT', 'SERVER'],
+    backoff: { initialDelayMs: 1, maxDelayMs: 1, jitterRatio: 0 },
+  }, 'loader test provider retryPolicy')
+
+  override providerRetryPolicy(_provider: string): ResolvedRetryPolicy {
+    return this.retryPolicy
+  }
 
   async * stream(_options: GenerateOptions): AsyncIterable<StreamChunk> {
     this.requests += 1
@@ -75,7 +85,7 @@ describe('real Loader composition', () => {
   // Real-Loader composition resolves workspace packages through tsx at test
   // time; first resolution after the host/client program split is slow enough
   // to trip the default 5s budget on cold caches.
-  it('loads the flat policy and records recovery through the shipping loop', { timeout: 60_000 }, async () => {
+  it('loads provider-supplied policy and records recovery through the shipping loop', { timeout: 60_000 }, async () => {
     const loaded = await loadYaml([
       "- name: '@deepseek-ai/dsh-llm'",
       "- name: '@deepseek-ai/dsh-session'",
@@ -83,12 +93,6 @@ describe('real Loader composition', () => {
       "- name: '@deepseek-ai/dsh-tools'",
       "- name: '@deepseek-ai/dsh-agent'",
       "- name: '@deepseek-ai/dsh-llm-retry'",
-      '  config:',
-      '    maxTransientRetries: 1',
-      '    initialDelayMs: 1',
-      '    maxDelayMs: 1',
-      '    jitterRatio: 0',
-      '    retryableCodes: [RATE_LIMIT, SERVER]',
       "- name: '@deepseek-ai/dsh-agent-loop'",
     ])
 

packages/llm/llm-retry/tests/persistence.spec.ts

@@ -34,12 +34,18 @@ describe.each(['jsonl', 'sqlite'] as const)('%s retry-event persistence', (kind)
       const session = ctx.sessions.create(SessionId(`retry-${kind}`))
       session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
       session.append('step/start', { turn: 1, step: 1 })
+      session.append('request/header', {
+        header: { config: { provider: 'mock', model: 'mock' } },
+        reason: 'initial',
+      })
       session.append('step/end', { turn: 1, step: 1 })
       const event = session.append('llm/retry', {
         turn: 1,
         step: 1,
+        provider: 'mock',
+        mode: 'always',
+        policyKey: '["always",500,10000,0.1]',
         retry: 1,
-        maxRetries: 2,
         delayMs: 750,
         failure: { message: 'provider busy', code: 'RATE_LIMIT', status: 429 },
       })

packages/llm/llm-retry/tests/transport-recovery.spec.ts

@@ -39,13 +39,17 @@ async function harness(
     apiKey: 'mock-key',
     baseURL,
     streamIdleTimeoutMs: options.streamIdleTimeoutMs ?? 1_000,
+    retryPolicy: {
+      mode: 'normal',
+      maxRetries: 2,
+      backoff: {
+        initialDelayMs: options.initialDelayMs ?? 10,
+        maxDelayMs: options.initialDelayMs ?? 10,
+        jitterRatio: 0,
+      },
+    },
   })
-  await ctx.plugin(Retry, {
-    maxTransientRetries: 2,
-    initialDelayMs: options.initialDelayMs ?? 10,
-    maxDelayMs: options.initialDelayMs ?? 10,
-    jitterRatio: 0,
-  })
+  await ctx.plugin(Retry)
   await ctx.plugin(AgentLoop, { agents: [] })
   return ctx
 }

packages/llm/llm-retry/tsdown.config.ts

@@ -0,0 +1,25 @@
+import { defineConfig } from 'tsdown'
+
+/** Build the package root and invariant companion as independent bundles. */
+export default defineConfig([
+  {
+    entry: ['lib/types/index.js'],
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+  },
+  {
+    entry: ['lib/types/invariant.js'],
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+  },
+])

packages/llm/llm/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/llm/llm/README.md
-README.md: 3efb3ece3caadeaceaa3c504ba4b10ddb951127a
-README.zh.md: 4af8b8d08cc96ff0e36b10b15e1d86afd43004c9
+README.md: 2328188e420df6de60f024982a31d37a858a303e
+README.zh.md: 586767a9e790fa68d27673836700fd789ce6a180

packages/llm/llm/README.md

@@ -12,15 +12,16 @@ An adapter registry plus a single streaming call surface, interceptable via a wa
 
 - `ctx.llm.registerAdapter(providers: string[], adapter: LlmAdapter): () => void` Register one adapter instance for the given provider routes. Registration is all-or-nothing, and is disposed with the calling fiber.
 - `ctx.llm.listProviders(): LlmProviderInfo[]` Describe registered provider routes in registration order.
+- `ctx.llm.providerRetryPolicy(provider: string): ResolvedRetryPolicy` Return the provider-owned retry policy captured during registration, with normal defaults resolved.
 - `ctx.llm.listModels(provider: string): Promise<LlmModelInfo[]>` Discover the models one registered provider currently advertises.
 - `ctx.llm.resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>` Resolve validated exact-model identity plus available context and reasoning metadata from the owning adapter, with optional cancellation for asynchronous adapters.
 - `ctx.llm.resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<LlmCallConfig>` Validate an explicit effort and materialize an adapter-configured default without clamping.
 - `ctx.llm.prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>` Resolve a config and capture its current adapter registration as one cancellable, one-shot call.
 - `ctx.llm.stream(options: GenerateOptions): AsyncIterable<StreamChunk>` Stream one model call as raw chunks (token-level deltas). Consumers assemble the chunks into blocks/messages with `BlockAssembler`.
 
-`LlmService` preserves errors from final adapter selection, synchronous dispatch, iterator construction, and iteration, and binds their provenance to the exact stream handle returned for that model call. `isLlmAdapterFailure(stream, value)` reports only errors from that call's final adapter boundary; `llmFailureOf(stream, value)` returns the adjacent immutable `LlmFailure`. Nested model calls, `llm/stream` middleware, and downstream consumer failures remain unclassified for the outer call. Classification never replaces or mutates the adapter's original coded `Error`.
+`LlmService` preserves errors from final adapter selection, synchronous dispatch, iterator construction, and iteration, and binds their provenance to the exact stream handle returned for that model call. `isLlmAdapterFailure(stream, value)` reports only errors from that call's final adapter boundary; `llmFailureOf(stream, value)` returns the adjacent immutable `LlmFailure`; `llmRetryPolicyOf(stream)` returns the immutable policy of the exact registration selected at that boundary, even if the route is later disposed or replaced. A call that never reaches a final adapter has no serving policy. Nested model calls, `llm/stream` middleware, and downstream consumer failures remain unclassified for the outer call. Classification never replaces or mutates the adapter's original coded `Error`.
 
-Provider and model metadata is a discovery surface, not a routing whitelist. `registerAdapter()` still owns provider exclusivity, while an adapter may accept model ids absent from `listModels()`; consumers must not reject a request because its model is unlisted. Returned metadata is detached and invalid or duplicate adapter entries fail with `INVALID_ADAPTER` or `INVALID_CATALOG`.
+Provider and model metadata is a discovery surface, not a routing whitelist. `registerAdapter()` still owns provider exclusivity and captures the adapter's retry policy for each route, while an adapter may accept model ids absent from `listModels()`; consumers must not reject a request because its model is unlisted. Returned selector metadata is detached and invalid or duplicate adapter entries fail with `INVALID_ADAPTER` or `INVALID_CATALOG`.
 
 Exact-model metadata is a separate correctness query, not a catalog decoration or global LLM setting. `resolveModelInfo()` asks the adapter that owns the exact provider/model route once; an adapter can describe an unlisted dynamic model, and absent `context` or `reasoning` fields mean only that those capabilities are unavailable. Invalid identity, context, or reasoning metadata fails with `INVALID_MODEL_INFO`, `INVALID_MODEL_CONTEXT`, or `INVALID_MODEL_REASONING`.
 
@@ -34,7 +35,7 @@ Reasoning identifiers are opaque adapter-owned strings rather than a core enum.
 
 ### Extension points
 
-- Subclass `LlmAdapter` and call `ctx.llm.registerAdapter(providers, adapter)` to add one or more provider routes. `GenerateOptions.provider` selects the adapter; `GenerateOptions.model` is adapter-owned and may be resolved dynamically. Override `providerInfo()` and asynchronous `listModels()` to expose selector metadata, then implement `resolveModel()` when exact identity, capacity, or selectable reasoning efforts are available; an asynchronous resolver must honor its optional cancellation signal. The defaults use the route and model ids as names, advertise no models, and return no capacity or reasoning metadata.
+- Subclass `LlmAdapter` and call `ctx.llm.registerAdapter(providers, adapter)` to add one or more provider routes. `GenerateOptions.provider` selects the adapter; `GenerateOptions.model` is adapter-owned and may be resolved dynamically. Override `providerRetryPolicy()` to supply provider-owned recovery configuration, `providerInfo()` and asynchronous `listModels()` to expose selector metadata, then implement `resolveModel()` when exact identity, capacity, or selectable reasoning efforts are available; an asynchronous resolver must honor its optional cancellation signal. The defaults use bounded normal retry policy, use the route and model ids as names, advertise no models, and return no capacity or reasoning metadata.
 - Wrap `llm/stream` via `ctx.on()` waterfall listeners for caching, logging, or routing. A wrapper that retries after emitting a chunk has no durable attempt boundary; shipped agent retry policy therefore uses `agent/request-error` instead.
 
 ### Content-block vocabulary (`types.ts`)
@@ -76,7 +77,7 @@ Pass-through; the registry preserves the assembled request prefix, while the sel
 
 ## Known Limitations and Deferred Work
 
-- **No default retry/caching/rate-limit policy ships in this service** — `llm/stream` remains a single-attempt call-wrapper seam; the agent loop separately offers proven model-request failures to `agent/request-error`, whose default preserves the original failure. `@deepseek-ai/dsh-llm-retry` is an optional policy plugin loaded by the shared example spine.
+- **No retry execution, caching, or rate limiting ships in this service** — provider registration stores retry policy, but `llm/stream` remains a single-attempt call-wrapper seam. The agent loop separately offers proven model-request failures to `agent/request-error`, whose default preserves the original failure; `@deepseek-ai/dsh-llm-retry` is the optional executor loaded by the shared example spine.
 - **`GenerateOptions` sampling is `temperature`/`maxTokens`/`stop` only** — no `tool_choice`, `top_p`, or penalty fields; the vocabulary grows when a producer lands ([dropped inert knobs](../../../.agents/notes/archived/simplification/2026-07-04-drop-inert-request-knobs.md)).
 - **Producer-gated variants stay out until produced** — `prefill`, per-tool `strict`, block `cache` hints, and the `agent` message-source variant were pruned as producerless ([Agent Note](../../../.agents/notes/archived/simplification/2026-07-04-prune-producerless-vocabulary-variants.md)).
 - **`BlockAssembler` handles core block kinds only** — a plugin-added block type whose stream is never closed by `block-end` makes `blocks()` throw.

packages/llm/llm/README.zh.md

@@ -12,15 +12,16 @@
 
 - `ctx.llm.registerAdapter(providers: string[], adapter: LlmAdapter): () => void` 为给定提供方路由注册一个适配器实例。注册要么全部成功，要么全部不生效，并且会随调用 fiber dispose。
 - `ctx.llm.listProviders(): LlmProviderInfo[]` 按注册顺序描述已注册提供方路由。
+- `ctx.llm.providerRetryPolicy(provider: string): ResolvedRetryPolicy` 返回注册时捕获的提供方重试策略，并解析 normal 默认值。
 - `ctx.llm.listModels(provider: string): Promise<LlmModelInfo[]>` 发现某个已注册提供方当前公布的模型。
 - `ctx.llm.resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>` 从拥有精确路由的适配器解析经校验的确切模型身份、可用上下文和推理（reasoning）元数据；异步适配器可选地支持取消。
 - `ctx.llm.resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<LlmCallConfig>` 校验显式推理强度，并填入适配器配置的默认值，但不自动调整。
 - `ctx.llm.prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>` 解析配置并将其当前适配器注册捕获为一次可取消、一次性调用。
 - `ctx.llm.stream(options: GenerateOptions): AsyncIterable<StreamChunk>` 将一次模型调用流式输出为原始 chunk（token 级 delta）。消费方使用 `BlockAssembler` 将 chunk 组装为块／消息。
 
-`LlmService` 保留来自最终适配器选择、同步 dispatch、iterator 构造与迭代的错误，并将其溯源绑定到该次模型调用返回的精确流句柄。`isLlmAdapterFailure(stream, value)` 只报告该调用最终适配器边界的错误；`llmFailureOf(stream, value)` 返回相邻的不可变 `LlmFailure`。嵌套模型调用、`llm/stream` middleware 和下游消费方失败对外层调用仍未分类。分类绝不替换或更改适配器的原始编码 `Error`。
+`LlmService` 保留来自最终适配器选择、同步 dispatch、iterator 构造与迭代的错误，并将其溯源绑定到该次模型调用返回的精确流句柄。`isLlmAdapterFailure(stream, value)` 只报告该调用最终适配器边界的错误；`llmFailureOf(stream, value)` 返回相邻的不可变 `LlmFailure`；`llmRetryPolicyOf(stream)` 返回在该边界选中的确切注册所对应的不可变策略，即使之后释放或替换路由也不变。未到达最终适配器的调用没有服务策略。嵌套模型调用、`llm/stream` middleware 和下游消费方失败对外层调用仍未分类。分类绝不替换或更改适配器的原始编码 `Error`。
 
-提供方与模型元数据是发现表层，不是路由白名单。`registerAdapter()` 仍拥有提供方排他性，适配器则可以接受 `listModels()` 中不存在的模型 id；消费方禁止因模型未列出而拒绝请求。返回的元数据与输入脱离，无效或重复适配器配置项会以 `INVALID_ADAPTER` 或 `INVALID_CATALOG` 失败。
+提供方与模型元数据是发现表层，不是路由白名单。`registerAdapter()` 仍拥有提供方排他性，并为每条路由捕获适配器的重试策略；适配器则可以接受 `listModels()` 中不存在的模型 id，消费方禁止因模型未列出而拒绝请求。返回的 selector 元数据与输入脱离，无效或重复适配器配置项会以 `INVALID_ADAPTER` 或 `INVALID_CATALOG` 失败。
 
 确切模型元数据是独立的正确性查询，不是 catalog 装饰或全局 LLM 设置。`resolveModelInfo()` 会向拥有精确提供方／模型路由的适配器查询一次；适配器可以描述未列出的动态模型，缺少 `context` 或 `reasoning` 字段只表示相应能力不可用。无效的身份、上下文或推理元数据会以 `INVALID_MODEL_INFO`、`INVALID_MODEL_CONTEXT` 或 `INVALID_MODEL_REASONING` 失败。
 
@@ -34,7 +35,7 @@
 
 ### 扩展点
 
-- 继承 `LlmAdapter` 并调用 `ctx.llm.registerAdapter(providers, adapter)`，添加一条或多条提供方路由。`GenerateOptions.provider` 选择适配器；`GenerateOptions.model` 属于适配器，可以动态解析。覆盖 `providerInfo()` 和异步 `listModels()` 以公开 selector 元数据；精确身份、容量或可选推理强度可用时，实现 `resolveModel()`；异步解析器必须响应其可选的取消 signal。默认实现将路由和模型 id 用作名称，不公布模型，也不返回容量或推理元数据。
+- 继承 `LlmAdapter` 并调用 `ctx.llm.registerAdapter(providers, adapter)`，添加一条或多条提供方路由。`GenerateOptions.provider` 选择适配器；`GenerateOptions.model` 属于适配器，可以动态解析。覆盖 `providerRetryPolicy()` 以提供由提供方持有的恢复配置，覆盖 `providerInfo()` 和异步 `listModels()` 以公开 selector 元数据；精确身份、容量或可选推理强度可用时，实现 `resolveModel()`；异步解析器必须响应其可选的取消 signal。默认实现使用有界的 normal 重试策略，将路由和模型 id 用作名称，不公布模型，也不返回容量或推理元数据。
 - 包装 `llm/stream` 时，通过 `ctx.on()` waterfall listener 实现缓存、日志或路由。发出 chunk 后重试的包装层没有持久尝试边界；因此已发布 agent 重试策略改用 `agent/request-error`。
 
 ### 内容块词汇（`types.ts`）
@@ -76,7 +77,7 @@
 
 ## 已知限制与暂缓事项
 
-- **本服务不内置默认重试／缓存／速率限制策略**：`llm/stream` 仍是单次尝试调用包装 seam；agent loop 会将已验证模型请求失败单独提供给 `agent/request-error`，其默认行为是保留原始失败。`@deepseek-ai/dsh-llm-retry` 是共享示例 spine 加载的可选策略插件。
+- **本服务不执行重试、缓存或速率限制**：提供方注册会存储重试策略，但 `llm/stream` 仍是单次尝试调用包装 seam。agent loop 会将已验证模型请求失败单独提供给 `agent/request-error`，其默认行为是保留原始失败；`@deepseek-ai/dsh-llm-retry` 是共享示例 spine 加载的可选执行器。
 - **`GenerateOptions` 采样只包含 `temperature`／`maxTokens`／`stop`**：没有 `tool_choice`、`top_p` 或 penalty 字段；有产生方落地时词汇才会增长（见 [已删除惰性旋钮](../../../.agents/notes/archived/simplification/2026-07-04-drop-inert-request-knobs.md)）。
 - **由产生方调节的变体在实际产生前保持在外**：`prefill`、每工具 `strict`、块 `cache` 提示与 `agent` 消息源变体因没有产生方而被剪除（见 [Agent Note](../../../.agents/notes/archived/simplification/2026-07-04-prune-producerless-vocabulary-variants.md)）。
 - **`BlockAssembler` 只处理核心块 kind**：如果插件添加块类型的流从未由 `block-end` 关闭，`blocks()` 会抛出异常。

packages/llm/llm/package.json

@@ -38,11 +38,16 @@
   "peerDependencies": {
     "@deepseek-ai/dsh-brand": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
   "devDependencies": {
     "@deepseek-ai/dsh-brand": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-timeout": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }
 }

packages/llm/llm/src/adapter-failure.ts

@@ -6,9 +6,15 @@
 
 import { HarnessError } from './error.ts'
 import type { LlmFailure, StreamChunk } from './types.ts'
+import type { ResolvedRetryPolicy } from './retry-policy.ts'
 
-/** Errors and normalized facts proven to originate in one model call's final adapter boundary. */
-export type AdapterFailureScope = WeakMap<Error, LlmFailure>
+/** Call-local facts captured when one model call enters its final adapter boundary. */
+export interface AdapterFailureScope {
+  /** Errors and normalized facts proven to originate in this call's final adapter boundary. */
+  readonly failures: WeakMap<Error, LlmFailure>
+  /** Immutable policy of the exact adapter registration selected for this call. */
+  retryPolicy?: ResolvedRetryPolicy
+}
 
 /** Call-local failure scopes keyed by the exact stream handle returned to a consumer. */
 const adapterFailureScopes = new WeakMap<AsyncIterable<StreamChunk>, AdapterFailureScope>()
@@ -54,7 +60,7 @@ export function markLlmAdapterFailure(
     message: errorMessage(error),
     code: harnessErrorCode(error),
   })
-  failures.set(error, failure)
+  failures.failures.set(error, failure)
   return error
 }
 
@@ -136,7 +142,7 @@ export function isLlmAdapterFailure(
   value: unknown,
 ): value is Error & { code?: string } {
   const failures = adapterFailureScopes.get(stream)
-  return value instanceof Error && failures !== undefined && failures.has(value)
+  return value instanceof Error && failures !== undefined && failures.failures.has(value)
 }
 
 /**
@@ -151,5 +157,18 @@ export function llmFailureOf(
   value: unknown,
 ): LlmFailure | undefined {
   const failures = adapterFailureScopes.get(stream)
-  return value instanceof Error ? failures?.get(value) : undefined
+  return value instanceof Error ? failures?.failures.get(value) : undefined
+}
+
+/**
+ * Read the retry policy of the exact registration selected at this call's
+ * final adapter boundary. The policy remains available after that registration
+ * is disposed or replaced; absence means no final adapter served the call.
+ * @param stream - the exact stream returned by the model call.
+ * @returns the immutable serving-registration policy, or `undefined`.
+ */
+export function llmRetryPolicyOf(
+  stream: AsyncIterable<StreamChunk>,
+): ResolvedRetryPolicy | undefined {
+  return adapterFailureScopes.get(stream)?.retryPolicy
 }

packages/llm/llm/src/index.ts

@@ -16,6 +16,8 @@ import type {
   Message,
   StreamChunk,
 } from './types.ts'
+import { resolveRetryPolicy } from './retry-policy.ts'
+import type { ResolvedRetryPolicy } from './retry-policy.ts'
 import type { ProviderRequestId } from './brand.ts'
 import { callConfigEquals, deepFreeze } from './call-config.ts'
 import type { LlmCallConfig } from './call-config.ts'
@@ -28,10 +30,11 @@ export * from './brand.ts'
 export * from './never.ts'
 export * from './error.ts'
 export * from './types.ts'
+export * from './retry-policy.ts'
 export { BlockAssembler } from './assembler.ts'
 export { callConfigEquals, deepFreeze, isAgentLoopRequest, markAgentLoopRequest } from './call-config.ts'
 export type { LlmCallConfig } from './call-config.ts'
-export { isLlmAdapterFailure, llmFailureOf } from './adapter-failure.ts'
+export { isLlmAdapterFailure, llmFailureOf, llmRetryPolicyOf } from './adapter-failure.ts'
 
 declare module 'cordis' {
   interface Context {
@@ -134,6 +137,15 @@ export abstract class LlmAdapter {
     return { id: provider, name: provider }
   }
 
+  /**
+   * Return the provider-owned retry policy captured with this route.
+   * @param _provider - a route passed to `registerAdapter()` for this instance.
+   * @returns a resolved policy, or `undefined` to use the normal defaults.
+   */
+  providerRetryPolicy(_provider: string): ResolvedRetryPolicy | undefined {
+    return undefined
+  }
+
   /**
    * List models this adapter can currently advertise for one owned provider.
    * The result is advisory: an adapter may accept unlisted model ids, and
@@ -204,7 +216,13 @@ export class LlmService extends Service {
           throw new LlmError(`adapter metadata for provider "${provider}" must preserve its id and have a non-empty name`, 'INVALID_ADAPTER')
         }
         unique.add(provider)
-        registrations.push({ adapter, provider: { id: info.id, name: info.name } })
+        const retryPolicy = adapter.providerRetryPolicy(provider)
+          ?? resolveRetryPolicy(undefined, `llm: provider "${provider}" retryPolicy`)
+        registrations.push({
+          adapter,
+          provider: { id: info.id, name: info.name },
+          retryPolicy,
+        })
       }
       for (const registration of registrations) this.adapters.set(registration.provider.id, registration)
       yield () => {
@@ -224,6 +242,15 @@ export class LlmService extends Service {
     return [...this.adapters.values()].map(({ provider }) => ({ ...provider }))
   }
 
+  /**
+   * Resolve the retry policy captured when one provider route was registered.
+   * @param provider - registered provider route to inspect.
+   * @returns the provider-owned policy, with normal defaults already resolved.
+   */
+  providerRetryPolicy(provider: string): ResolvedRetryPolicy {
+    return this.registration(provider).retryPolicy
+  }
+
   /**
    * Discover models advertised by one registered provider. Catalog membership
    * is advisory and never changes routing or request validation.
@@ -459,6 +486,7 @@ export class LlmService extends Service {
     let iterator: AsyncIterator<StreamChunk>
     try {
       const registration = prepared?.registration ?? this.registration(options.provider)
+      failures.retryPolicy = registration.retryPolicy
       const resolvedConfig = prepared === undefined
         ? await this.resolveCallConfigFor(registration, options, options.signal)
         : prepared.config
@@ -530,7 +558,7 @@ export class LlmService extends Service {
     options: GenerateOptions,
     prepared?: { registration: AdapterRegistration; config: LlmCallConfig },
   ): AsyncIterable<StreamChunk> {
-    const failures: AdapterFailureScope = new WeakMap<Error, LlmFailure>()
+    const failures: AdapterFailureScope = { failures: new WeakMap<Error, LlmFailure>() }
     const stream = this.ctx.waterfall(
       this,
       'llm/stream',
@@ -544,6 +572,7 @@ export class LlmService extends Service {
 interface AdapterRegistration {
   readonly adapter: LlmAdapter
   readonly provider: LlmProviderInfo
+  readonly retryPolicy: ResolvedRetryPolicy
 }
 
 export default LlmService