Merge remote-tracking branch 'origin/master' into worktree/web-multimodal-image-input

# Conflicts: # apps/web/tests/built-boot.snapshot.ts # packages/client/runtime/README.i18n.yaml # packages/client/runtime/src/client/sessions/conversation.ts # packages/client/ui-conversation/README.i18n.yaml # packages/client/ui-conversation/src/client/chat/ChatView.tsx # packages/client/ui-conversation/src/client/chat/MessageItem.tsx # packages/host/apiproxy/README.i18n.yaml
2026-07-31 13:43:10 +08:00
parent 702336be02 c48a50d553
commit 1f0b5b1ebf
145 changed files with 5272 additions and 367 deletions
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/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/runtime/README.md
-README.md: 910458038d4e86c338761c93b03db8e0aa95e3d8
-README.zh.md: 799f17b1beac9696a73727642f0f6e16c9b98f99
+README.md: b7e4bc17bd074310df33609c1bc127a187d46d93
+README.zh.md: ae4df903ed7cb85c81c300e40db3e943dbf01f07
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -30,6 +30,10 @@ SlotsService gives the renderer separate bare observables for `useSessions` and

 `SessionManager` retains the latest validated `session/title` control snapshot independently of list and session-instance arrival. Newer event seqs replace older snapshots, title timestamps contribute to list recency, and a subscription baseline discards any retained title beyond its `lastSeq` before the optional folded title arrives. Explicit session removal also clears the retained title. The client-facing `SessionSummary.title` is therefore only the actual durable title; `displayTitle` is always present and falls back through the cwd basename and session id. A cold persisted session keeps that fallback until opening or resuming it causes the host to fold and project its log-backed title. `ISession.rename` settles the `title` projection cell directly from the unary response's `{title, seq}` under the same higher-seq-wins rule — the list row and every `useProjection('title')` reader update ahead of the push frame, whose later replay of the same seq is a no-op.

+## Model retry projection
+
+The Session object validates plugin-owned, provider-routed `llm/retry` payloads at the event wire boundary against the producer's complete field contract, including timer, integer, status, provider-delay, and non-empty diagnostic bounds. A valid event removes the matching failed step's streaming partial and inserts a durable retry notice at the event's sequence position. The notice is `scheduled` until a following retry turn starts; an aborted or disposed source turn marks it `cancelled`, while the retry turn marks it `started`. Normal-mode notices carry their finite maximum; always-mode notices remain explicitly unbounded. Window rebuild and history replay apply the same projection, so logged chunks from the discarded attempt never reappear as an interrupted reply after refresh. A terminal turn without `llm/retry` retains the existing behavior: visible unfinalized output is frozen as an interrupted assistant node.
+
 ## Session forking

 `ISessions.fork({sessionId, atSeq?, increaseTitle?})` resolves only after the child summary is locally addressable, carrying source lineage and cwd with `blank: false`; callers choose whether to open it. With `increaseTitle: true`, the client renames the child from the source session's persisted title: a trailing `(N)` or `（N）` is incremented without changing bracket style, while any other title gets ` (1)` appended; the rename is skipped when the source has no persisted title, and a rename failure rejects the promise but leaves the created child in place. This option is not sent in the Host fork request. A `workspace-attach-failed` response still identifies a child already published by the Host, so `SessionManager` reconciles that partial success before `SessionForkError` reaches the caller instead of making a retry create a duplicate child.
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -30,6 +30,10 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸

 `SessionManager` 独立于列表和 Session 实例到达情况，保留最近一次通过验证的 `session/title` 控制快照。seq 更高的事件会替换旧快照，标题时间戳计入列表新近程度；订阅基线会先丢弃 seq 超过其 `lastSeq` 的任何已保留标题，再接收可选的折叠标题。显式移除 Session 也会清除已保留标题。因此，面向客户端的 `SessionSummary.title` 只包含实际的持久化标题；`displayTitle` 始终存在，并依次回退到 cwd basename 和 Session id。冷态持久化会话会保持该回退值，直到打开或恢复会话，促使主机折叠并投影由日志支撑的标题。`ISession.rename` 用 unary 响应中的 `{title, seq}` 直接结算 `title` 投影格，遵循同一 seq 高者胜规则——列表行和所有 `useProjection('title')` 读者在推送帧到达前即更新；推送帧随后重放同一 seq 时为无操作。

