From e5e7c0347e74ddbd59edac79f241070a04cedea1 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 26 Jul 2026 14:47:41 +0800 Subject: [PATCH 1/3] docs(cli): document the DSH_TOOLS_MODE contract in the owning README Responding to ds-review-bot round 2 on #648: the env seam's accepted values, native default, process-wide scope, loud-failure behavior, and temporary status now live in apps/cli/README.md next to the Web/headless surface it configures, not only in the cordis.yml comment. --- apps/cli/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/apps/cli/README.md b/apps/cli/README.md index 4ff9034dd3..50571632c0 100644 --- a/apps/cli/README.md +++ b/apps/cli/README.md @@ -14,6 +14,8 @@ The TUI surface: The Web and headless surfaces boot one shared composition (`cordis.yml`): both treat the invoking directory as the default project and Workspace root, create named Workspaces beneath that root unless `--workspace-root ` overrides it, load applicable `AGENTS.md`/`CLAUDE.md` instructions into each agent-loop request prefix with a 65,536-byte render budget, and opt into first-message model titles. Headless differs only in listening on an OS-assigned port (parallel `dsh -p` runs never collide; the stderr-printed URL opens the live session in a browser). Both need the frontend dist and client bundles built (`pnpm run build && pnpm run build:web`). +`DSH_TOOLS_MODE` selects the tool presentation mode for the whole Web/headless process: `native` (the schema default when unset), `code` (the `run_code`-only Code Mode wire), or `both`; any other value fails loud at boot through the `dsh-tools` config schema. It is a TEMPORARY seam — process-wide because Loader composition is static — and is removed once the web UI owns per-session tool-mode selection; the TUI surface ignores it (its config tree pins its own mode). + ## Install (developer machine) Symlink the source-running launcher onto your PATH; it resolves the checkout through its own real path, so code changes apply on the next launch with no build step: From acf0d42ed89759810c4ca09081eb2e2a1541db1d Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 26 Jul 2026 14:51:03 +0800 Subject: [PATCH 2/3] fix(client-runtime): settled-only dispatch index carries null callTime; README matches MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Responding to ds-review-bot round 2 on #653: the tool/code-dispatch event is appended at settlement, so using its time as callTime fabricated a zero-duration call for duration-aware consumers — it is now null (start unknown) per the ToolResultNode contract, pinned in the session spec. The README's codeDispatches section described the PR3 running→settled lifecycle a stack ahead of this tree; it now documents the settled-only index this PR ships (the running shape lands with the start event in #658, which already merges cleanly over this). --- packages/client/runtime/README.md | 2 +- packages/client/runtime/src/client/sessions/session.ts | 5 ++++- packages/client/runtime/tests/session.spec.ts | 3 +++ 3 files changed, 8 insertions(+), 2 deletions(-) diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md index 12bfaa459b..af164de824 100644 --- a/packages/client/runtime/README.md +++ b/packages/client/runtime/README.md @@ -14,7 +14,7 @@ SlotsService gives the renderer separate bare observables for `useSessions` and ## Code Mode sub-dispatch index -`ConversationSnapshot.codeDispatches` groups a `run_code` call's sub-dispatches under their parent callId, in start order, using the native call-block shapes: a started-but-unsettled sub-call is a `RunningToolCall` (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. Live mux frames and history replay build the identical index; sub-calls never join the surface `nodes` flow; per-parent array and map references are memo-stable across unrelated snapshot swaps. +`ConversationSnapshot.codeDispatches` groups a `run_code` call's sub-dispatches under their parent callId, in dispatch order, as settled `ToolResultNode` entries (the native result shape): each `tool/code-dispatch` event appends one. The event carries only the settle timestamp, so `callTime` is `null` (start unknown) — no duration claim is possible from this index yet. Live mux frames and history replay build the identical index; sub-calls never join the surface `nodes` flow; per-parent array and map references are memo-stable across unrelated snapshot swaps. ## Session title projection diff --git a/packages/client/runtime/src/client/sessions/session.ts b/packages/client/runtime/src/client/sessions/session.ts index 322a2049fd..1c2eac7ea3 100644 --- a/packages/client/runtime/src/client/sessions/session.ts +++ b/packages/client/runtime/src/client/sessions/session.ts @@ -638,7 +638,10 @@ export class Session implements ObservableSnapshot { kind: 'tool-result', seq: event.seq, time: event.time, callId: data.subCallId, call: { name: data.name, argsRaw: JSON.stringify(data.arguments) }, - callTime: event.time, + // The settle event is the only timestamp this event carries; the + // start time is unknown (null per the ToolResultNode contract), so + // duration-aware consumers never see a fabricated zero-duration call. + callTime: null, content: data.content, isError: data.isError, callView: null, resultView: null, } diff --git a/packages/client/runtime/tests/session.spec.ts b/packages/client/runtime/tests/session.spec.ts index beceefce30..9cf153f105 100644 --- a/packages/client/runtime/tests/session.spec.ts +++ b/packages/client/runtime/tests/session.spec.ts @@ -659,6 +659,9 @@ describe('run_code sub-dispatch indexing', () => { expect(subs?.[0]).toMatchObject({ kind: 'tool-result', callId: 'p1:code:1', call: { name: 'bash', argsRaw: '{"command":"ls","description":"列目录"}' }, + // The settle event carries no start time: callTime stays null (never a + // fabricated zero-duration). + callTime: null, isError: false, content: [{ type: 'text', text: 'demo.txt' }], }) expect(subs?.[1]).toMatchObject({ callId: 'p1:code:2', isError: true }) From f9cc62266cfb87c7b3af9b5ab20b0a4138093f55 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 26 Jul 2026 15:26:52 +0800 Subject: [PATCH 3/3] fix(tools): single ordered driver lane for the sub-dispatch scheduler; validate the cap MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Responding to ds-review-bot round 2 on #658 (three critical findings, one warning — all rooted in the pump/commit split racing ordered stages): - ONE driver lane now owns every ordered stage: the start append, prepare (pre-execute/guards), and the head-of-line commit (post-execute, context deferral, settle append). start() is awaited before the next entry can start, so concurrent submissions can no longer run pre-execute pipelines concurrently; only the around-dispatch/body stage overlaps, matching the native loop's fillPool sequencing. - An exclusive call's barrier now holds through its COMMIT: later starts wait for the exclusive pipeline (post-execute included) to finish, the native exclusive-group semantics. - drainDispatches() awaits the driver run itself, so a commit already mid-flight when the program returns is drained before run_code closes the turn — the settle event and deferred contexts land inside it. - maxParallelSubCalls is resolved and validated at construction (positive integer), so direct construction can no longer wedge the pool with 0. New tests: overlapping-submission ordered-prepare, barrier-through-commit, drain-mid-commit, cap rejection. 96 keyless snapshots replay unchanged; Agent Note updated (both languages). --- ...code-mode-live-parallel-dispatch.i18n.yaml | 4 +- ...-07-26-code-mode-live-parallel-dispatch.md | 2 +- ...-26-code-mode-live-parallel-dispatch.zh.md | 2 +- packages/core/tools/src/code-mode.ts | 206 ++++++++++-------- packages/core/tools/src/index.ts | 11 +- packages/core/tools/tests/code-mode.spec.ts | 114 ++++++++++ 6 files changed, 240 insertions(+), 99 deletions(-) diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.i18n.yaml index 6dd3aaf059..91685e9811 100644 --- a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.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 -2026-07-26-code-mode-live-parallel-dispatch.md: f0d13456d63779fb89b9af4cb09bc90c37356a21 -2026-07-26-code-mode-live-parallel-dispatch.zh.md: 5554ab0456f13a2bbc6d5b18e515930f954c6682 +2026-07-26-code-mode-live-parallel-dispatch.md: b4afc21be902d8ed3e5bee2ad1a540413a864f25 +2026-07-26-code-mode-live-parallel-dispatch.zh.md: 409e4cbf9ea3d1b4d1bbe0cd86b494429ebb8a3d diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.md b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.md index f0d13456d6..b4afc21be9 100644 --- a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.md +++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.md @@ -15,7 +15,7 @@ Two gaps remained after the first two PRs. Sub-call rows appeared only when each **One lifecycle pair, one scheduling contract, shared with native.** - **Event pair**: `tool/code-dispatch-start` (parent/sub ids, name, normalized args) is appended when the scheduler actually starts a call — not at submission, so a queued call abandoned by run settlement logs nothing. The existing `tool/code-dispatch` settles the pair (same `subCallId`); every started call settles exactly once (aborts settle as `isError` outcomes through the pipeline). Timing = the two events' `time` fields. Both stay log-only; model context is untouched; format stays v0. -- **Bridge scheduler**: submitted calls are classified at submission via `registry.executionMode` (the SAME fail-closed `isConcurrencySafe` contract the loop uses) and start strictly in submission order. Consecutive parallel-classified calls overlap up to `maxParallelSubCalls` (a validated registry `Config` field, default 10 — the loop scheduler's own default; `1` restores serial dispatch); an exclusive call drains the pool, runs alone, and bars later calls. This is the loop's group semantics adapted to calls that arrive over time instead of in one parsed batch. Run settlement aborts in-flight dispatches and abandons queued-unstarted ones (binding rejection, no events), then drains to quiescence before the outer result closes the turn. +- **Bridge scheduler**: submitted calls are classified at start time via `registry.executionMode` (the SAME fail-closed `isConcurrencySafe` contract the loop uses) and start strictly in submission order. One single-lane driver owns every ORDERED stage — the start append, `prepare` (pre-execute/guards), the head-of-line `finalize`/`finish` commit (post-execute + context deferral + settle append) — so ordered policy stages never overlap each other and only the around-dispatch/body stage runs concurrently, exactly the native loop's sequencing (`fillPool` awaits `startCall` then `commitReady`). Consecutive parallel-classified calls overlap up to `maxParallelSubCalls` (a `Config` field validated by the Loader schema AND re-validated at direct construction, default 10 — the loop scheduler's own default; `1` restores serial dispatch); an exclusive call drains the pool, runs alone, and holds its barrier until its COMMIT completes (post-execute included), like a native exclusive group. Run settlement aborts in-flight dispatches and abandons queued-unstarted ones (binding rejection, no events), then drains to quiescence — including a commit already mid-flight when the program returned — before the outer result closes the turn. - **Client**: `CodeSubCall` widens to `RunningToolCall | ToolResultNode` — a start event lands the running shape in the dispatch index (rows derive the running ring from the shape, exactly as for native in-flight calls), and its settle replaces the entry in place, preserving start order under parallel completion and carrying the start's `time` as `callTime` (duration source). A settle with no observed start (window cut mid-pair, or a pre-start-event log) appends directly, so old logs keep rendering. - **SDK prompt**: the model-facing "calls execute sequentially" sentence is replaced with the true contract (independent safe calls may overlap under `Promise.all`; dependent work sequences with `await`) — a model-visible change, re-recorded across every code-mode snapshot. diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.zh.md b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.zh.md index 5554ab0456..409e4cbf9e 100644 --- a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.zh.md +++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.zh.md @@ -15,7 +15,7 @@ Status: implemented **一对生命周期事件，一份调度契约，与原生共用。** - **事件对**：`tool/code-dispatch-start`（父/子 id、名称、规范化参数）在调度器真正启动某个调用时才追加，而非在提交时，因此因 run 结算而被放弃的排队调用不会留下任何日志。既有的 `tool/code-dispatch` 结算该事件对（`subCallId` 相同）；每个已启动的调用恰好结算一次（中止也会作为 `isError` 结果经由流水线结算）。计时即这两个事件的 `time` 字段。两个事件都保持仅日志；模型上下文不受影响；格式保持 v0。 -- **桥接层调度器**：已提交的调用在提交那一刻就经 `registry.executionMode` 分类（与 loop 所用完全相同的 fail-closed `isConcurrencySafe` 契约），并严格按提交顺序启动。连续被分类为可并行的调用可以重叠执行，上限为 `maxParallelSubCalls`（经校验的注册表 `Config` 字段，默认值 10，即 loop 调度器自身的默认值；设为 `1` 即恢复串行分发）；独占调用则先排空池、独自运行，并阻挡其后的调用。这是把 loop 的分组语义适配到另一种场景：调用随时间陆续到达，而非作为单个已解析的批次一次性到达。run 结算时会中止仍在运行的分发，并放弃已排队未启动的分发（绑定调用被拒绝，不产生事件），随后排空到完全停稳，之后外层结果才结束该轮次。 +- **桥接层调度器**：已提交的调用在启动那一刻经 `registry.executionMode` 分类（与 loop 所用完全相同的 fail-closed `isConcurrencySafe` 契约），并严格按提交顺序启动。所有有序阶段——start 事件追加、`prepare`（pre-execute/守卫）、队首 `finalize`/`finish` 提交（post-execute + 上下文延迟提交 + settle 事件追加）——由单一驱动车道独占执行，因此有序策略阶段彼此绝不重叠，只有 around-dispatch/工具体阶段并发运行，与原生 loop 的时序完全一致（`fillPool` 先 await `startCall` 再 `commitReady`）。连续被分类为可并行的调用可以重叠执行，上限为 `maxParallelSubCalls`（`Config` 字段，Loader schema 校验之外直接构造时也重新校验，默认值 10，即 loop 调度器自身的默认值；设为 `1` 即恢复串行分发）；独占调用则先排空池、独自运行，且其屏障保持到自身提交（含 post-execute）完成为止，与原生独占分组一致。run 结算时会中止仍在运行的分发，并放弃已排队未启动的分发（绑定调用被拒绝，不产生事件），随后排空到完全停稳——包括程序返回时已在途的提交——之后外层结果才结束该轮次。 - **client 侧**：`CodeSubCall` 拓宽为 `RunningToolCall | ToolResultNode`：start 事件把运行中形状写入分发索引（行组件从该形状推导出运行指示环，与原生运行中的调用处理完全一致），其结算事件则原位替换该条目，即使并行完成也保持启动顺序不变，并把 start 事件的 `time` 作为 `callTime`（时长来源）带入。未观察到对应 start 的结算事件（窗口切在事件对中间，或日志录制于 start 事件引入之前）会直接追加，因此旧日志仍能照常渲染。 - **SDK 提示词**：面向模型的「调用按顺序执行」一句替换为真实契约（相互独立的安全调用可以在 `Promise.all` 下重叠执行；相互依赖的工作以 `await` 顺序衔接）；这是模型可见的变更，每一份 code-mode 快照都已重新录制。 diff --git a/packages/core/tools/src/code-mode.ts b/packages/core/tools/src/code-mode.ts index c97338518d..cc25a0e853 100644 --- a/packages/core/tools/src/code-mode.ts +++ b/packages/core/tools/src/code-mode.ts @@ -249,100 +249,114 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () => let dispatches = 0 // The per-run scheduler, reusing the NATIVE concurrency contract through - // the registry's staged view (the loop scheduler's own seam): submitted - // calls START strictly in submission order; only the around-dispatch/body - // stage overlaps — ordered pre-execute runs at start time and ordered - // post-execute/context commitment runs in submission order through the - // commit cursor below, so stateful policy listeners observe submission - // order exactly as they do under the native loop. Consecutive - // parallel-classified calls overlap up to maxParallel; an exclusive call - // waits for the pool to drain, runs alone, and bars later calls. - // Classification is re-read via executionMode() immediately before each - // start (a registry mutation while queued can flip a call exclusive), - // matching the native scheduler's lazy reclassification. + // the registry's staged view (the loop scheduler's own seam) — and the + // native loop's SEQUENCING: every ordered stage (the dispatch-start + // append, prepare = pre-execute/guards, finalize/finish = post-execute, + // context deferral, the settle append) runs inside ONE driver lane, so + // ordered policy stages never overlap each other and only the + // around-dispatch/body stage runs concurrently. Starts are strictly + // submission-ordered; results commit in submission order through the + // head-of-line cursor. Consecutive parallel-classified calls overlap up + // to maxParallel; an exclusive call waits for the pool to drain, runs + // alone, and holds its barrier until its COMMIT (post-execute included) + // completes, exactly like a native exclusive group. Classification is + // re-read via executionMode() immediately before each start (a registry + // mutation while queued can flip a call exclusive), matching the native + // scheduler's lazy reclassification. interface PendingDispatch { - /** Ordered stage: append the start event, prepare, dispatch (body overlaps), park for commit. */ + /** Ordered stage: append the start event, await prepare (pre-execute/guards), launch the body into `flight`. */ start(): Promise classify(): 'parallel' | 'exclusive' abandon(): void /** Ordered stage: post-execute + context deferral + settle event, in submission order. */ commit(): Promise - /** Set once the dispatch stage settles; commit() runs after this resolves. */ - dispatched?: Promise + /** The launched around-dispatch/body stage; resolved until start() replaces it. */ + flight: Promise + /** True once the dispatch stage parked its outcome; the commit cursor waits on it. */ + settled: boolean + /** The classification this entry started under; an exclusive holds its barrier through commit(). */ + mode?: 'parallel' | 'exclusive' } const pendingQueue: PendingDispatch[] = [] const inFlight = new Set>() const commitQueue: PendingDispatch[] = [] - let committing = false let exclusiveActive = false - let pumping = false - /** Ordered commit cursor: drain the head-of-line settled dispatches one at a time. */ - const commitReady = async (): Promise => { - if (committing) return - committing = true - try { - while (commitQueue.length > 0) { - const head = commitQueue[0] - /* v8 ignore next -- the loop condition bounds the index. */ - if (head === undefined) break - /* v8 ignore next -- entries join commitQueue only after start() set dispatched (see pump). */ - if (head.dispatched === undefined) break - await head.dispatched - commitQueue.shift() - await head.commit() - } - } finally { - committing = false - } + let driving = false + let driverRun: Promise = Promise.resolve() + let wake: (() => void) | undefined + const wakeup = (): void => { + const release = wake + wake = undefined + release?.() } - const pump = (): void => { - // Defensive re-entry guard: today every caller (binding submission, - // flight.finally, drain) runs off promise callbacks, never while pump - // is on the stack, so this cannot fire — kept against a future - // synchronous caller. - /* v8 ignore next -- see the re-entry note above. */ - if (pumping) return - pumping = true - try { - for (;;) { - const head = pendingQueue[0] - if (head === undefined) return - if (runController.signal.aborted) { - pendingQueue.shift() - head.abandon() - continue + /** + * The single ordered lane. Each pass commits the head-of-line settled + * dispatch (ordered post-execute), then starts the next queued entry if + * its slot is free (ordered pre-execute), and otherwise sleeps until a + * body settles or a new submission arrives. One run reaching the + * empty-queues/empty-pool state is quiescence. + */ + const drive = (): Promise => { + if (driving) return driverRun + driving = true + driverRun = (async () => { + try { + for (;;) { + // Arm before inspecting state so a settle or submission landing + // between the checks and the await below cannot be lost. + const signal = new Promise((resolve) => { wake = resolve }) + const commitHead = commitQueue[0] + if (commitHead !== undefined && commitHead.settled) { + commitQueue.shift() + await commitHead.commit() + // The barrier covers post-execute: later starts wait for the + // exclusive call's full pipeline, as under the native loop. + if (commitHead.mode === 'exclusive') exclusiveActive = false + continue + } + const head = pendingQueue[0] + if (head !== undefined) { + if (runController.signal.aborted) { + pendingQueue.shift() + head.abandon() + continue + } + // Reclassify at start time (fail-closed on registry changes). + const mode = head.classify() + const capacity = !exclusiveActive + && (mode === 'exclusive' ? inFlight.size === 0 : inFlight.size < maxParallel) + if (capacity) { + if (mode === 'exclusive') exclusiveActive = true + head.mode = mode + pendingQueue.shift() + // Joined before start() so the commit cursor sees submission + // order; nothing commits it until `settled` flips. + commitQueue.push(head) + await head.start() + const flight: Promise = head.flight.finally(() => { + inFlight.delete(flight) + wakeup() + }) + inFlight.add(flight) + continue + } + } + if (pendingQueue.length === 0 && commitQueue.length === 0 && inFlight.size === 0) return + await signal } - // Reclassify at start time (fail-closed on registry changes). - const mode = head.classify() - if (exclusiveActive || inFlight.size >= (mode === 'exclusive' ? 1 : maxParallel)) return - // The guard above already returned for an exclusive head with any - // in-flight sibling, so claiming the barrier here is race-free. - if (mode === 'exclusive') exclusiveActive = true - pendingQueue.shift() - const flight = head.start().finally(() => { - inFlight.delete(flight) - if (mode === 'exclusive') exclusiveActive = false - // Commit ordering and slot refill are independent: the cursor - // may wait head-of-line on an earlier dispatch while later - // slots keep starting. - void commitReady() - pump() - }) - // Joined AFTER start() ran synchronously, so every commitQueue - // entry already carries its `dispatched` promise. - commitQueue.push(head) - inFlight.add(flight) + } finally { + driving = false + wake = undefined } - } finally { - pumping = false - } + })() + return driverRun } - /** Every in-flight dispatch settled AND committed; nothing can start (the run is aborted at call time). */ + /** Every dispatch settled AND committed; nothing can start (the run is aborted at call time). */ const drainDispatches = async (): Promise => { - // Abandon queued-unstarted tasks first, then await the live set until quiescent. - pump() - while (inFlight.size > 0) await Promise.allSettled([...inFlight]) - await commitReady() + // The abort already fired: the driver abandons queued-unstarted + // entries, awaits the live pool, and drains the ordered commit lane — + // including a commit already in progress when the program returned. + await drive() } // Read through a call, not a bare property: the abort state genuinely @@ -368,7 +382,7 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () => type DispatchOutcome = { isError: true; message: string } | { isError: false; value: JsonValue } const scheduler = registry[TOOL_REGISTRY_SCHEDULER] const outcome = await new Promise((resolve, reject) => { - // Set by start(): what commit() finalizes in submission order. + // Set by the dispatch stage (or start() for a pre-settled result): what commit() finalizes in submission order. let parked: | { kind: 'post-result' | 'final-result'; exec: ToolRunContext; result: ToolExecutionResult } | undefined @@ -391,34 +405,37 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () => : { isError: false, value: result.value }) } pendingQueue.push({ - // Re-read per pump pass against the same agent view the SDK + flight: Promise.resolve(), + settled: false, + // Re-read per driver pass against the same agent view the SDK // declared; fail-closed exclusive when undeclared/invalid. classify: () => registry.executionMode(input).kind, abandon: () => { reject(new Error(`run_code run is over (${String(runController.signal.reason)}); ${name} tool call abandoned`)) }, - start(): Promise { + async start(): Promise { exec.agent?.session.append('tool/code-dispatch-start', { parentCallId: exec.callId, subCallId, name, arguments: normalized.logged, }) - // Ordered prepare (pre-execute/guards) runs here — starts are - // strictly submission-ordered; only dispatch overlaps. - this.dispatched = (async () => { - const prepared = await scheduler.prepare(input) - if (prepared.kind === 'dispatch') { - const dispatchOutcome = await scheduler.dispatch(prepared.exec) + // Ordered prepare runs INSIDE the driver lane: the next entry's + // pre-execute waits for this resolution, as under the native + // scheduler. Only the launched body below overlaps. + const prepared = await scheduler.prepare(input) + if (prepared.kind === 'dispatch') { + this.flight = scheduler.dispatch(prepared.exec).then((dispatchOutcome) => { parked = { kind: dispatchOutcome.kind, exec: prepared.exec, result: dispatchOutcome.result } - return - } - parked = { kind: prepared.kind, exec: prepared.exec, result: prepared.result } - })() - return this.dispatched + this.settled = true + }) + return + } + parked = { kind: prepared.kind, exec: prepared.exec, result: prepared.result } + this.settled = true }, async commit(): Promise { - /* v8 ignore next -- commit() runs only after this.dispatched resolved, which set parked. */ + /* v8 ignore next -- commit() runs only after `settled` flipped, which set parked. */ if (parked === undefined) return const result = parked.kind === 'post-result' ? await scheduler.finalize(parked.exec, parked.result) @@ -429,7 +446,8 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () => settle(result) }, }) - pump() + wakeup() + void drive() }) // A budget expiry or outer cancel that lands while this call was in // flight already aborted the dispatch; stop the program now rather diff --git a/packages/core/tools/src/index.ts b/packages/core/tools/src/index.ts index 68a7cefcd4..fe44384e3f 100644 --- a/packages/core/tools/src/index.ts +++ b/packages/core/tools/src/index.ts @@ -635,6 +635,15 @@ interface FusedToolSignal { dispose(): void } +/** Resolve the run_code overlap cap at the owning config boundary (direct construction bypasses the Loader schema). */ +function resolveMaxParallelSubCalls(value: number | undefined): number { + const maxParallelSubCalls = value ?? 10 + if (!Number.isInteger(maxParallelSubCalls) || maxParallelSubCalls < 1) { + throw new Error('maxParallelSubCalls must be a positive integer') + } + return maxParallelSubCalls +} + /** * Tool registry and execution pipeline. Scoped registrations shadow globals; * one visibility resolver feeds presentation, lookup, and dispatch. @@ -681,7 +690,7 @@ export class ToolRegistry extends Service { // the filterable global/scoped capability layers. this.codeTransport = this.mode === 'native' ? undefined - : createRunCodeTool(this, () => this.requireCodeRuntime(), config.maxParallelSubCalls ?? 10) + : createRunCodeTool(this, () => this.requireCodeRuntime(), resolveMaxParallelSubCalls(config.maxParallelSubCalls)) ctx.systemPrompt.tools(context => this.wireSchemas(context.scope)) if (this.mode !== 'native') { ctx.systemPrompt.section({ diff --git a/packages/core/tools/tests/code-mode.spec.ts b/packages/core/tools/tests/code-mode.spec.ts index e227f07544..43a3f7c5d1 100644 --- a/packages/core/tools/tests/code-mode.spec.ts +++ b/packages/core/tools/tests/code-mode.spec.ts @@ -510,6 +510,113 @@ describe('the sub-dispatch scheduler (native concurrency contract)', () => { expect(calls).toEqual([]) }) + it('ordered pre-execute never overlaps: a slow policy on one call delays the next start', async () => { + const { ctx, runtime } = await setup({ mode: 'code' }) + const gated = registerGated(ctx, 'safe_read', true) + const stages: string[] = [] + let releaseGate: (() => void) | undefined + ctx.on('tools/pre-execute', async (preExec, next) => { + if (preExec.name !== 'safe_read') return next() + stages.push(`pre-enter:${String(preExec.callId)}`) + if (releaseGate === undefined) { + // The FIRST call's policy awaits an asynchronous decision. + await new Promise((resolve) => { releaseGate = resolve }) + } + stages.push(`pre-exit:${String(preExec.callId)}`) + return next() + }) + runtime.behavior = async (request) => { + const tools = request.bindings[0]!.functions + const all = Promise.all([tools.safe_read!({ id: 'a' }), tools.safe_read!({ id: 'b' })]) + // Both submissions are in; the second pre-execute must NOT have entered + // while the first is still awaiting its policy decision. + await expect.poll(() => stages.length).toBeGreaterThanOrEqual(1) + expect(stages).toEqual(['pre-enter:call-1:code:1']) + releaseGate!() + await expect.poll(() => gated.pending()).toBe(2) + gated.releaseAll() + await all + return { logs: [], value: 'ordered-prepare' } + } + const result = await runCode(ctx, 'program') + expect(result.isError).toBe(false) + expect(stages).toEqual([ + 'pre-enter:call-1:code:1', 'pre-exit:call-1:code:1', + 'pre-enter:call-1:code:2', 'pre-exit:call-1:code:2', + ]) + }) + + it('an exclusive call holds its barrier through post-execute: the next start waits for the commit', async () => { + const { ctx, runtime } = await setup({ mode: 'code' }) + const writer = registerGated(ctx, 'writer', false) + const reader = registerGated(ctx, 'safe_read', true) + const stages: string[] = [] + let releasePost: (() => void) | undefined + ctx.on('tools/post-execute', async (postExec, _result, next): Promise => { + if (postExec.name === 'writer') { + stages.push('post-enter:writer') + await new Promise((resolve) => { releasePost = resolve }) + stages.push('post-exit:writer') + } + return next() + }) + runtime.behavior = async (request) => { + const tools = request.bindings[0]!.functions + const w = tools.writer!({ id: 'w' }) + const r = tools.safe_read!({ id: 'r' }) + await expect.poll(() => writer.pending()).toBe(1) + writer.release() + // The writer's body is done and its async post-execute is running; the + // parallel read must not have STARTED (no pre/body) while the exclusive + // call's pipeline is still open. + await expect.poll(() => stages).toContain('post-enter:writer') + expect(reader.pending()).toBe(0) + releasePost!() + await w + await expect.poll(() => reader.pending()).toBe(1) + reader.releaseAll() + await r + return { logs: [], value: 'barrier-through-commit' } + } + const result = await runCode(ctx, 'program') + expect(result.isError).toBe(false) + expect(stages).toEqual(['post-enter:writer', 'post-exit:writer']) + }) + + it('run settlement drains a commit already in progress: the settle event lands inside the turn', async () => { + const { ctx, runtime } = await setup({ mode: 'code' }) + const gated = registerGated(ctx, 'safe_read', true) + const { agent, events } = fakeAgent() + let releasePost: (() => void) | undefined + ctx.on('tools/post-execute', async (postExec, _result, next): Promise => { + if (postExec.name === 'safe_read') { + await new Promise((resolve) => { releasePost = resolve }) + } + return next() + }) + runtime.behavior = async (request) => { + // Fire-and-forget: the program returns while the sub-call's async + // post-execute commit is mid-flight. + request.bindings[0]!.functions.safe_read!({ id: 'a' }).catch(() => 'run-over') + await expect.poll(() => gated.pending()).toBe(1) + gated.release() + await expect.poll(() => releasePost !== undefined).toBe(true) + queueMicrotask(() => { releasePost!() }) + return { logs: [], value: 'returned-early' } + } + const result = await runCode(ctx, 'program', { agent }) + expect(result.isError).toBe(false) + // The drain awaited the in-progress commit: the settle event exists and + // preceded the run_code turn closing (all appends happen inside + // execute()). The run's settlement aborted the sub-call's signal while + // its post-execute was mid-flight, so the native cancellation contract + // replaces the successful outcome with the aborted result — the event is + // still durable and in-turn, which is the invariant under test. + const settles = events.filter(event => event.type === 'tool/code-dispatch') + expect(settles).toHaveLength(1) + expect(settles[0]?.data).toMatchObject({ name: 'safe_read', isError: true }) + }) + it('post-execute and context commitment stay in submission order under out-of-order completion', async () => { const { ctx, runtime } = await setup({ mode: 'code' }) const gated = registerGated(ctx, 'safe_read', true) @@ -1293,6 +1400,13 @@ describe('the run_code dispatch bridge', () => { expect(derived[0]?.role).toBe('user') }) + it('direct construction rejects a non-positive parallel sub-call cap at load', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt, {}) + expect(() => new ToolRegistry(ctx, { mode: 'code', maxParallelSubCalls: 0 })) + .toThrow('maxParallelSubCalls must be a positive integer') + }) + it('direct construction in code mode defaults the parallel sub-call cap', async () => { const ctx = new Context() await ctx.plugin(SystemPrompt, {})