feat(tools): live dispatch lifecycle + native-contract parallel sub-calls in Code Mode

The bridge replaces its serialization queue with a pool that reuses the native concurrency contract: submissions classify through registry.executionMode (fail-closed isConcurrencySafe), start strictly in submission order, overlap up to the validated maxParallelSubCalls config (default 10; 1 restores serial), and exclusive calls drain the pool, run alone, and bar later calls. Each started sub-call logs a tool/code-dispatch-start event at pool entry; the existing tool/code-dispatch settles the pair (started ⇔ settles exactly once; abandoned queued calls log neither). SDK prompt guidance now states the true Promise.all contract — re-recorded across every code/both-mode snapshot (plus the stale cordis-dynamic-toolchain fixture gaining the required description arg). Client: CodeSubCall widens to RunningToolCall | ToolResultNode — starts land the running shape (rows wear the native running ring), settles replace in place preserving start order, callTime pairs to the start time. Fixture emits start/settle pairs; jsdom pins the running sub-row; runtime specs pin in-place settlement and out-of-order completion.
2026-07-26 06:02:36 +08:00
parent 526651cb88
commit 8a79679489
34 changed files with 1921 additions and 1673 deletions
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -144,30 +144,22 @@ function buildAlphaLog(): SessionEvent[] {
      data: { turn, step: 0, content: [{ type: 'tool-call', id: callId, name: 'run_code', arguments: args } as ContentBlock], provenance: { provider: 'fixture', model: 'fx-1' } },
    })
    push({ type: 'tool/call', data: { turn, step: 0, callId, name: 'run_code', arguments: args } })
-    push({
-      type: 'tool/code-dispatch',
-      data: {
-        parentCallId: callId, subCallId: `${callId}:code:1`, name: 'bash',
-        arguments: { command: 'ls notes', description: 'List notes' },
-        isError: false, content: [{ type: 'text', text: 'demo.txt\nnew-demo.txt' }],
-      },
-    })
-    push({
-      type: 'tool/code-dispatch',
-      data: {
-        parentCallId: callId, subCallId: `${callId}:code:2`, name: 'read',
-        arguments: { path: 'notes/demo.txt' },
-        isError: false, content: [{ type: 'text', text: 'hello fixture\n' }],
-      },
-    })
-    push({
-      type: 'tool/code-dispatch',
-      data: {
-        parentCallId: callId, subCallId: `${callId}:code:3`, name: 'read',
-        arguments: { path: 'notes/missing.txt' },
-        isError: true, content: [{ type: 'text', text: 'Error: ENOENT: notes/missing.txt not found' }],
-      },
-    })
+    const dispatchPair = (n: number, name: string, dispatchArgs: Record<string, unknown>, resultText: string, isError = false): void => {
+      push({
+        type: 'tool/code-dispatch-start',
+        data: { parentCallId: callId, subCallId: `${callId}:code:${n}`, name, arguments: dispatchArgs },
+      })
+      push({
+        type: 'tool/code-dispatch',
+        data: {
+          parentCallId: callId, subCallId: `${callId}:code:${n}`, name,
+          arguments: dispatchArgs, isError, content: [{ type: 'text', text: resultText }],
+        },
+      })
+    }
+    dispatchPair(1, 'bash', { command: 'ls notes', description: 'List notes' }, 'demo.txt\nnew-demo.txt')
+    dispatchPair(2, 'read', { path: 'notes/demo.txt' }, 'hello fixture\n')
+    dispatchPair(3, 'read', { path: 'notes/missing.txt' }, 'Error: ENOENT: notes/missing.txt not found', true)
    push({
      type: 'tool/result', surfaceOp: 'append',
      data: { turn, step: 0, callId, content: text('{"listing":"demo.txt\\nnew-demo.txt","demo":"hello fixture\\n"}'), isError: false },
--- a/packages/client/runtime/src/client/sessions/conversation.ts
+++ b/packages/client/runtime/src/client/sessions/conversation.ts
@@ -128,15 +128,19 @@ export type ConversationNode =
  | UnknownSurfaceNode

 /**
- * One `run_code` sub-dispatch materialized as a {@link ToolResultNode} so every
- * consumer (tool rows, details panel) renders it through the exact components
- * that render a native settled call. Never part of the surface `nodes` flow —
- * sub-calls live under their parent via {@link ConversationSnapshot.codeDispatches}.
- * `callId` is the deterministic sub-call id (`<parent>:code:<n>`); `call`
- * carries the sub-tool name and its JSON-stringified logged arguments;
- * `content`/`isError` are the sub-call's complete logged outcome.
+ * 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 surface `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 = ToolResultNode
+export type CodeSubCall = RunningToolCall | ToolResultNode

 /** In-flight tool card material: tool/call seen, tool/result not yet. */
 export interface RunningToolCall {
--- a/packages/client/runtime/src/client/sessions/session.ts
+++ b/packages/client/runtime/src/client/sessions/session.ts
@@ -616,14 +616,36 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
  /** Per-event side effects (right column of the §A.9 dispatch table):
   *  chunk accumulation / partial clear on finalize / openCalls add-remove. */
  private applyEventSideEffects(event: SessionEvent, view?: ToolEventView): void {
-    // `tool/code-dispatch` 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 it structurally —
-    // the same posture as every other cross-wire event payload.
+    // 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') {
-      // A sub-dispatch becomes a ToolResultNode so rows and the details
-      // panel reuse the native rendering path verbatim; it indexes under its
-      // parent run_code callId and never joins the surface flow.
+      // 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
@@ -632,17 +654,22 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
        isError: boolean
        content: ContentBlock[]
      }
-      const parent = data.parentCallId
-      const siblings = this.codeDispatches.get(parent) ?? []
-      const sub: CodeSubCall = {
+      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) },
-        callTime: event.time,
+        // Duration source: the paired start's time when observed.
+        callTime: started === undefined ? event.time : started.time,
        content: data.content, isError: data.isError,
        callView: null, resultView: null,
      }
-      this.codeDispatches.set(parent, [...siblings, sub])
+      this.codeDispatches.set(
+        data.parentCallId,
+        at === -1 ? [...siblings, settled] : siblings.map((sub, index) => (index === at ? settled : sub)),
+      )
      this.dispatchesRev++
      return
    }