+## 模型重试投影
+
+Session 对象会在事件 wire 边界依据生产方的完整字段契约，验证由插件负责、按提供方路由的 `llm/retry` 载荷，包括计时器、整数、状态、提供方延迟和非空诊断字段的边界。有效事件会移除对应失败步骤的流式输出片段，并在该事件的序列位置插入一条持久的重试提示。该提示在后续重试轮次开始前为 `scheduled`；源轮次中止或释放会将其标记为 `cancelled`，重试轮次则会将其标记为 `started`。normal mode 提示携带其有限上限；always mode 提示则保持显式无界。窗口重建与历史回放应用相同的投影，因此刷新后，来自已丢弃尝试的日志分片绝不会重新显示为中断回复。没有 `llm/retry` 的终止轮次保留现有行为：可见但尚未定稿的输出会冻结为中断的 assistant 节点。
+
 ## 会话 fork

 `ISessions.fork({sessionId, atSeq?, increaseTitle?})` 只在子会话摘要已能在本地寻址后才完成；该摘要携带源会话的谱系和 cwd，且 `blank: false`，由调用方决定是否打开。`increaseTitle: true` 会在 client 端把源会话的持久化标题改名到子会话：尾部 `(N)` 或 `（N）` 递增并保留括号样式，其余标题追加 ` (1)`；源会话没有持久化标题时跳过改名，改名失败时拒绝 promise 但保留已创建的子会话。该选项不会进入 Host fork 请求。即使响应为 `workspace-attach-failed`，其中仍会标识 Host 已发布的子会话，因此 `SessionManager` 会先将这一部分成功对账，再让 `SessionForkError` 到达调用方，避免重试创建重复的子会话。
--- a/packages/client/runtime/package.json
+++ b/packages/client/runtime/package.json
@@ -37,6 +37,7 @@
    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
    "@deepseek-ai/dsh-host-apiproxy": "workspace:^",
    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-llm-retry": "workspace:^",
    "@deepseek-ai/dsh-session": "workspace:^",
    "@deepseek-ai/dsh-session-projection": "workspace:^",
    "@deepseek-ai/dsh-session-title": "workspace:^",
@@ -50,6 +51,7 @@
  },
  "devDependencies": {
    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-timeout": "workspace:^",
    "@types/react": "~18.3.1",
    "cordis": "^4.0.0-rc.7"
  },
