refactor(client): localize nested Tool call trees

2026-08-08 17:08:22 +08:00
parent 5e0b7571e6
commit 9ed33dfe4f
48 changed files with 586 additions and 413 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: bb85d3c7b45eb0d82d789a9133bba787f1d6c5e9
-README.zh.md: 18aedbb487a490c85ce68ccc460fd82218157843
+README.md: fad0f6e4f948ebf412b2bd837a4f68e6dc805ec8
+README.zh.md: 4ede12a320082a5023ec121306650fce72a12663
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -44,9 +44,9 @@ Because the projection is log-ordered, the node array is seq-monotonic by constr

 `SessionHistoryInspection.requests` is one chronological, purpose-discriminated provider-request stream. Assistant requests always carry their numeric `turn` and `step`; compaction requests carry `step: 0` and a `turn` owner that may be `null`. That null owner means a manual compaction ran standalone between turns, not that it belongs to either adjacent turn. A `session/end-seed` boundary closes an unmatched compaction request as an error at the boundary time with `Compaction was interrupted before completion.`; a later start projects as an independent request instead of overwriting the orphan.

-## Code Mode sub-dispatch index
+## Code Mode child-call tree

-`ConversationSnapshot.codeDispatches` groups a `run_code` call's sub-dispatches under their parent callId, in start order, using the native call-block shapes: a `tool/code-dispatch-start` event lands the `RunningToolCall` form (rows derive the running ring from the shape) and its `tool/code-dispatch` settlement replaces it in place with the `ToolResultNode` form, `callTime` carrying the paired start's time. A settle whose start fell outside the replay window appends directly with `callTime: null` (duration unknown — never a fabricated zero). Live mux frames and history replay build the identical index; sub-calls never join the transcript `nodes` flow; per-parent array and map references are memo-stable across unrelated snapshot swaps.
+Every `ToolCallBlock` recursively owns its children through `subCalls`, in start order. Runtime's `ToolCallTree` privately maintains the parent-callId-to-children index: a `tool/code-dispatch-start` event lands as a `RunningToolCall`, and the matching `tool/code-dispatch` settlement replaces it in place with a `ToolResultNode` whose `callTime` comes from the paired start. When the start fell outside the replay window, the settlement appends directly with `callTime: null`; Runtime never fabricates a zero duration. Live mux frames and history replay share this fold and tree projection, and child calls never become independent roots in transcript `nodes`. A child update copies only its ancestor path to the owning root; unchanged siblings and other roots retain object identity.

 ## Session title projection

--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -44,9 +44,9 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸

 `SessionHistoryInspection.requests` 是一条按时间顺序排列、以用途为判别字段的提供方请求流。助手请求始终携带数值型 `turn` 与 `step`；压缩请求携带 `step: 0`，其 `turn` 所有者可以是 `null`。这个 null 所有者表示手动压缩独立运行在两个轮次之间，并不表示它属于任一相邻轮次。`session/end-seed` 边界会在边界时刻将未匹配的压缩请求以错误状态结束，错误固定为 `Compaction was interrupted before completion.`；后续 start 会投影为独立请求，而不会覆盖这项遗留的未匹配请求。

-## Code Mode 子调用索引
+## Code Mode 子调用树

-`ConversationSnapshot.codeDispatches` 按父调用的 callId 和启动顺序，用原生调用块形状组织一个 `run_code` 调用的子调用：`tool/code-dispatch-start` 事件落成 `RunningToolCall` 形状（行组件从该形状推导运行中的转圈状态），其 `tool/code-dispatch` 完结事件原位替换为 `ToolResultNode` 形状，`callTime` 携带成对 start 事件的时间。start 落在回放窗口之外的完结事件则直接追加，`callTime: null`（耗时未知——绝不伪造零耗时）。live mux 帧与历史回放构建相同的索引；子调用永不进入 transcript 的 `nodes` 流；无关快照交换不会改变每个父调用对应的数组引用和映射引用，两者均保持 memo 稳定。
+每个 `ToolCallBlock` 都通过 `subCalls` 按启动顺序递归拥有自己的子调用。Runtime 的 `ToolCallTree` 私下维护 parent callId 到 child 的索引：`tool/code-dispatch-start` 事件落成 `RunningToolCall`，对应的 `tool/code-dispatch` 完结事件原位替换为 `ToolResultNode`，其 `callTime` 来自成对 start 事件；start 落在回放窗口之外时，完结事件会以 `callTime: null` 直接追加，绝不伪造零耗时。live mux 帧与历史回放共用这套 fold 和树投影；子调用不会成为 transcript `nodes` 中的独立 root。一次 child 变化只会复制从该 child 到所属 root 的祖先链，未变化的 sibling 和其他 root 保持对象引用稳定。

 ## Session 标题投影

--- a/packages/client/runtime/src/client/index.ts
+++ b/packages/client/runtime/src/client/index.ts
@@ -8,7 +8,7 @@ import { SessionsService } from './sessions/service.ts'
 import type { SessionListState } from './sessions/service.ts'
 import { SessionHistoryService } from './session-history/service.ts'
 import { WorkspacesService } from './workspaces/service.ts'