--- a/packages/client/runtime/tests/event-script.ts
+++ b/packages/client/runtime/tests/event-script.ts
@@ -26,6 +26,11 @@ export const ev = {
    at(seq, { type: 'tool/call', data: { turn, step, callId, name, arguments: args } }),
  toolResult: (seq: number, turn: number, callId: string, body: string, step = 0): SessionEvent =>
    at(seq, { type: 'tool/result', surfaceOp: 'append', data: { turn, step, callId, content: text(body), isError: false } }),
+  codeDispatchStart: (seq: number, parentCallId: string, n: number, name: string, args: unknown): SessionEvent =>
+    at(seq, {
+      type: 'tool/code-dispatch-start',
+      data: { parentCallId, subCallId: `${parentCallId}:code:${n}`, name, arguments: args },
+    }),
  codeDispatch: (seq: number, parentCallId: string, n: number, name: string, args: unknown, body: string, isError = false): SessionEvent =>
    at(seq, {
      type: 'tool/code-dispatch',
--- a/packages/client/runtime/tests/session.spec.ts
+++ b/packages/client/runtime/tests/session.spec.ts
@@ -645,6 +645,32 @@ describe('resync', () => {
 })

 describe('run_code sub-dispatch indexing', () => {
+  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, '问', '答'))
+    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":"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')
+    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')
+    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')
+    expect(settled?.map(sub => 'kind' in sub)).toEqual([true, true])
+    expect(settled?.[0]).toMatchObject({ callId: 'p1:code:1', callTime: 1_700_000_000_008 })
+  })
+
  it('indexes live tool/code-dispatch events under their parent as native-shaped result nodes', async () => {
    const { api, session } = makeSession()
    api.onHistory = () => histResponse(plainTurn(0, 0, '问', '答'))
--- a/packages/client/ui-conversation/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
@@ -20,7 +20,7 @@ import {
  memo, useLayoutEffect, useMemo, useRef, useState, type ReactNode,
 } from 'react'
 import type {
-  ConversationNode, ConversationSnapshot, RunningToolCall, ToolResultNode,
+  CodeSubCall, ConversationNode, ConversationSnapshot, RunningToolCall, ToolResultNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
 import { IconChevronDownOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
@@ -46,18 +46,22 @@ type RenderToolRow = ChatViewSlotProps['renderSlot']
 type UseConversation = SnapshotSelectorHook<ConversationSnapshot>

 /** One `run_code` sub-dispatch row: the identical keyed-slot dispatch as a
- *  top-level call (same registrations, same fallback), nested by the parent. */
+ *  top-level call (same registrations, same fallback), nested by the parent.
+ *  A started-but-unsettled sub-call arrives as the RunningToolCall shape and
+ *  renders the running state exactly as a native in-flight row. */
 const SubCallRow = memo(function SubCallRow({ renderSlot, node, onOpenDetails, selected }: {
  renderSlot: RenderToolRow
-  node: ToolResultNode
+  node: CodeSubCall
  onOpenDetails: OpenDetails
  selected: boolean
 }) {
-  const toolName = node.call?.name ?? ''
+  const settled = 'kind' in node
+  const toolName = settled ? node.call?.name ?? '' : node.name
+  const seq = settled ? node.seq : node.time
  const owner = useMemo(() => ({
    callId: node.callId, toolName, block: node,
-    openDetails: () => { onOpenDetails({ turnSeq: node.seq, callId: node.callId, toolName }) },
-  }), [node, toolName, onOpenDetails])
+    openDetails: () => { onOpenDetails({ turnSeq: seq, callId: node.callId, toolName }) },
+  }), [node, toolName, seq, onOpenDetails])
  return (
    <div className={css.callRow} data-selected={selected || undefined}>
      {renderSlot('conversation.chat.toolview', owner, {
@@ -82,8 +86,8 @@ const CallRow = memo(function CallRow({ renderSlot, callId, toolName, block, seq
  seq: number
  onOpenDetails: OpenDetails
  selected: boolean
-  /** `run_code` sub-dispatches in dispatch order (reference-stable per parent); undefined for ordinary calls. */
-  subCalls?: readonly ToolResultNode[] | undefined
+  /** `run_code` sub-dispatches in dispatch order (reference-stable per parent; running entries settle in place); undefined for ordinary calls. */
+  subCalls?: readonly CodeSubCall[] | undefined
  /** The store's selected callId, matched against sub-rows (undefined when no sub-row here is selected). */
  selectedCallId?: string | undefined
 }) {
@@ -122,7 +126,7 @@ const ToolGroup = memo(function ToolGroup({ renderSlot, results, onOpenDetails,
  /** Only set when the selected call lives in THIS group, top-level or nested (memo economy). */
  selectedCallId: string | undefined
  /** Sub-dispatch index off the snapshot (map reference is chunk-storm stable). */
-  codeDispatches: ReadonlyMap<string, readonly ToolResultNode[]>
+  codeDispatches: ReadonlyMap<string, readonly CodeSubCall[]>
 }) {
  return (
    <div className={css.toolGroup}>
--- a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
@@ -31,13 +31,16 @@ function materialFor(s: ConversationSnapshot, callId: string): CallMaterial | nu
  if (open !== undefined) {
    return { name: open.name, argsRaw: open.argsRaw, result: null, running: true }
  }
-  // run_code sub-dispatches: already ToolResultNode-shaped, so a selected
-  // sub-row resolves through the same material as a native settled call.
+  // run_code sub-dispatches: the native call-block shapes, so a selected
+  // sub-row resolves through the same material as a native call — the
+  // settled ToolResultNode form, or the RunningToolCall form mid-flight.
  for (const subs of s.codeDispatches.values()) {
    for (const sub of subs) {
-      if (sub.callId === callId) {
+      if (sub.callId !== callId) continue
+      if ('kind' in sub) {
        return { name: sub.call?.name ?? callId, argsRaw: sub.call?.argsRaw ?? null, result: sub, running: false }
      }
+      return { name: sub.name, argsRaw: sub.argsRaw, result: null, running: true }
    }
  }
  return null
--- a/packages/client/ui-conversation/tests/chat-code-subcalls.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-code-subcalls.spec.tsx
@@ -199,6 +199,21 @@ describe('run_code sub-calls through the real chat machinery', () => {
    expect(nest!.querySelector('[data-sample="bash-global"]')).not.toBeNull()
  })

+  it('a started-but-unsettled sub-call renders the running state exactly like a native in-flight row', async () => {
+    const parent = 'call-live'
+    const runningSub: CodeSubCall = {
+      callId: `${parent}:code:1`, name: 'grep', argsRaw: '{"pattern":"todo"}',
+      turn: 0, step: 0, time: 21_000, callView: null,
+    }
+    const dispatches = new Map([[parent, [runningSub]]])
+    const b = await bench(snapshotWith([], dispatches, [runningCode(parent)]))
+    const view = mountApp(b.slots)
+    // The nested row derives 'running' from the RunningToolCall shape — the
+    // same StateDot ring a native in-flight row wears.
+    const nested = view.container.querySelector('[data-subcalls] [data-variant][data-state="running"]')
+    expect(nested).not.toBeNull()
+  })
+
  it('an ordinary tool row renders no sub-call nest', async () => {
    const parent = 'call-64'
    const plain: ToolResultNode = {