--- a/packages/client/runtime/src/client/index.ts
+++ b/packages/client/runtime/src/client/index.ts
@@ -45,7 +45,7 @@ export type {
 export type {
  AssistantBlock, AssistantMessageNode, AssistantProvenanceView, AssistantRequestConfig,
  AssistantTiming, CodeSubCall, CommandNode, ComposerPhase, ContextMessageNode, ConversationNode,
-  ConversationSnapshot, QueuedMessage, RunningToolCall,
+  ConversationSnapshot, ModelRetryNode, QueuedMessage, RunningToolCall,
  SteeringMessageNode, TodoItem, ToolResultNode, UnknownSurfaceNode, UserMessageNode,
 } from './sessions/conversation.ts'
 export type {
--- a/packages/client/runtime/src/client/sessions/conversation.ts
+++ b/packages/client/runtime/src/client/sessions/conversation.ts
@@ -6,6 +6,7 @@
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
 import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment'
+import type { LlmRetryEventData } from '@deepseek-ai/dsh-llm-retry/types'
 import type { TodoItem } from '@deepseek-ai/dsh-session/types'
 import type {
  InboxItemId, RpcError, SessionId, ToolCallView, ToolResultView,
@@ -124,6 +125,19 @@ export interface ContextMessageNode {
  source: unknown
 }

+/** Durable notice that a closed failed step is waiting for a model-request retry. */
+export type ModelRetryNode = LlmRetryEventData & {
+  kind: 'model-retry'
+  seq: number
+  /** Unix epoch ms from the llm/retry session event. */
+  time: number
+  /**
+   * Client-derived lifecycle: scheduled until a retry turn starts, started
+   * once it does, or cancelled when the failed turn aborts first.
+   */
+  retryState: 'scheduled' | 'started' | 'cancelled'
+}
+
 /** A tool result paired (when in-window) with its call head. */
 export interface ToolResultNode {
  kind: 'tool-result'
@@ -186,6 +200,7 @@ export type ConversationNode =
  | AssistantMessageNode
  | SteeringMessageNode
  | ContextMessageNode
+  | ModelRetryNode
  | ToolResultNode
  | CommandNode
  | UnknownSurfaceNode
@@ -268,7 +283,7 @@ export interface PromptError {
 /** The immutable snapshot contract Session hands to uSES (see the web client architecture RFC). */
 export interface ConversationSnapshot {
  sessionId: SessionId
-  /** Surface fold product (finalized conversation nodes in surface order). */
+  /** Finalized surface events and durable operational notices in event order. */
  nodes: readonly ConversationNode[]
  /** Fold degradation flag (cross-window replace defense): when true, nodes come from the lenient linear scan. */
  foldDegraded: boolean
--- a/packages/client/runtime/src/client/sessions/session.ts
+++ b/packages/client/runtime/src/client/sessions/session.ts
@@ -3,6 +3,7 @@
 import type { Context } from 'cordis'
 import type { AttachmentIdType, ImageAttachmentRef } from '@deepseek-ai/dsh-attachment'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
+import type { LlmRetryEventData } from '@deepseek-ai/dsh-llm-retry/types'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 import type {
  HistoryEntry, IApiClient, InboxItemId, MuxFrame, PromptContentPart,
@@ -13,8 +14,8 @@ import type {
 import { transportError } from '@deepseek-ai/dsh-host-apiproxy/api'
 import type { SessionFace } from '../contract/session.ts'
 import type {
-  CodeSubCall, ComposerPhase, ConversationNode, ConversationSnapshot, OpenState,
-  PromptError, QueuedMessage, RunningToolCall,
+  CodeSubCall, ComposerPhase, ConversationNode, ConversationSnapshot, ModelRetryNode,
+  OpenState, PromptError, QueuedMessage, RunningToolCall,
 } from './conversation.ts'
 import type { PendingInteraction } from './pending.ts'
 import { PendingWait } from './pending.ts'
@@ -27,6 +28,10 @@ import type { ProjectionsBaseline } from './projection-store.ts'
 /** Messages requested per history page. */
 export const PAGE_MESSAGES = 50

+// Browser bundles cannot value-import the host timeout library. This protocol
+// bound is pinned to @deepseek-ai/dsh-timeout's MAX_TIMER_DELAY_MS in tests.
+const MAX_RETRY_DELAY_MS = 2_147_483_647
+
 /** Manager-owned observers of a Session object's local state edges. */
 export interface SessionOptions {
  /**
@@ -89,9 +94,9 @@ export class Session implements SessionFace {
  private readonly foldAdapter = new FoldAdapter()
  private partial: PartialAccumulator | null = null
  private openCalls = new Map<string, RunningToolCall>()
-  /** Interrupted-turn terminal nodes (frozen partial text / aborted tool cards), merged into the flow by seq.
-   *  Derived from window events (turn/end sweep) — rebuilt by rebuildDerivedFromWindow like partial/openCalls. */
-  private frozenNodes: ConversationNode[] = []
+  /** Operational notices and interrupted-turn terminal nodes merged into the flow by seq.
+   *  Derived from window events — rebuilt by rebuildDerivedFromWindow like partial/openCalls. */
+  private derivedNodes: ConversationNode[] = []
  private pending = new Map<string, PendingInteraction>()
  // Revision counters preserve array identity when derived content is unchanged, so
  // React.memo children survive unrelated snapshot swaps (chunk storms must not re-render every
@@ -101,12 +106,12 @@ export class Session implements SessionFace {
  private callsCache: { rev: number; value: RunningToolCall[] } | null = null
  private pendingRev = 0
  private pendingCache: { rev: number; value: PendingInteraction[] } | null = null
+  private derivedRev = 0
+  private nodesCache: { folded: readonly ConversationNode[]; derivedRev: number; value: readonly ConversationNode[] } | null = null
  /** Authoritative stream-only inbox snapshot; pending work never hits history. */
  private queued: QueuedMessage[] = []
  private queueRev = 0
  private queueCache: { rev: number; value: QueuedMessage[] } | null = null
-  private frozenRev = 0
-  private nodesCache: { folded: readonly ConversationNode[]; frozenRev: number; value: readonly ConversationNode[] } | null = null
  /** `run_code` sub-dispatches by parent callId (window-derived, like openCalls). Appends
   *  copy-on-write the per-parent array so published snapshot references never mutate. */
  private codeDispatches = new Map<string, readonly CodeSubCall[]>()
@@ -648,8 +653,28 @@ export class Session implements SessionFace {
  }

  /** Per-event side effects (right column of the §A.9 dispatch table):
-   *  chunk accumulation / partial clear on finalize / openCalls add-remove. */
+   *  chunk/retry projection and openCalls add-remove. */
  private applyEventSideEffects(event: SessionEvent, view?: ToolEventView): void {
+    const eventType = event.type as string
+    if (eventType === 'llm/retry') {
+      const data = parseRetryEventData(event.data)
+      if (data === null) {
+        console.error(`[web-runtime] ignored malformed llm/retry event at seq ${event.seq}`)
+        return
+      }
+      if (this.partial !== null && this.partial.turn === data.turn && this.partial.step === data.step) {
+        this.partial = null
+      }
+      this.derivedNodes.push({
+        kind: 'model-retry',
+        seq: event.seq,
+        time: event.time,
+        retryState: 'scheduled',
+        ...data,
+      })
+      this.derivedRev++
+      return
+    }
    // The `tool/code-dispatch-start`/`tool/code-dispatch` pair is declared by
    // the host-side dsh-tools plugin whose types cannot enter the client
    // program (its host Context merges collide with the client's), so this
@@ -710,6 +735,10 @@ export class Session implements SessionFace {
      return
    }
    switch (event.type) {
+      case 'turn/start': {
+        if (event.data.trigger.kind === 'retry') this.settleScheduledRetry('started')
+        return
+      }
      case 'assistant/chunk': {
        const { turn, step, chunk } = event.data
        if (this.partial === null || this.partial.turn !== turn || this.partial.step !== step) {
@@ -738,6 +767,9 @@ export class Session implements SessionFace {
        return
      }
      case 'turn/end': {
+        if (event.data.reason.kind === 'aborted' || event.data.reason.kind === 'disposed') {
+          this.settleScheduledRetry('cancelled', event.data.turn)
+        }
        // Aborted turns never finalize. The accumulated partial is VALUE, not residue: freeze it
        // into an interrupted terminal node (pulse stops, text survives) instead of deleting it.
        // Shared by live and window-replay paths, so a refresh reconstructs the same frozen node
@@ -747,12 +779,12 @@ export class Session implements SessionFace {
          const visible = blocks.some(b => (b.kind === 'text' || b.kind === 'reasoning' ? b.text !== '' : true))
          if (visible) {
            // Fractional seq: strictly after every event of this turn (all < turn/end seq), before the next turn.
-            this.frozenNodes.push({
+            this.derivedNodes.push({
              kind: 'assistant', seq: event.seq - 0.9, time: event.time,
              turn: this.partial.turn, step: this.partial.step,
              blocks, interrupted: true,
            })
-            this.frozenRev++
+            this.derivedRev++
          }
          this.partial = null
        }
@@ -762,7 +794,7 @@ export class Session implements SessionFace {
          this.openCalls.delete(callId)
          this.callsRev++
          // The spinner card becomes an interrupted terminal card (never vanishes mid-flow).
-          this.frozenNodes.push({
+          this.derivedNodes.push({
            kind: 'tool-result', seq: event.seq - 0.8 + callOffset++ * 0.01, time: event.time,
            callId,
            call: { name: call.name, argsRaw: call.argsRaw },
@@ -770,7 +802,7 @@ export class Session implements SessionFace {
            content: [], isError: true, error: { name: 'Interrupted', code: 'interrupted' },
            callView: call.callView, resultView: null,
          })
-          this.frozenRev++
+          this.derivedRev++
        }
        return
      }
@@ -779,15 +811,36 @@ export class Session implements SessionFace {
    }
  }

-  /** Re-derive state (partial/openCalls/frozenNodes) from raw window events after a rebuild — keeps
-   *  paging/stitching consistent, and makes the live freeze and the history replay converge on the
-   *  same interrupted nodes (chunks are logged, so the replayed sweep re-freezes identical text). */
+  /**
+   * Settle the newest scheduled retry, optionally restricted to its failed turn.
+   * @param retryState - next client projection state to publish.
+   * @param turn - failed turn required for cancellation; omitted for the next retry turn start.
+   */
+  private settleScheduledRetry(
+    retryState: Exclude<ModelRetryNode['retryState'], 'scheduled'>,
+    turn?: number,
+  ): void {
+    const index = this.derivedNodes.findLastIndex(node =>
+      node.kind === 'model-retry'
+      && node.retryState === 'scheduled'
+      && (turn === undefined || node.turn === turn))
+    if (index < 0) return
+    const node = this.derivedNodes[index]
+    /* v8 ignore next -- findLastIndex's predicate narrows the indexed node only at runtime. */
+    if (node?.kind !== 'model-retry') return
+    this.derivedNodes[index] = { ...node, retryState }
+    this.derivedRev++
+  }
+
+  /** Re-derive state (partial/openCalls/derivedNodes) from raw window events after a rebuild — keeps
+   *  paging/stitching consistent, and makes live handling and history replay converge on the same
+   *  retry notices and interrupted nodes. */
  private rebuildDerivedFromWindow(): void {
    this.partial = null
    this.openCalls.clear()
    this.callsRev++
-    this.frozenNodes = []
-    this.frozenRev++
+    this.derivedNodes = []
+    this.derivedRev++
    this.codeDispatches = new Map()
    this.dispatchesRev++
    for (let i = 0; i < this.events.length; i++) {
@@ -804,17 +857,17 @@ export class Session implements SessionFace {

  private buildSnapshot(): ConversationSnapshot {
    const { nodes: folded, degraded } = this.foldAdapter.nodes()
-    // Frozen interrupted nodes ride fractional seqs: a stable merge keeps them in flow order.
-    // The merged array is cached on (folded reference, frozenRev) so an unchanged flow keeps its
+    // Derived nodes use their event seq or a nearby fractional seq: a stable merge keeps flow order.
+    // The merged array is cached on (folded reference, derivedRev) so an unchanged flow keeps its
    // reference across snapshot swaps (§A.9.4).
    let nodes: readonly ConversationNode[]
-    if (this.nodesCache !== null && this.nodesCache.folded === folded && this.nodesCache.frozenRev === this.frozenRev) {
+    if (this.nodesCache !== null && this.nodesCache.folded === folded && this.nodesCache.derivedRev === this.derivedRev) {
      nodes = this.nodesCache.value
    } else {
-      nodes = this.frozenNodes.length === 0
+      nodes = this.derivedNodes.length === 0
        ? folded
-        : [...folded, ...this.frozenNodes].sort((a, b) => a.seq - b.seq)
-      this.nodesCache = { folded, frozenRev: this.frozenRev, value: nodes }
+        : [...folded, ...this.derivedNodes].sort((a, b) => a.seq - b.seq)
+      this.nodesCache = { folded, derivedRev: this.derivedRev, value: nodes }
    }
    if (this.callsCache === null || this.callsCache.rev !== this.callsRev) {
      this.callsCache = { rev: this.callsRev, value: [...this.openCalls.values()] }
@@ -858,6 +911,58 @@ export class Session implements SessionFace {
  }
 }

+/** Validate the plugin-owned payload at the session-event wire boundary. */
+function parseRetryEventData(value: unknown): LlmRetryEventData | null {
+  if (value === null || typeof value !== 'object') return null
+  const data = value as Record<string, unknown>
+  const failure = data.failure
+  if (failure === null || typeof failure !== 'object') return null
+  const failureData = failure as Record<string, unknown>
+  if (!nonNegativeSafeInteger(data.turn)
+    || !nonNegativeSafeInteger(data.step)
+    || typeof data.provider !== 'string'
+    || data.provider.length === 0
+    || typeof data.policyKey !== 'string'
+    || data.policyKey.length === 0
+    || !positiveSafeInteger(data.retry)
+    || typeof data.delayMs !== 'number'
+    || !Number.isFinite(data.delayMs)
+    || data.delayMs < 0
+    || data.delayMs > MAX_RETRY_DELAY_MS
+    || typeof failureData.message !== 'string'
+    || failureData.message.length === 0
+    || typeof failureData.code !== 'string'
+    || failureData.code.length === 0) return null
+  if (data.mode === 'normal') {
+    if (!positiveSafeInteger(data.maxRetries) || data.retry > data.maxRetries) return null
+  } else if (data.mode === 'always') {
+    if ('maxRetries' in data) return null
+  } else {
+    return null
+  }
+  if (failureData.status !== undefined
+    && (typeof failureData.status !== 'number'
+      || !Number.isInteger(failureData.status)
+      || failureData.status < 100
+      || failureData.status > 599)) return null
+  if (failureData.providerRetryAfterMs !== undefined
+    && (typeof failureData.providerRetryAfterMs !== 'number'
+      || !Number.isFinite(failureData.providerRetryAfterMs)
+      || failureData.providerRetryAfterMs <= 0)) return null
+  if (failureData.requestId !== undefined
+    && (typeof failureData.requestId !== 'string'
+      || failureData.requestId.length === 0)) return null
+  return data as unknown as LlmRetryEventData
+}
+
+function nonNegativeSafeInteger(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0
+}
+
+function positiveSafeInteger(value: unknown): value is number {
+  return nonNegativeSafeInteger(value) && value > 0
+}
+
 /**
 * The composerPhase judgment — the single site that knows the predicate
 * (consumers switch on the result, never re-derive). Monotone per session
--- a/packages/client/runtime/tests/event-script.ts
+++ b/packages/client/runtime/tests/event-script.ts
@@ -63,7 +63,25 @@ export const ev = {
    }),
  stepEnd: (seq: number, turn: number, step = 0): SessionEvent =>
    at(seq, { type: 'step/end', data: { turn, step } }),
-  turnEnd: (seq: number, turn: number, reason: 'completed' | 'cancelled' = 'completed'): SessionEvent =>
+  retry: (
+    seq: number,
+    turn: number,
+    step = 0,
+    retry = 1,
+    maxRetries = 2,
+    delayMs = 500,
+    message = 'temporary transport failure',
+  ): SessionEvent =>
+    at(seq, {
+      type: 'llm/retry',
+      data: {
+        turn, step,
+        provider: 'fake', mode: 'normal', policyKey: 'fake-normal',
+        retry, maxRetries, delayMs,
+        failure: { code: 'TRANSPORT', message },
+      },
+    }),
+  turnEnd: (seq: number, turn: number, reason: 'completed' | 'aborted' | 'disposed' = 'completed'): SessionEvent =>
    at(seq, { type: 'turn/end', data: { turn, reason: { kind: reason } } }),
  commandRun: (seq: number, commandId: string, name: string, args = ''): SessionEvent =>
    at(seq, { type: 'command/run', data: { commandId, name, args, source: { kind: 'user' } } }),
--- a/packages/client/runtime/tests/session.spec.ts
+++ b/packages/client/runtime/tests/session.spec.ts
@@ -8,6 +8,7 @@

 import { describe, expect, it, vi } from 'vitest'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
 import { Session } from '../src/client/sessions/session.ts'
 import { FakeApiClient, deferred, err, ok } from './fake-api.ts'
@@ -161,6 +162,214 @@ describe('live event path', () => {
    expect((last as { interrupted?: true }).interrupted).toBeUndefined()
  })

+  it('retracts the failed step partial on retry and keeps a replayable notice before the recovered response', async () => {
+    const { session } = await opened()
+    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
+    const retryTurn = [
+      ev.turnStart(6, 1),
+      ev.user(7, '请重试'),
+      ev.stepStart(8, 1),
+      ev.chunkStart(9, 1),
+      ev.chunkText(10, 1, '不完整回复'),
+      ev.stepEnd(11, 1),
+      ev.retry(12, 1, 0, 1, 2, 450, '连接被重置'),
+      at(13, {
+        type: 'turn/end',
+        data: {
+          turn: 1,
+          reason: {
+            kind: 'error', step: 0,
+            failure: { code: 'TRANSPORT', message: '连接被重置' },
+          },
+        },
+      }),
+      at(14, { type: 'turn/start', data: { turn: 2, trigger: { kind: 'retry' } } }),
+      ev.stepStart(15, 2),
+      ev.assistant(16, 2, '完整回复'),
+      ev.stepEnd(17, 2),
+      ev.turnEnd(18, 2),
+    ]
+    for (const event of retryTurn.slice(0, 7)) feed(event)
+
+    let snapshot = session.getSnapshot()
+    expect(snapshot.partial).toBeNull()
+    expect(snapshot.nodes.at(-1)).toMatchObject({
+      kind: 'model-retry',
+      retryState: 'scheduled',
+      turn: 1,
+      step: 0,
+      provider: 'fake',
+      mode: 'normal',
+      policyKey: 'fake-normal',
+      retry: 1,
+      maxRetries: 2,
+      delayMs: 450,
+      failure: { code: 'TRANSPORT', message: '连接被重置' },
+    })
+    expect(JSON.stringify(snapshot.nodes)).not.toContain('不完整回复')
+
+    for (const event of retryTurn.slice(7)) feed(event)
+    snapshot = session.getSnapshot()
+    expect(snapshot.nodes.slice(-2).map(node => node.kind)).toEqual(['model-retry', 'assistant'])
+    expect(snapshot.nodes.at(-2)).toMatchObject({ kind: 'model-retry', retryState: 'started' })
+    expect(snapshot.nodes.at(-1)).toMatchObject({ kind: 'assistant', blocks: [{ kind: 'text', text: '完整回复' }] })
+
+    const replay = makeSession()
+    replay.api.onHistory = () => histResponse([...plainTurn(0, 0, 'a', 'b'), ...retryTurn])
+    await replay.session.open()
+    expect(replay.session.getSnapshot().nodes).toEqual(snapshot.nodes)
+    expect(replay.session.getSnapshot().partial).toBeNull()
+  })
+
+  it('rejects retry payloads outside the producer contract without retracting the current partial', async () => {
+    const { session } = await opened()
+    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
+    feed(ev.turnStart(6, 1))
+    feed(ev.chunkStart(7, 1))
+    feed(ev.chunkText(8, 1, '仍在生成'))
+    const valid = {
+      turn: 1, step: 0,
+      provider: 'fake', mode: 'normal', policyKey: 'fake-normal',
+      retry: 1, maxRetries: 2, delayMs: 500,
+      failure: { code: 'TRANSPORT', message: 'temporary failure' },
+    }
+    const invalid = [
+      { ...valid, turn: Number.MAX_SAFE_INTEGER + 1 },
+      { ...valid, step: Number.MAX_SAFE_INTEGER + 1 },
+      { ...valid, provider: '' },
+      { ...valid, policyKey: '' },
+      { ...valid, retry: Number.MAX_SAFE_INTEGER + 1 },
+      { ...valid, maxRetries: Number.MAX_SAFE_INTEGER + 1 },
+      { ...valid, delayMs: -1 },
+      { ...valid, delayMs: Number.POSITIVE_INFINITY },
+      { ...valid, delayMs: MAX_TIMER_DELAY_MS + 1 },
+      { ...valid, failure: { ...valid.failure, message: '' } },
+      { ...valid, failure: { ...valid.failure, code: '' } },
+      { ...valid, failure: { ...valid.failure, status: '429' } },
+      { ...valid, failure: { ...valid.failure, status: 99 } },
+      { ...valid, failure: { ...valid.failure, status: 429.5 } },
+      { ...valid, failure: { ...valid.failure, status: 600 } },
+      { ...valid, failure: { ...valid.failure, providerRetryAfterMs: 0 } },
+      { ...valid, failure: { ...valid.failure, providerRetryAfterMs: Number.POSITIVE_INFINITY } },
+      { ...valid, failure: { ...valid.failure, requestId: 1 } },
+      { ...valid, failure: { ...valid.failure, requestId: '' } },
+    ]
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+    try {
+      for (const [index, data] of invalid.entries()) {
+        feed(at(9 + index, { type: 'llm/retry', data }))
+      }
+      expect(session.getSnapshot().partial?.blocks).toEqual([{ kind: 'text', text: '仍在生成' }])
+      expect(session.getSnapshot().nodes.filter(node => node.kind === 'model-retry')).toEqual([])
+      expect(errorSpy).toHaveBeenCalledTimes(invalid.length)
+      expect(errorSpy).toHaveBeenCalledWith('[web-runtime] ignored malformed llm/retry event at seq 9')
+    } finally {
+      errorSpy.mockRestore()
+    }
+  })
+
+  it('accepts complete retry payloads at the producer field boundaries', async () => {
+    const { session } = await opened()
+    session.handleMuxEnvelope('r' as never, {
+      type: 'session/event',
+      sessionId: SID,
+      event: at(6, {
+        type: 'llm/retry',
+        data: {
+          turn: Number.MAX_SAFE_INTEGER,
+          step: Number.MAX_SAFE_INTEGER,
+          provider: 'fake',
+          mode: 'normal',
+          policyKey: 'fake-normal',
+          retry: Number.MAX_SAFE_INTEGER,
+          maxRetries: Number.MAX_SAFE_INTEGER,
+          delayMs: MAX_TIMER_DELAY_MS,
+          failure: {
+            code: 'RATE_LIMIT',
+            message: 'provider busy',
+            status: 599,
+            providerRetryAfterMs: Number.MIN_VALUE,
+            requestId: 'req-1',
+          },
+        },
+      }),
+    })
+    expect(session.getSnapshot().nodes.at(-1)).toMatchObject({
+      kind: 'model-retry',
+      retryState: 'scheduled',
+      retry: Number.MAX_SAFE_INTEGER,
+      delayMs: MAX_TIMER_DELAY_MS,
+      failure: { status: 599, providerRetryAfterMs: Number.MIN_VALUE, requestId: 'req-1' },
+    })
+  })
+
+  it('projects always-mode retries and rejects mode-specific maximums or unknown modes', async () => {
+    const { session } = await opened()
+    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+    try {
+      feed(at(6, {
+        type: 'llm/retry',
+        data: {
+          turn: 1, step: 0,
+          provider: 'fake', mode: 'always', policyKey: 'fake-always',
+          retry: 3, delayMs: 500,
+          failure: { code: 'TRANSPORT', message: 'retry forever' },
+        },
+      }))
+      expect(session.getSnapshot().nodes.at(-1)).toMatchObject({
+        kind: 'model-retry',
+        retryState: 'scheduled',
+        mode: 'always',
+        retry: 3,
+      })
+
+      feed(at(7, {
+        type: 'llm/retry',
+        data: {
+          turn: 2, step: 0,
+          provider: 'fake', mode: 'always', policyKey: 'fake-always',
+          retry: 4, maxRetries: 4, delayMs: 500,
+          failure: { code: 'TRANSPORT', message: 'unexpected maximum' },
+        },
+      }))
+      feed(at(8, {
+        type: 'llm/retry',
+        data: {
+          turn: 2, step: 0,
+          provider: 'fake', mode: 'sometimes', policyKey: 'fake-unknown',
+          retry: 4, delayMs: 500,
+          failure: { code: 'TRANSPORT', message: 'unknown mode' },
+        },
+      }))
+      expect(session.getSnapshot().nodes.filter(node => node.kind === 'model-retry')).toHaveLength(1)
+      expect(errorSpy).toHaveBeenCalledTimes(2)
+    } finally {
+      errorSpy.mockRestore()
+    }
+  })
+
+  it.each(['aborted', 'disposed'] as const)(
+    'marks a scheduled retry as cancelled when its failed turn ends %s',
+    async (reason) => {
+      const { session } = await opened()
+      const feed = (event: SessionEvent) => {
+        session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event })
+      }
+      feed(ev.turnStart(6, 1))
+      feed(ev.retry(7, 1))
+      expect(session.getSnapshot().nodes.at(-1)).toMatchObject({
+        kind: 'model-retry',
+        retryState: 'scheduled',
+      })
+      feed(ev.turnEnd(8, 1, reason))
+      expect(session.getSnapshot().nodes.at(-1)).toMatchObject({
+        kind: 'model-retry',
+        retryState: 'cancelled',
+      })
+    },
+  )
+
  it('freezes an unfinalized partial into an interrupted node on turn/end (cancel path)', async () => {
    const { session } = await opened()
    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
@@ -168,7 +377,7 @@ describe('live event path', () => {
    feed(ev.user(7, '要被打断的'))
    feed(ev.chunkStart(8, 1))
    feed(ev.chunkText(9, 1, '说到一半'))
-    feed(ev.turnEnd(10, 1, 'cancelled')) // no assistant/message ever arrives
+    feed(ev.turnEnd(10, 1, 'aborted')) // no assistant/message ever arrives
    const snapshot = session.getSnapshot()
    expect(snapshot.partial).toBeNull()
    const frozen = snapshot.nodes.at(-1)
@@ -187,7 +396,7 @@ describe('live event path', () => {
    expect(session.getSnapshot().runningCalls).toEqual([])
    // Second call never resolves: turn/end freezes it as an error card.
    feed(ev.toolCall(9, 1, 'c2', 'slow_tool', '{}'))
-    feed(ev.turnEnd(10, 1, 'cancelled'))
+    feed(ev.turnEnd(10, 1, 'aborted'))
    const snapshot = session.getSnapshot()
    expect(snapshot.runningCalls).toEqual([])
    expect(snapshot.nodes.at(-1)).toMatchObject({
@@ -544,7 +753,7 @@ describe('remaining branches', () => {
    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
    feed(ev.turnStart(6, 1))
    feed(ev.chunkStart(7, 1)) // empty text block only, no delta
-    feed(ev.turnEnd(8, 1, 'cancelled'))
+    feed(ev.turnEnd(8, 1, 'aborted'))
    const snapshot = session.getSnapshot()
    expect(snapshot.partial).toBeNull()
    expect(snapshot.nodes.filter(n => n.kind === 'assistant' && (n as { interrupted?: true }).interrupted)).toEqual([])
@@ -558,7 +767,7 @@ describe('remaining branches', () => {
    feed(ev.turnStart(6, 1))
    feed(ev.toolCall(7, 1, 'turn1-call', 'echo', '{}'))
    feed(ev.toolCall(8, 2, 'turn2-call', 'echo', '{}')) // stray call attributed to a later turn
-    feed(ev.turnEnd(9, 1, 'cancelled'))
+    feed(ev.turnEnd(9, 1, 'aborted'))
    const snapshot = session.getSnapshot()
    expect(snapshot.runningCalls.map(c => c.callId)).toEqual(['turn2-call'])
    expect(snapshot.nodes.at(-1)).toMatchObject({ kind: 'tool-result', callId: 'turn1-call', isError: true })
@@ -652,7 +861,7 @@ describe('remaining branches', () => {
    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
    feed(ev.turnStart(6, 1))
    feed(at(7, { type: 'assistant/chunk', data: { turn: 1, step: 0, chunk: { type: 'tool-call-delta', index: 0, id: 'c1', name: 'echo', argumentsDelta: '{' } } }))
-    feed(ev.turnEnd(8, 1, 'cancelled'))
+    feed(ev.turnEnd(8, 1, 'aborted'))
    const frozen = session.getSnapshot().nodes.at(-1)
    expect(frozen).toMatchObject({ kind: 'assistant', interrupted: true, blocks: [{ kind: 'tool-call', callId: 'c1' }] })
  })
--- a/packages/client/runtime/tsconfig.json
+++ b/packages/client/runtime/tsconfig.json
@@ -38,6 +38,9 @@
    {
      "path": "../../llm/llm"
    },
+    {
+      "path": "../../llm/llm-retry"
+    },
    {
      "path": "../../support/invariants"
    }