-import type { ConversationSnapshot, RunningToolCall, ToolResultNode } from './sessions/conversation.ts'
+import type { ConversationSnapshot } from './sessions/conversation.ts'
 import type { UseProjection } from './sessions/projection-store.ts'

 export { SlotsService } from './slots.ts'
@@ -49,10 +49,10 @@ export type {
 } from './contract/store.ts'
 export type {
  AssistantBlock, AssistantMessageNode, AssistantProvenanceView, AssistantRequestConfig,
-  AssistantTiming, CodeSubCall, CommandNode, CompactionSummaryNode, ComposerPhase,
+  AssistantTiming, CommandNode, CompactionSummaryNode, ComposerPhase,
  ContextMessageNode, ConversationNode, ConversationSnapshot, ModelRetryNode, QueuedMessage,
  RunningToolCall,
-  SteeringMessageNode, TodoItem, ToolResultNode, TurnErrorNode, UnknownSurfaceNode, UserMessageNode,
+  SteeringMessageNode, TodoItem, ToolCallBlock, ToolResultNode, TurnErrorNode, UnknownSurfaceNode, UserMessageNode,
 } from './sessions/conversation.ts'
 export type {
  ConversationContext, ConversationContextOriginKind,
@@ -89,13 +89,6 @@ declare module '@deepseek-ai/dsh-type-meta' {
 /** The conversation-snapshot selector hook supplied to session-scoped UI entries. */
 export type UseConversationSession = SnapshotSelectorHook<ConversationSnapshot>

-/**
- * One tool call as the chat flow renders it: still-running (spinner card) or
- * settled (result node). The fold produces both shapes; toolview components
- * narrow on the discriminant fields.
- */
-export type ToolCallBlock = RunningToolCall | ToolResultNode
-
 declare module '@deepseek-ai/dsh-client-ui-slots' {
  /**
   * Session standard kit, real members (ui-slots declares the empty seat;
--- a/packages/client/runtime/src/client/session-history/history-fold.ts
+++ b/packages/client/runtime/src/client/session-history/history-fold.ts
@@ -1,4 +1,3 @@
-import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 import {
  SurfaceManager, isSurfaceEligibleType, isSurfaceEvent,
@@ -7,7 +6,7 @@ import type {
  HistoryEntry, ToolCallView, ToolResultView,
 } from '@deepseek-ai/dsh-client-connection/client'
 import type {
-  AssistantRequestConfig, AssistantTiming, CodeSubCall, ConversationNode,
+  AssistantRequestConfig, AssistantTiming, ConversationNode,
  PartialAssistant, RunningToolCall,
 } from '../sessions/conversation.ts'
 import { toAssistantBlocks } from '../sessions/conversation.ts'
@@ -20,6 +19,7 @@ import type { ConversationPromptSnapshot } from '../sessions/request-inspection.
 import { PartialAccumulator } from '../sessions/partial.ts'
 import type { AssistantStepMetadata } from '../sessions/assistant-timing.ts'
 import { indexAssistantStepTiming, settledAssistantTiming } from '../sessions/assistant-timing.ts'
+import { ToolCallTree } from '../sessions/tool-call-tree.ts'

 interface CallIndexEntry {
  name: string
@@ -41,7 +41,6 @@ export interface ConversationHistoryProjection {
  interruptedNodes: readonly ConversationNode[]
  partial: PartialAssistant | null
  runningCalls: readonly RunningToolCall[]
-  codeDispatches: ReadonlyMap<string, readonly CodeSubCall[]>
 }

 function replacementCrossesWindowHead(event: SessionEvent, baseSeq: number): boolean {
@@ -177,6 +176,7 @@ function materializeNode(
        meta: event.data.meta,
        callView: call?.callView ?? null,
        resultView,
+        subCalls: [],
      }
    }
    default:
@@ -188,74 +188,22 @@ function materializeNode(
 }
 /* jscpd:ignore-end */

-function projectTransient(entries: readonly HistoryEntry[]): Pick<
+interface TransientProjection extends Pick<
  ConversationHistoryProjection,
-  'interruptedNodes' | 'partial' | 'runningCalls' | 'codeDispatches'
+  'interruptedNodes' | 'partial' | 'runningCalls'
 > {
+  toolCallTree: ToolCallTree
+}
+
+function projectTransient(entries: readonly HistoryEntry[]): TransientProjection {
  let partial: PartialAccumulator | null = null
  const openCalls = new Map<string, RunningToolCall>()
  const interruptedNodes: ConversationNode[] = []
-  const codeDispatches = new Map<string, readonly CodeSubCall[]>()
+  const toolCallTree = new ToolCallTree()

  for (const entry of entries) {
    const { event } = entry
-    if ((event.type as string) === 'tool/code-dispatch-start') {
-      const data = event.data as unknown as {
-        parentCallId: string
-        subCallId: string
-        name: string
-        arguments: unknown
-      }
-      const siblings = codeDispatches.get(data.parentCallId) ?? []
-      // The independent replay emits the same public running-call shape as
-      // Chat without reading or mutating Session's live index.
-      /* jscpd:ignore-start */
-      codeDispatches.set(data.parentCallId, [...siblings, {
-        callId: data.subCallId,
-        name: data.name,
-        argsRaw: JSON.stringify(data.arguments),
-        turn: 0,
-        step: 0,
-        time: event.time,
-        callView: null,
-      }])
-      /* jscpd:ignore-end */
-      continue
-    }
-    if ((event.type as string) === 'tool/code-dispatch') {
-      const data = event.data as unknown as {
-        parentCallId: string
-        subCallId: string
-        name: string
-        arguments: unknown
-        isError: boolean
-        content: ContentBlock[]
-      }
-      const siblings = codeDispatches.get(data.parentCallId) ?? []
-      const at = siblings.findIndex(sub => sub.callId === data.subCallId)
-      const started = at === -1 ? undefined : siblings[at]
-      // History independently reproduces the public settled-call shape instead
-      // of consuming Session's live code-dispatch projection.
-      /* jscpd:ignore-start */
-      const settled: CodeSubCall = {
-        kind: 'tool-result', seq: event.seq, time: event.time,
-        callId: data.subCallId,
-        call: { name: data.name, argsRaw: JSON.stringify(data.arguments) },
-        callTime: started?.time ?? null,
-        content: data.content,
-        isError: data.isError,
-        callView: null,
-        resultView: null,
-      }
-      codeDispatches.set(
-        data.parentCallId,
-        at === -1
-          ? [...siblings, settled]
-          : siblings.map((sub, index) => index === at ? settled : sub),
-      )
-      /* jscpd:ignore-end */
-      continue
-    }
+    if (toolCallTree.apply(event)) continue
    switch (event.type) {
      case 'assistant/chunk': {
        const { turn, step, chunk } = event.data
@@ -280,6 +228,7 @@ function projectTransient(entries: readonly HistoryEntry[]): Pick<
          step: event.data.step,
          time: event.time,
          callView: entry.view?.for === 'call' ? entry.view.view : null,
+          subCalls: [],
        })
        /* jscpd:ignore-end */
        break
@@ -317,6 +266,7 @@ function projectTransient(entries: readonly HistoryEntry[]): Pick<
            error: { name: 'Interrupted', code: 'interrupted' },
            callView: call.callView,
            resultView: null,
+            subCalls: [],
          })
          /* jscpd:ignore-end */
        }
@@ -331,7 +281,7 @@ function projectTransient(entries: readonly HistoryEntry[]): Pick<
    interruptedNodes,
    partial: partial?.toPartial() ?? null,
    runningCalls: [...openCalls.values()],
-    codeDispatches,
+    toolCallTree,
  }
 }

@@ -462,9 +412,17 @@ export function projectConversationHistory(
    }
  }

+  const transient = projectTransient(entries)
+  const projectedEventNodes = transient.toolCallTree.projectNodes(eventNodes)
+  const projectedContexts = contexts.map((context): ConversationContext => {
+    const nodes = transient.toolCallTree.projectNodes(context.nodes)
+    return nodes === context.nodes ? context : { ...context, nodes }
+  })
  return {
-    eventNodes,
-    contexts,
-    ...projectTransient(entries),
+    eventNodes: projectedEventNodes,
+    contexts: projectedContexts,
+    interruptedNodes: transient.toolCallTree.projectNodes(transient.interruptedNodes),
+    partial: transient.partial,
+    runningCalls: transient.toolCallTree.projectRunningCalls(transient.runningCalls),
  }
 }
--- a/packages/client/runtime/src/client/sessions/conversation.ts
+++ b/packages/client/runtime/src/client/sessions/conversation.ts
@@ -174,6 +174,8 @@ export interface ToolResultNode {
  callView: ToolCallView | null
  /** Host-computed render intent from this tool/result's wire view; null = same default. */
  resultView: ToolResultView | null
+  /** Child calls owned by this call, in dispatch order. */
+  subCalls: readonly ToolCallBlock[]
 }

 /**
@@ -263,21 +265,6 @@ export type ConversationNode =
  | CompactionSummaryNode
  | UnknownSurfaceNode

-/**
- * One `run_code` sub-dispatch materialized in the native call-block shapes so
- * every consumer (tool rows, details panel) renders it through the exact
- * components that render a native call: a started-but-unsettled sub-call is a
- * {@link RunningToolCall} (rows derive the running state from the shape,
- * exactly as for native calls) and its `tool/code-dispatch` settlement
- * replaces it in place with the {@link ToolResultNode} form. Never part of
- * the transcript `nodes` flow — sub-calls live under their parent via
- * {@link ConversationSnapshot.codeDispatches}. `callId` is the deterministic
- * sub-call id (`<parent>:code:<n>`); the call side carries the sub-tool name
- * and its JSON-stringified logged arguments; `content`/`isError` are the
- * settled sub-call's complete logged outcome.
- */
-export type CodeSubCall = RunningToolCall | ToolResultNode
-
 /** In-flight tool card material: tool/call seen, tool/result not yet. */
 export interface RunningToolCall {
  callId: string
@@ -289,8 +276,12 @@ export interface RunningToolCall {
  time: number
  /** Host-computed render intent riding the tool/call frame; null = generic JSON card. */
  callView: ToolCallView | null
+  /** Child calls owned by this call, in dispatch order. */
+  subCalls: readonly ToolCallBlock[]
 }

+/** One running or settled call, recursively owning its child calls. */
+export type ToolCallBlock = RunningToolCall | ToolResultNode

 /** One transient inbox occurrence from the authoritative `session/queue` snapshot. */
 export interface QueuedMessage {
@@ -355,13 +346,6 @@ export interface ConversationSnapshot {
  turnEnds: ReadonlyMap<number, number>
  partial: PartialAssistant | null
  runningCalls: readonly RunningToolCall[]
-  /**
-   * `run_code` sub-dispatches grouped under their parent callId, in dispatch
-   * order. Populated from in-window `tool/code-dispatch` events (live and
-   * replay identically); the per-parent array reference is stable across
-   * unrelated snapshot swaps (memo premise, same regime as `nodes`).
-   */
-  codeDispatches: ReadonlyMap<string, readonly CodeSubCall[]>
  pending: readonly PendingInteraction[]
  /** Authoritative transient inbox snapshot, including queued and steering placements. */
  queue: readonly QueuedMessage[]
--- a/packages/client/runtime/src/client/sessions/history.ts
+++ b/packages/client/runtime/src/client/sessions/history.ts
@@ -1,7 +1,7 @@
 import type { ToolSchema } from '@deepseek-ai/dsh-llm/types'
 import type { HistoryEntry } from '@deepseek-ai/dsh-client-connection/client'
 import type {
-  CodeSubCall, ConversationNode, PartialAssistant, RunningToolCall,
+  ConversationNode, PartialAssistant, RunningToolCall,
 } from './conversation.ts'
 import type { ConversationContext } from './conversation-context.ts'
 import { projectConversationHistory } from '../session-history/history-fold.ts'
@@ -34,7 +34,6 @@ export interface SessionHistoryInspection {
  interruptedNodes: readonly ConversationNode[]
  partial: PartialAssistant | null
  runningCalls: readonly RunningToolCall[]
-  codeDispatches: ReadonlyMap<string, readonly CodeSubCall[]>
 }

 /**
@@ -112,9 +111,6 @@ export function createHistoryInspection(
    get runningCalls() {
      return conversationProjection().runningCalls
    },
-    get codeDispatches() {
-      return conversationProjection().codeDispatches
-    },
    get requests() {
      return requestProjection().requests
    },
--- a/packages/client/runtime/src/client/sessions/session.ts
+++ b/packages/client/runtime/src/client/sessions/session.ts
@@ -13,7 +13,7 @@ import type {
 import { transportError } from '@deepseek-ai/dsh-host-apiproxy/api'
 import type { SessionFace } from '../contract/session.ts'
 import type {
-  CodeSubCall, ComposerPhase, ConversationNode, ConversationSnapshot, ModelRetryNode,
+  ComposerPhase, ConversationNode, ConversationSnapshot, ModelRetryNode,
  OpenState, PromptError, QueuedMessage, RunningToolCall,
 } from './conversation.ts'
 import type { PendingInteraction } from './pending.ts'
@@ -24,6 +24,7 @@ import { Notifier } from './notifier.ts'
 import { isVisibleAssistantChunk, PartialAccumulator } from './partial.ts'
 import { ProjectionValueStore } from './projection-store.ts'
 import type { ProjectionsBaseline } from './projection-store.ts'
+import { ToolCallTree } from './tool-call-tree.ts'

 /** Messages requested per history page. */
 export const PAGE_MESSAGES = 50
@@ -129,11 +130,8 @@ export class Session implements SessionFace {
  private queued: QueuedMessage[] = []
  private queueRev = 0
  private queueCache: { rev: number; value: QueuedMessage[] } | 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[]>()
-  private dispatchesRev = 0
-  private dispatchesCache: { rev: number; value: ReadonlyMap<string, readonly CodeSubCall[]> } | null = null
+  /** Window-derived child-call lifecycle and immutable tree projection. */
+  private readonly toolCallTree = new ToolCallTree()
  private running = false
  private address: SubagentAddress | undefined
  private parentAvailable = false
@@ -746,65 +744,10 @@ export class Session implements SessionFace {
      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
-    // wire consumer narrows them structurally — the same posture as every
-    // other cross-wire event payload.
-    if ((event.type as string) === 'tool/code-dispatch-start') {
-      // A started sub-dispatch enters the index as a RunningToolCall — the
-      // exact shape a native in-flight call renders from — under its parent
-      // run_code callId; it never joins the surface flow.
-      const data = event.data as unknown as {
-        parentCallId: string
-        subCallId: string
-        name: string
-        arguments: unknown
-      }
-      const running: CodeSubCall = {
-        callId: data.subCallId, name: data.name,
-        argsRaw: JSON.stringify(data.arguments),
-        turn: 0, step: 0, time: event.time, callView: null,
-      }
-      const siblings = this.codeDispatches.get(data.parentCallId) ?? []
-      this.codeDispatches.set(data.parentCallId, [...siblings, running])
-      this.dispatchesRev++
-      return
-    }
-    if ((event.type as string) === 'tool/code-dispatch') {
-      // Settlement replaces the running entry in place (same array position,
-      // so parallel sub-calls keep their start order) with the
-      // ToolResultNode form; a settle with no observed start (history window
-      // cut mid-pair, or a pre-start-event log) appends directly.
-      const data = event.data as unknown as {
-        parentCallId: string
-        subCallId: string
-        name: string
-        arguments: unknown
-        isError: boolean
-        content: ContentBlock[]
-      }
-      const siblings = this.codeDispatches.get(data.parentCallId) ?? []
-      const at = siblings.findIndex(sub => sub.callId === data.subCallId)
-      const started = at === -1 ? undefined : siblings[at]
-      const settled: CodeSubCall = {
-        kind: 'tool-result', seq: event.seq, time: event.time,
-        callId: data.subCallId,
-        call: { name: data.name, argsRaw: JSON.stringify(data.arguments) },
-        // Duration source: the paired start's time when observed; null =
-        // unknown (settle-only window), matching the native tool-result
-        // contract so views never present a fabricated zero duration.
-        callTime: started === undefined ? null : started.time,
-        content: data.content, isError: data.isError,
-        callView: null, resultView: null,
-      }
-      this.codeDispatches.set(
-        data.parentCallId,
-        at === -1 ? [...siblings, settled] : siblings.map((sub, index) => (index === at ? settled : sub)),
-      )
-      this.dispatchesRev++
-      return
-    }
+    // These lifecycle events are declared by a host-only plugin whose Context
+    // types cannot enter the client program. ToolCallTree owns their structural
+    // wire narrowing, pairing, and nested snapshot projection.
+    if (this.toolCallTree.apply(event)) return
    switch (event.type) {
      case 'turn/start':
        this.lastStepByTurn.set(event.data.turn, 0)
@@ -834,6 +777,7 @@ export class Session implements SessionFace {
          callId: String(event.data.callId), name: event.data.name, argsRaw: event.data.arguments,
          turn: event.data.turn, step: event.data.step, time: event.time,
          callView: view?.for === 'call' ? view.view : null,
+          subCalls: [],
        })
        this.callsRev++
        return
@@ -901,7 +845,7 @@ export class Session implements SessionFace {
            call: { name: call.name, argsRaw: call.argsRaw },
            callTime: call.time,
            content: [], isError: true, error: { name: 'Interrupted', code: 'interrupted' },
-            callView: call.callView, resultView: null,
+            callView: call.callView, resultView: null, subCalls: [],
          })
          this.derivedRev++
        }
@@ -948,8 +892,7 @@ export class Session implements SessionFace {
    this.turnTimingsRev++
    this.turnEnds = new Map()
    this.turnEndsRev++
-    this.codeDispatches = new Map()
-    this.dispatchesRev++
+    this.toolCallTree.reset()
    for (let i = 0; i < this.events.length; i++) {
      const event = this.events[i]
      /* v8 ignore next -- dense-array guard: i stays within events.length, so the undefined arm needs a sparse array no caller builds. */
@@ -988,22 +931,18 @@ export class Session implements SessionFace {
    if (this.pendingCache === null || this.pendingCache.rev !== this.pendingRev) {
      this.pendingCache = { rev: this.pendingRev, value: [...this.pending.values()] }
    }
-    if (this.dispatchesCache === null || this.dispatchesCache.rev !== this.dispatchesRev) {
-      this.dispatchesCache = { rev: this.dispatchesRev, value: new Map(this.codeDispatches) }
-    }
    if (this.queueCache === null || this.queueCache.rev !== this.queueRev) {
      this.queueCache = { rev: this.queueRev, value: this.queued }
    }
    const partial = this.partial?.toPartial() ?? null
    return {
      sessionId: this.sessionId,
-      nodes,
+      nodes: this.toolCallTree.projectNodes(nodes),
      turnTimings: this.turnTimingsCache.value,
      turnEnds: this.turnEndsCache.value,
      partial,
-      runningCalls: this.callsCache.value,
+      runningCalls: this.toolCallTree.projectRunningCalls(this.callsCache.value),
      pending: this.pendingCache.value,
-      codeDispatches: this.dispatchesCache.value,
      queue: this.queueCache.value,
      running: this.running,
      subagent: this.address === undefined
--- a/packages/client/runtime/src/client/sessions/tool-call-tree.ts
+++ b/packages/client/runtime/src/client/sessions/tool-call-tree.ts
@@ -0,0 +1,171 @@
+import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import type {
+  ConversationNode, RunningToolCall, ToolCallBlock, ToolResultNode,
+} from './conversation.ts'
+
+interface ProjectedBlock {
+  source: ToolCallBlock
+  children: readonly ToolCallBlock[]
+  value: ToolCallBlock
+}
+
+function sameBlocks(
+  left: readonly ToolCallBlock[],
+  right: readonly ToolCallBlock[],
+): boolean {
+  return left.length === right.length
+    && left.every((block, index) => block === right[index])
+}
+
+/**
+ * Owns Code Dispatch pairing and projects its private parent index into the
+ * recursive Tool call contract exposed by conversation snapshots.
+ */
+export class ToolCallTree {
+  private readonly childrenByParent = new Map<string, readonly ToolCallBlock[]>()
+  private readonly projectedByCall = new Map<string, ProjectedBlock>()
+  private revision = 0
+  private nodesCache: {
+    source: readonly ConversationNode[]
+    revision: number
+    value: readonly ConversationNode[]
+  } | null = null
+  private runningCache: {
+    source: readonly RunningToolCall[]
+    revision: number
+    value: readonly RunningToolCall[]
+  } | null = null
+
+  /** Forget all event-derived child calls before replaying a new window. */
+  reset(): void {
+    this.childrenByParent.clear()
+    this.projectedByCall.clear()
+    this.revision++
+  }
+
+  /**
+   * Fold one event when it belongs to the Code Dispatch lifecycle.
+   * @param event - Session event from the current live or history window.
+   * @returns Whether the event was consumed as a child-call lifecycle event.
+   */
+  apply(event: SessionEvent): boolean {
+    if ((event.type as string) === 'tool/code-dispatch-start') {
+      const data = event.data as unknown as {
+        parentCallId: string
+        subCallId: string
+        name: string
+        arguments: unknown
+      }
+      const running: RunningToolCall = {
+        callId: data.subCallId,
+        name: data.name,
+        argsRaw: JSON.stringify(data.arguments),
+        turn: 0,
+        step: 0,
+        time: event.time,
+        callView: null,
+        subCalls: [],
+      }
+      const siblings = this.childrenByParent.get(data.parentCallId) ?? []
+      this.childrenByParent.set(data.parentCallId, [...siblings, running])
+      this.revision++
+      return true
+    }
+    if ((event.type as string) !== 'tool/code-dispatch') return false
+    const data = event.data as unknown as {
+      parentCallId: string
+      subCallId: string
+      name: string
+      arguments: unknown
+      isError: boolean
+      content: ContentBlock[]
+    }
+    const siblings = this.childrenByParent.get(data.parentCallId) ?? []
+    const at = siblings.findIndex(sub => sub.callId === data.subCallId)
+    const started = at === -1 ? undefined : siblings[at]
+    const settled: ToolResultNode = {
+      kind: 'tool-result',
+      seq: event.seq,
+      time: event.time,
+      callId: data.subCallId,
+      call: { name: data.name, argsRaw: JSON.stringify(data.arguments) },
+      callTime: started?.time ?? null,
+      content: data.content,
+      isError: data.isError,
+      callView: null,
+      resultView: null,
+      subCalls: [],
+    }
+    this.childrenByParent.set(
+      data.parentCallId,
+      at === -1
+        ? [...siblings, settled]
+        : siblings.map((sub, index) => index === at ? settled : sub),
+    )
+    this.revision++
+    return true
+  }
+
+  /**
+   * Attach recursively projected children to all settled roots in a node list.
+   * @param nodes - Cache-stable base conversation nodes.
+   * @returns The original list when no root changed, otherwise a structurally shared list.
+   */
+  projectNodes(nodes: readonly ConversationNode[]): readonly ConversationNode[] {
+    if (this.nodesCache?.source === nodes && this.nodesCache.revision === this.revision) {
+      return this.nodesCache.value
+    }
+    let changed = false
+    const projected = nodes.map((node): ConversationNode => {
+      if (node.kind !== 'tool-result') return node
+      const value = this.projectBlock(node) as ToolResultNode
+      changed ||= value !== node
+      return value
+    })
+    const value = changed ? projected : nodes
+    this.nodesCache = { source: nodes, revision: this.revision, value }
+    return value
+  }
+
+  /**
+   * Attach recursively projected children to all running root calls.
+   * @param calls - Cache-stable base running calls.
+   * @returns The original list when no root changed, otherwise a structurally shared list.
+   */
+  projectRunningCalls(calls: readonly RunningToolCall[]): readonly RunningToolCall[] {
+    if (this.runningCache?.source === calls && this.runningCache.revision === this.revision) {
+      return this.runningCache.value
+    }
+    let changed = false
+    const projected = calls.map((call): RunningToolCall => {
+      const value = this.projectBlock(call) as RunningToolCall
+      changed ||= value !== call
+      return value
+    })
+    const value = changed ? projected : calls
+    this.runningCache = { source: calls, revision: this.revision, value }
+    return value
+  }
+
+  private projectBlock(block: ToolCallBlock): ToolCallBlock {
+    const children = this.childrenByParent.get(block.callId) ?? block.subCalls
+    const projectedChildren = children.map(child => this.projectBlock(child))
+    const childValue = sameBlocks(children, projectedChildren)
+      ? children
+      : projectedChildren
+    const cached = this.projectedByCall.get(block.callId)
+    if (cached?.source === block && sameBlocks(cached.children, childValue)) {
+      return cached.value
+    }
+    const value: ToolCallBlock = block.subCalls === childValue
+      ? block
+      : { ...block, subCalls: childValue }
+    this.projectedByCall.set(block.callId, {
+      source: block,
+      children: childValue,
+      value,
+    })
+    return value
+  }
+}
--- a/packages/client/runtime/src/client/sessions/transcript-adapter.ts
+++ b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
@@ -103,6 +103,7 @@ function materializeNode(
        meta: event.data.meta,
        callView: call?.callView ?? null,
        resultView,
+        subCalls: [],
      }
    }
    /* v8 ignore next 2 -- defensive arm: only the four surface-eligible types
--- a/packages/client/runtime/tests/session.spec.ts
+++ b/packages/client/runtime/tests/session.spec.ts
@@ -1151,7 +1151,17 @@ describe('resync', () => {

 })

-describe('run_code sub-dispatch indexing', () => {
+describe('nested run_code sub-dispatches', () => {
+  const subCallsOf = (session: Session, callId: string) => {
+    const snapshot = session.getSnapshot()
+    const running = snapshot.runningCalls.find(call => call.callId === callId)
+    if (running !== undefined) return running.subCalls
+    for (const node of snapshot.nodes) {
+      if (node.kind === 'tool-result' && node.callId === callId) return node.subCalls
+    }
+    return undefined
+  }
+
  it('a start event lands as a running-shaped sub-call and its settle replaces it in place', async () => {
    const { api, session } = makeSession()
    api.onHistory = () => histResponse(plainTurn(0, 0, '问', '答'))
@@ -1161,19 +1171,19 @@ describe('run_code sub-dispatch indexing', () => {
    feed(ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"1","description":"d"}'))
    feed(ev.codeDispatchStart(8, 'p1', 1, 'bash', { command: 'sleep' }))
    feed(ev.codeDispatchStart(9, 'p1', 2, 'read', { path: 'a.txt' }))
-    const live = session.getSnapshot().codeDispatches.get('p1')
+    const live = subCallsOf(session, 'p1')
    expect(live).toHaveLength(2)
    // Running shape (no 'kind'): the exact RunningToolCall form native rows use.
    expect(live?.[0]).toMatchObject({ callId: 'p1:code:1', name: 'bash', argsRaw: '{"command":"sleep"}' })
    expect(live?.[0] !== undefined && 'kind' in live[0]).toBe(false)
    // Settle out of order (parallel run): #2 first — replaces in place, keeping start order.
    feed(ev.codeDispatch(10, 'p1', 2, 'read', { path: 'a.txt' }, 'alpha'))
-    const mixed = session.getSnapshot().codeDispatches.get('p1')
+    const mixed = subCallsOf(session, 'p1')
    expect(mixed?.map(sub => 'kind' in sub)).toEqual([false, true])
    expect(mixed?.[1]).toMatchObject({ callId: 'p1:code:2', content: [{ type: 'text', text: 'alpha' }] })
    // The settle carries the paired start's time as callTime (duration source).
    feed(ev.codeDispatch(11, 'p1', 1, 'bash', { command: 'sleep' }, 'done'))
-    const settled = session.getSnapshot().codeDispatches.get('p1')
+    const settled = subCallsOf(session, 'p1')
    expect(settled?.map(sub => 'kind' in sub)).toEqual([true, true])
    expect(settled?.[0]).toMatchObject({ callId: 'p1:code:1', callTime: 1_700_000_000_008 })
  })
@@ -1187,7 +1197,7 @@ describe('run_code sub-dispatch indexing', () => {
    feed(ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"return 1","description":"跑一个程序"}'))
    feed(ev.codeDispatch(8, 'p1', 1, 'bash', { command: 'ls', description: '列目录' }, 'demo.txt'))
    feed(ev.codeDispatch(9, 'p1', 2, 'read', { path: 'a.txt' }, 'Error: ENOENT', true))
-    const subs = session.getSnapshot().codeDispatches.get('p1')
+    const subs = subCallsOf(session, 'p1')
    expect(subs).toHaveLength(2)
    expect(subs?.[0]).toMatchObject({
      kind: 'tool-result', callId: 'p1:code:1',
@@ -1205,23 +1215,29 @@ describe('run_code sub-dispatch indexing', () => {
    expect(session.getSnapshot().nodes.some(n => n.kind === 'tool-result' && n.callId.includes(':code:'))).toBe(false)
  })

-  it('rebuilds the same index from a history window (replay parity)', async () => {
+  it('rebuilds the same nested tree from a history window (replay parity)', async () => {
    const { api, session } = makeSession()
    api.onHistory = () => histResponse([
      ...plainTurn(0, 0, '问', '答'),
      ev.turnStart(6, 1),
      ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"return 1","description":"跑一个程序"}'),
-      ev.codeDispatch(8, 'p1', 1, 'bash', { command: 'ls' }, 'demo.txt'),
-      ev.toolResult(9, 1, 'p1', '{"done":true}'),
-      ev.turnEnd(10, 1),
+      ev.codeDispatchStart(8, 'p1', 1, 'run_code', { code: 'return tools.read({ path: "a.txt" })' }),
+      ev.codeDispatch(9, 'p1:code:1', 1, 'read', { path: 'a.txt' }, 'alpha'),
+      ev.codeDispatch(10, 'p1', 1, 'run_code', { code: 'return tools.read({ path: "a.txt" })' }, 'alpha'),
+      ev.toolResult(11, 1, 'p1', '{"done":true}'),
+      ev.turnEnd(12, 1),
    ])
    await session.open()
-    const subs = session.getSnapshot().codeDispatches.get('p1')
+    const subs = subCallsOf(session, 'p1')
    expect(subs).toHaveLength(1)
-    expect(subs?.[0]).toMatchObject({ callId: 'p1:code:1', call: { name: 'bash' } })
+    expect(subs?.[0]).toMatchObject({
+      callId: 'p1:code:1',
+      call: { name: 'run_code' },
+      subCalls: [{ callId: 'p1:code:1:code:1', call: { name: 'read' } }],
+    })
  })

-  it('keeps the dispatch map reference across unrelated changes and swaps it on a new dispatch', async () => {
+  it('keeps an unaffected root reference and path-copies it on a new child', async () => {
    const { api, session } = makeSession()
    api.onHistory = () => histResponse(plainTurn(0, 0, '稳', '定'))
    await session.open()
@@ -1230,13 +1246,48 @@ describe('run_code sub-dispatch indexing', () => {
    feed(ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"1","description":"d"}'))
    feed(ev.codeDispatch(8, 'p1', 1, 'bash', { command: 'ls' }, 'x'))
    const before = session.getSnapshot()
+    const beforeRoot = before.runningCalls.find(call => call.callId === 'p1')!
    feed(ev.chunkStart(9, 1))
    feed(ev.chunkText(10, 1, '流式'))
    const after = session.getSnapshot()
-    expect(after.codeDispatches).toBe(before.codeDispatches)
+    const afterRoot = after.runningCalls.find(call => call.callId === 'p1')!
+    expect(afterRoot).toBe(beforeRoot)
    feed(ev.codeDispatch(11, 'p1', 2, 'read', { path: 'a' }, 'y'))
-    expect(session.getSnapshot().codeDispatches).not.toBe(after.codeDispatches)
-    expect(session.getSnapshot().codeDispatches.get('p1')).toHaveLength(2)
+    const changedRoot = session.getSnapshot().runningCalls.find(call => call.callId === 'p1')!
+    expect(changedRoot).not.toBe(afterRoot)
+    expect(changedRoot.subCalls[0]).toBe(afterRoot.subCalls[0])
+    expect(changedRoot.subCalls).toHaveLength(2)
+  })
+
+  it('path-copies only the owning branch when a nested child changes', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(0, 0, '树', '结构'))
+    await session.open()
+    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
+    feed(ev.turnStart(6, 1))
+    feed(ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"1","description":"first"}'))
+    feed(ev.toolCall(8, 1, 'p2', 'run_code', '{"code":"2","description":"second"}'))
+    feed(ev.codeDispatch(9, 'p1', 1, 'run_code', { code: 'nested' }, 'child'))
+    feed(ev.codeDispatch(10, 'p1', 2, 'read', { path: 'sibling' }, 'sibling'))
+    feed(ev.codeDispatch(11, 'p2', 1, 'bash', { command: 'pwd' }, 'root two'))
+    const before = session.getSnapshot()
+    const beforeFirst = before.runningCalls.find(call => call.callId === 'p1')!
+    const beforeSecond = before.runningCalls.find(call => call.callId === 'p2')!
+    const beforeChild = beforeFirst.subCalls[0]!
+    const beforeSibling = beforeFirst.subCalls[1]!
+
+    feed(ev.codeDispatch(12, 'p1:code:1', 1, 'read', { path: 'nested' }, 'leaf'))
+    const after = session.getSnapshot()
+    const afterFirst = after.runningCalls.find(call => call.callId === 'p1')!
+    const afterSecond = after.runningCalls.find(call => call.callId === 'p2')!
+
+    expect(afterFirst).not.toBe(beforeFirst)
+    expect(afterSecond).toBe(beforeSecond)
+    expect(afterFirst.subCalls[0]).not.toBe(beforeChild)
+    expect(afterFirst.subCalls[1]).toBe(beforeSibling)
+    expect(afterFirst.subCalls[0]?.subCalls).toMatchObject([
+      { callId: 'p1:code:1:code:1', call: { name: 'read' } },
+    ])
  })
 })