diff --git a/.github/workflows/e2e.yml b/.github/workflows/e2e.yml index a2015696f4..dd3965f5cd 100644 --- a/.github/workflows/e2e.yml +++ b/.github/workflows/e2e.yml @@ -110,9 +110,14 @@ jobs: fi echo "DEEPSEEK_API_KEY present." + # The e2e suites boot the example bins in `lib` mode (DSH_EXAMPLE_MODE=lib): + # the built artifact under plain Node, resolving plugins through real package + # exports — the shape a real consumer runs. That requires a prior build. + - name: Build (lib for the e2e example bins) + run: pnpm run build + # Real-API end-to-end tests only. The keyless gates (lint/typecheck/ - # coverage/snapshot/build/etc.) already run in ci.yml on every push/PR; - # no need to repeat them or build first (tests run unbuilt via tsx). + # coverage/snapshot/etc.) already run in ci.yml on every push/PR. # DEEPSEEK_BASE_URL is pinned to the external API; the secret is scoped to # this step (and preflight) only — never exposed to checkout/setup/install. - name: E2E tests (real DeepSeek API) @@ -120,4 +125,5 @@ jobs: DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY_EXTERNAL }} DEEPSEEK_BASE_URL: https://api.deepseek.com DSH_E2E_MAX_WORKERS: 14 + DSH_EXAMPLE_MODE: lib run: pnpm run test:e2e diff --git a/AGENTS.md b/AGENTS.md index 21e9877e05..e551a7de10 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -99,7 +99,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`, ## Conventions - Every npm package is `@deepseek-ai/dsh-`; vendored packages keep upstream names and are `private: true`. `cordis` is a peerDependency (+ dev) of every harness package. -- ESM everywhere (`"type": "module"`). Cross-package imports use package names, never relative paths; in-package relative imports use explicit `.ts` extensions. Dev/test/demo run unbuilt via tsx + the root tsconfig `paths` map; builds are for outside consumers only. +- ESM everywhere (`"type": "module"`). Cross-package imports use package names; in-package relative imports include `.ts`. CI subprocesses that boot examples or Cordis configs run built `lib/` under plain Node; only explicit source-path regressions use tsx ([testing policy](docs/testing.md#test-subprocess-launch-modes)). - **Registrations are effects**: every contribution goes through `ctx.effect()` / `ctx.on()`; a registry's `register()` returns the disposer. - **Typed events use declaration merging** and merge-extensible maps. Event JSDoc needs `@mode` and payload `@param`; scoped keys absent from payloads need `@dshScopeScan unsupported`. Public service methods document parameters and non-void returns. - **Switch on discriminant tags.** Closed unions end in `assertNever`; merge-extensible unions fall through a documented default. diff --git a/docs/agent-lifecycle.md b/docs/agent-lifecycle.md index b9292aa80e..c753f59992 100644 --- a/docs/agent-lifecycle.md +++ b/docs/agent-lifecycle.md @@ -34,10 +34,19 @@ sequenceDiagram Session-->>SDK: session/event assistant/chunk* Driver->>Hooks: agent/step-result waterfall Driver->>Session: assistant/message - Driver->>Session: tool/call - Driver->>Tools: execute through pre and post waterfalls - Tools-->>Session: tool-owned events when applicable - Driver->>Session: tool/result and step/end + Driver->>Tools: classify pending call by executionMode + loop barriers and bounded rolling pool, reclassify before start + opt call starts + Driver->>Session: tool/call + Driver->>Tools: ordered pre, concurrent execute + Tools-->>Session: tool-owned events when applicable + end + opt next model-order result ready + Driver->>Tools: ordered post + Driver->>Session: tool/result + end + end + Driver->>Session: step/end Driver->>Hooks: agent/turn-continuation waterfall Driver->>Hooks: agent/turn-stop serial terminal checkpoint Driver->>Session: turn/end diff --git a/docs/architecture.md b/docs/architecture.md index e77870ec3a..d4abf10283 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -83,11 +83,12 @@ forever: 'assistant/chunk' agent/step-result 'assistant/message' (transformed content or empty success anchor after step-result rejection) - each tool call: - 'tool/call' - tools/pre-execute -> monotonic guards -> tools/execute -> tools/post-execute -> tools/result - 'tool/result' - append post-tool context and steering + schedule tool calls by ctx.tools.executionMode: + exclusive -> one-call barrier + parallel -> rolling pool, <= maxParallelToolCalls in flight; reclassify before start + each start -> 'tool/call' -> ordered tools/pre-execute -> concurrent tools/execute + each model-order result -> ordered tools/post-execute -> 'tool/result' + append accepted tool-batch context after all recorded results, then steering 'step/end' agent/turn-continuation agent/turn-stop (terminal policy) @@ -98,7 +99,7 @@ forever: Each step assembles ordered prompt sections, tool schemas, and `{{name}}` variables; unknown or valueless references fail the turn. `dsh-system-prompt` owns the harness identity and default persona, which an agent scope may shadow. The loop supplies `model` and `cwd` ([prompt-ownership RFC](rfc/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md)). -Post-tool context lands after all tool results so tool-call/result adjacency stays stable. Steering drains between steps; ordinary leftover steering after a turn is re-queued as input. A terminal `agent/turn-stop` is the explicit exception: it runs after ordinary continuation and steering folding, then remains authoritative through turn close and flush so steering from those later listeners is discarded rather than becoming another step or turn; ordinary queued prompts are preserved. +Context accepted during tool execution—including async `agent.inject()` notices and post-tool `additionalContexts`—waits for settlement, then follows every recorded result. Successful batches preserve call/result adjacency; interrupted batches drain that context before turn closure. Steering drains between steps; ordinary leftover steering becomes queued input. Terminal `agent/turn-stop` runs after continuation and steering folding, stays authoritative through turn close and flush, and discards later steering while preserving queued prompts. ### Failure Boundaries diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 3e3d8141fa..4cac932a6f 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -46,6 +46,8 @@ export interface Config { provider: string /** Model name for ACP-created agents (must have a registered adapter). */ model: string + /** Bundled agent-loop concurrency cap; `1` is serial and omission uses its default. */ + maxParallelToolCalls?: number /** Deployment persona (the system-prompt plugin's `persona` config). */ persona?: string /** Explicit model-facing tool order (the system-prompt plugin's `toolOrder` config; see dsh-system-prompt). */ @@ -76,8 +78,13 @@ Source: [`packages/examples/acp-demo/src/index.ts:32`](../packages/examples/acp- Requires: `agents` · `sessions` · `llm` · `tools` · `systemPrompt` ```ts config-catalog -/** Plugin configuration for declarative startup agents. */ +/** Agent-loop plugin configuration. */ export interface Config { + /** + * Maximum parallel-safe calls in flight per agent step. `1` is serial; + * omission defaults to {@link DEFAULT_MAX_PARALLEL_TOOL_CALLS}. + */ + maxParallelToolCalls?: number /** Agents created or resumed at plugin startup. */ agents: (AgentOptions & { /** Registry identity for the live agent. */ @@ -92,7 +99,7 @@ export interface Config { Depends on: [`AgentId`](../packages/core/agent/src/index.ts) · [`AgentOptions`](../packages/core/agent/src/index.ts) · [`SessionId`](../packages/core/session/src/index.ts) -Source: [`packages/core/agent-loop/src/index.ts:322`](../packages/core/agent-loop/src/index.ts) +Source: [`packages/core/agent-loop/src/index.ts:334`](../packages/core/agent-loop/src/index.ts) ## `@deepseek-ai/dsh-agent-spine-demo` @@ -115,6 +122,8 @@ Source: [`packages/core/agent-loop/src/index.ts:322`](../packages/core/agent-loo export interface Config { /** The agent-loop `agents` list (see dsh-agent-loop's `Config`). */ agents?: AgentLoopConfig['agents'] + /** Agent-loop concurrency cap; `1` is serial. */ + maxParallelToolCalls?: AgentLoopConfig['maxParallelToolCalls'] /** The deployment persona (see dsh-system-prompt's `Config`). */ persona?: SystemPromptConfig['persona'] /** The explicit model-facing tool order (see dsh-system-prompt's `Config`). */ @@ -783,6 +792,8 @@ export interface Config { provider: string /** Model name for the `main` agent (must have a registered adapter). */ model: string + /** Bundled agent-loop concurrency cap; `1` is serial and omission uses its default. */ + maxParallelToolCalls?: number /** Deployment persona (the system-prompt plugin's `persona` config). */ persona?: string /** Explicit model-facing tool order (the system-prompt plugin's `toolOrder` config; see dsh-system-prompt). */ @@ -1191,7 +1202,7 @@ export interface Config { export type ToolPresentationMode = 'native' | 'code' | 'both' ``` -Source: [`packages/core/tools/src/index.ts:322`](../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:382`](../packages/core/tools/src/index.ts) ## `@deepseek-ai/dsh-user-approval` diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index 9cf51c1de3..6fbffc1798 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -23,7 +23,7 @@ A fully configured agent and live session were published. Setup is composition-o Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:153`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:154`](../../packages/core/agent/src/types.ts) ### `agent/disposed` — emit @@ -35,7 +35,7 @@ An agent left the registry; AgentLoop emits this after driver quiescence but bef Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:162`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:163`](../../packages/core/agent/src/types.ts) ### `agent/error` — emit @@ -47,7 +47,7 @@ A step or turn errored. The loop reports a failure here (plus the logger) even w Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:297`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:298`](../../packages/core/agent/src/types.ts) ### `agent/pre-step` — serial @@ -59,7 +59,7 @@ Awaited serial checkpoint for session-surface mutation after prompt assembly and Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:216`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:217`](../../packages/core/agent/src/types.ts) ### `agent/prompt-submit` — waterfall @@ -71,7 +71,7 @@ Allow, rewrite, or block one drained prompt before it becomes a user message. Ca Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:226`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:227`](../../packages/core/agent/src/types.ts) ### `agent/queued` — emit @@ -83,7 +83,7 @@ Detached, frozen content entered the agent's inbox. Source defaults have already Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:181`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:182`](../../packages/core/agent/src/types.ts) ### `agent/request` — waterfall @@ -95,7 +95,7 @@ Replace the frozen call configuration. Model-visible content must use logged cha Types: [Agent](../core-data-structures/core.md) · [LlmCallConfig](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:238`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:239`](../../packages/core/agent/src/types.ts) ### `agent/session-prefix` — waterfall @@ -107,7 +107,7 @@ Compose request-only messages placed before derived history. The frozen result i Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:253`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:254`](../../packages/core/agent/src/types.ts) ### `agent/session-start` — emit @@ -119,7 +119,7 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to Types: [Agent](../core-data-structures/core.md) · [SessionStartSource](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:194`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:195`](../../packages/core/agent/src/types.ts) ### `agent/status` — emit @@ -131,7 +131,7 @@ Agent status changed (`idle` ⇄ `running`, or → `disposed`). `send()` does no Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:171`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:172`](../../packages/core/agent/src/types.ts) ### `agent/step-result` — waterfall @@ -143,7 +143,7 @@ Waterfall: post-process the assembled assistant Message before tool dispatch (va Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:264`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:265`](../../packages/core/agent/src/types.ts) ### `agent/turn-continuation` — waterfall @@ -155,7 +155,7 @@ Override whether the turn continues. The default continues after tool calls or s Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:274`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:275`](../../packages/core/agent/src/types.ts) ### `agent/turn-stop` — serial @@ -167,7 +167,7 @@ Monotonic terminal-stop checkpoint after continuation and steering are folded; a Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:284`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:285`](../../packages/core/agent/src/types.ts) ## `approval/*` diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index 30d47d70a2..b858cb6260 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -19,7 +19,7 @@ async createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise ``` -Source: [`packages/core/agent-loop/src/index.ts:335`](../../packages/core/agent-loop/src/index.ts) +Source: [`packages/core/agent-loop/src/index.ts:352`](../../packages/core/agent-loop/src/index.ts) ## `ctx.agents` — `AgentRegistry` @@ -319,12 +319,13 @@ restrict(filter: ToolRestriction): () => void guard(guard: ToolGuard): () => void get(name: string, scope?: ScopeKey): ToolDefinition | undefined schemas(scope?: ScopeKey): ToolSchema[] +executionMode(exec: ToolExecutionInput): ToolExecutionMode async execute(exec: ToolExecutionInput): Promise ``` -Types: [ToolDefinition](../core-data-structures/tools.md) · [ToolExecutionInput](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) +Types: [ToolDefinition](../core-data-structures/tools.md) · [ToolExecutionInput](../core-data-structures/tools.md) · [ToolExecutionMode](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) -Source: [`packages/core/tools/src/index.ts:378`](../../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:438`](../../packages/core/tools/src/index.ts) ## `ctx.userInteraction` — `UserInteractionService` diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md index 458de11457..c1ecdcc6a5 100644 --- a/docs/core-data-structures/core.md +++ b/docs/core-data-structures/core.md @@ -342,6 +342,11 @@ interface Agent { * `options.envelope: 'raw'` preserves caller-owned framing. Does not run the * model. * + * In an open turn, inject appends at the current log position except while + * the current tool-call batch executes: accepted context waits FIFO until the + * batch settles, then appends after every recorded result and before turn + * close even when execution is interrupted. + * * Turn-enclosure (the turn-enclosure RFC): an inject while a turn is open joins that turn; * an inject while idle wraps its `context/message` in a one-shot `injection` * turn (`turn/start` → `context/message` → `turn/end`) and checkpoints it for diff --git a/docs/core-data-structures/tools.md b/docs/core-data-structures/tools.md index f6c634377c..edb20586bc 100644 --- a/docs/core-data-structures/tools.md +++ b/docs/core-data-structures/tools.md @@ -6,7 +6,7 @@ Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index ## `ToolDefinition` — a registered tool -A `ToolSchema` (the model-facing fields) plus the `execute` function and optional UI presenters. The registry holds these; the loop dispatches calls through them. The registry's `schemas()` builds the model-facing `ToolSchema[]` by an explicit allowlist — `execute`/`presentCall`/`presentResult` must never leak into a model request. +A `ToolSchema` (the model-facing fields) plus the `execute` function, host-only scheduler metadata, and optional UI presenters. The registry holds these; the loop dispatches calls through them. The registry's `schemas()` builds the model-facing `ToolSchema[]` by an explicit allowlist — `execute`/`timeoutMs`/`isConcurrencySafe`/`presentCall`/`presentResult` must never leak into a model request. ```ts type-equiv interface ToolDefinition extends ToolSchema { @@ -19,6 +19,18 @@ interface ToolDefinition extends ToolSchema { * cooperative implementation that can reach quiescence when the signal aborts. */ timeoutMs?: number + /** + * Pure synchronous classifier for overlap with sibling tool calls. Only + * `true` opts in; omission, exceptions, non-`true` returns, and invalid + * `defineTool` arguments are exclusive. This metadata is never model-visible. + * + * Opted-in executions must not mutate parent-owned state. Shared state must + * tolerate concurrent dispatch; recorder races are permitted only when they + * commute or fail closed. See the parallel-tool-call RFC for the full contract. + * @param args - parsed arguments; `defineTool` validates before calling. + * @returns Whether this call may join a parallel group. + */ + isConcurrencySafe?(args: unknown): boolean /** * Optional: how to present the PENDING state of one call in a UI, derived from * the call's `args` (parsed arguments, `unknown` — the tool validates/narrows @@ -133,6 +145,14 @@ interface ToolRunContext extends ToolExecution { } ``` +The agent loop asks the registry for each pending call's execution mode and uses it to form exclusive barriers and rolling-pool parallel runs: + +```ts type-equiv +type ToolExecutionMode = + | { kind: 'parallel' } + | { kind: 'exclusive' } +``` + ```ts type-equiv interface ToolExecution extends ToolExecutionInput { /** Registry-assigned identity shared with nested calls only as their opaque `parent` token. */ @@ -160,11 +180,13 @@ interface ToolExecutionResult { error?: ToolErrorInfo /** * Extra model-facing contexts deferred by a composite tool or attached by - * `tools/post-execute` listeners for the NEXT request. They are NOT part of - * this call's `content`: the loop buffers every context and appends them only - * AFTER all `tool/result`s for the step, preserving tool-call/result - * adjacency. The array preserves each context's source, envelope, metadata, - * and production order instead of flattening mixed plugin provenance. + * `tools/post-execute` listeners for the NEXT request. They are not part of + * this call's `content`: the loop accepts them into the active-batch FIFO and + * appends them after every recorded `tool/result` when the batch settles, even + * when execution is interrupted. The array preserves each context's source, + * envelope, metadata, and production order. An accepted outer call keeps + * deferred contexts before decision contexts; a block retains only contexts + * supplied by the blocking decision. */ additionalContexts?: HookContext[] /** diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index d49cbf0f35..acd90d4423 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -7,19 +7,19 @@ This matrix shows which packages dispatch each harness-owned event and which pac | Event | Mode | Declared in | Dispatchers | Listeners | | --- | --- | --- | --- | --- | -| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:153`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`jsonrpc`](../packages/ui/jsonrpc), [`stdio`](../packages/ui/stdio) | -| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:162`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`stdio`](../packages/ui/stdio) | -| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:297`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | -| `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:216`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic), [`time-context`](../packages/context/time-context), [`user-approval`](../packages/ui/user-approval) | -| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:226`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`acp`](../packages/ui/acp), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | -| `agent/queued` | `emit` | [`packages/core/agent/src/types.ts:181`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | -| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:238`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`acp`](../packages/ui/acp) | -| `agent/session-prefix` | `waterfall` | [`packages/core/agent/src/types.ts:253`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`tool-skill`](../packages/skill/tool-skill), [`workspace-context`](../packages/context/workspace-context) | -| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:194`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | -| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:171`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`invariants`](../packages/support/invariants), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`stdio`](../packages/ui/stdio) | -| `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:264`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | -| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:274`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | -| `agent/turn-stop` | `serial` | [`packages/core/agent/src/types.ts:284`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | +| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:154`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`jsonrpc`](../packages/ui/jsonrpc), [`stdio`](../packages/ui/stdio) | +| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:163`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`stdio`](../packages/ui/stdio) | +| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:298`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | +| `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:217`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic), [`time-context`](../packages/context/time-context), [`user-approval`](../packages/ui/user-approval) | +| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:227`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`acp`](../packages/ui/acp), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | +| `agent/queued` | `emit` | [`packages/core/agent/src/types.ts:182`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | +| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:239`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`acp`](../packages/ui/acp) | +| `agent/session-prefix` | `waterfall` | [`packages/core/agent/src/types.ts:254`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`tool-skill`](../packages/skill/tool-skill), [`workspace-context`](../packages/context/workspace-context) | +| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:195`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | +| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:172`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`invariants`](../packages/support/invariants), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`stdio`](../packages/ui/stdio) | +| `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:265`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | +| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:275`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | +| `agent/turn-stop` | `serial` | [`packages/core/agent/src/types.ts:285`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | | `approval/request` | `waterfall` | [`packages/ui/user-approval/src/index.ts:31`](../packages/ui/user-approval/src/index.ts) | [`user-approval`](../packages/ui/user-approval) (`waterfall`) | [`acp`](../packages/ui/acp) | | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:61`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) | | `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:70`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`) | [`fs-policy`](../packages/fs/fs-policy) | diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md index 5484d0efe2..3bc15253a5 100644 --- a/docs/persistence-catalog.md +++ b/docs/persistence-catalog.md @@ -1,13 +1,85 @@ -# Persistence Log Event Catalog +# Session Persistence Event Catalog -Every event type that can appear in a session's durable event log: each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with the payload it carries, its surface badge, and the declaration it comes from. It complements [session.md](core-data-structures/session.md) (the `SessionEvent` envelope, surface list, and `deriveMessages()` projection), [persistence.md](core-data-structures/persistence.md) (how the log is made durable), and the [cordis events catalog](cordis-catalog/events.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit). +Every event type that can appear in a session's durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](core-data-structures/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](core-data-structures/persistence.md) (how the log is made durable), and the [cordis events catalog](cordis-catalog/events.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit). -This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Payload blocks use a `ts persistence-catalog` fence (skipped by doc-typecheck, since a bare payload fragment is not standalone-compilable). Type names in a payload link to the page that documents them. See [the persistence-log-catalog RFC](rfc/implemented/process/2026-07-04-persistence-log-catalog.md). +This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks retain the source declaration and nested property JSDoc, removing only the indentation imposed by a containing interface/module, and use a `ts persistence-catalog` fence (skipped by doc-typecheck because declarations reference types from their owning modules). Type names in a payload link to the page that documents them. See [the persistence-log-catalog RFC](rfc/implemented/process/2026-07-04-persistence-log-catalog.md). -The on-disk envelope around every payload is `SessionEvent` — `type`, monotonic `seq`, epoch-ms `time`, the `data` documented here, plus `surfaceOp`/`sourceEventSeqs` on **surface** events only ([envelope](core-data-structures/session.md#sessioneventt--one-log-entry)). **surface** marks a `SurfaceEventType` member: it produces an LLM message and declares how it joins the surface list. **log-only** marks everything else: durable, replayable record with no derived-history contribution. Every payload is JSON-serializable (enforced at `Session.append`), and the whole format is pinned at `SESSION_FORMAT_VERSION = 0` — pre-release, no compatibility implied ([the version stance](core-data-structures/persistence.md)). Scope: the packages in this repo; a downstream plugin can merge further event types, which are outside this catalog by construction. +The envelope declarations below compose each event's `type`, monotonic `seq`, epoch-ms `time`, `data`, and the conditional `surfaceOp`/`sourceEventSeqs` fields. **surface** marks a `SurfaceEventType` member: it produces an LLM message and declares how it joins the surface list. **log-only** marks everything else: a durable, replayable record with no derived-history contribution. Every payload is JSON-serializable (enforced at `Session.append`), and the whole format is pinned at `SESSION_FORMAT_VERSION = 0` — pre-release, no compatibility implied ([the version stance](core-data-structures/persistence.md)). Scope: the packages in this repo; a downstream plugin can merge further event types, which are outside this catalog by construction. + +## Event envelope + +```ts persistence-catalog +/** The appendable event-type keys of {@link SessionEventMap}, plugin-merged extensions included. */ +export type SessionEventType = keyof SessionEventMap + +/** + * The subset of {@link SessionEventType} values whose events produce LLM + * messages and are eligible to appear on the ordered surface. Only these + * event types may carry {@link SurfaceOp} and {@link SessionEvent.sourceEventSeqs}. + */ +export type SurfaceEventType = + | 'user/message' + | 'assistant/message' + | 'tool/result' + | 'context/message' + | 'steering/message' + +/** + * How a session event entered the ordered surface. Only valid on + * {@link SurfaceEventType} events. + * + * - `'append'`: added to the tail — normal path for user/assistant/tool/context + * messages. + * - `{ op: 'replace', start, end }`: replaces surface nodes from `start` + * (inclusive) through `end` (inclusive) with this node. Both must exist as + * surface nodes in the current surface. `start === end` replaces a single + * node. The node's {@link SessionEvent.sourceEventSeqs} must include every + * shadowed surface node. Used by compaction and possible other manipulations. + */ +export type SurfaceOp = + | 'append' + | { op: 'replace'; start: number; end: number } + +/** + * One immutable entry in the session log. + * + * A proper discriminated union over `type` (not independent `type`/`data` + * unions), so `switch (event.type)` narrows `event.data` without casts. + * + * The {@link sourceEventSeqs} and {@link surfaceOp} fields are conditional: + * they only exist on {@link SurfaceEventType} variants (`user/message`, + * `assistant/message`, `tool/result`, `context/message`, `steering/message`). + * Non-surface events (boundary markers, chunks, usage, errors) never carry + * surface metadata — the compiler enforces this at `Session.append()` + * call sites. + */ +export type SessionEvent = { + [K in SessionEventType]: { + type: K + /** Monotonic sequence number within the session. */ + seq: number + /** Unix epoch milliseconds. */ + time: number + data: SessionEventMap[K] + } & (K extends SurfaceEventType ? { + /** + * Seq numbers of events that are provenance sources of this event + * (e.g. the `assistant/chunk` seqs that built an `assistant/message`, + * or the surface nodes shadowed by a compaction replace node). An + * `assistant/message` may carry a present empty array for a known empty + * provider stream; omission means unrecorded provenance. + */ + sourceEventSeqs?: number[] + /** How this event entered the surface; absent for non-surface events. */ + surfaceOp?: SurfaceOp + } : object) +}[T] +``` + +Sources: [`packages/core/session/src/types.ts:255`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:262`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:292`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:324`](../packages/core/session/src/types.ts) ## Events @@ -15,10 +87,21 @@ The on-disk envelope around every payload is `SessionEvent` — `type`, monotoni #### `approval/asked` — log-only -An approval question was put to the answerer chain — log-only audit (like `hook/*`; NOT a surface event, carries no `surfaceOp`). `id` pairs it with the `approval/decided` that always follows; `toolName` is the tool the question is about, `callId` the exact tool call when the asker had one, `reason` the asker's human-readable explanation (e.g. a hook's permission-decision reason). - ```ts persistence-catalog -'approval/asked': { id: ApprovalRequestId; toolName: string; callId?: CallId; reason?: string } +/** + * An approval question was put to the answerer chain — log-only audit + * (like `hook/*`; NOT a surface event, carries no `surfaceOp`). `id` pairs + * it with the `approval/decided` that always follows; `toolName` is the + * tool the question is about, `callId` the exact tool call when the asker + * had one, `reason` the asker's human-readable explanation (e.g. a hook's + * permission-decision reason). + */ +'approval/asked': { + id: ApprovalRequestId + toolName: string + callId?: CallId + reason?: string +} ``` Types: [CallId](core-data-structures/core.md) @@ -27,19 +110,31 @@ Source: [`packages/ui/user-approval/src/index.ts:45`](../packages/ui/user-approv #### `approval/decided` — log-only -The outcome of a prior `approval/asked` (same `id`) — log-only audit. Exactly one per ask, appended when the outcome is known: a decision, a cancellation, or the fail-closed `'unavailable'`. - ```ts persistence-catalog -'approval/decided': { id: ApprovalRequestId; outcome: ApprovalOutcome } +/** + * The outcome of a prior `approval/asked` (same `id`) — log-only audit. + * Exactly one per ask, appended when the outcome is known: a decision, a + * cancellation, or the fail-closed `'unavailable'`. + */ +'approval/decided': { + id: ApprovalRequestId + outcome: ApprovalOutcome +} ``` Source: [`packages/ui/user-approval/src/index.ts:56`](../packages/ui/user-approval/src/index.ts) #### `approval/policy` — log-only -The session's approval policy was switched — log-only, durable, replayable, never in the model transcript (the model learns the policy from the prompt section and the narrator's notices). The LAST such event is the session's override (effectiveApprovalPolicy); who asked for it is derivable from position (an event after the log's last `request/header` was a runtime switch by the user). - ```ts persistence-catalog +/** + * The session's approval policy was switched — log-only, durable, + * replayable, never in the model transcript (the model learns the policy + * from the prompt section and the narrator's notices). The LAST such + * event is the session's override ({@link effectiveApprovalPolicy}); + * who asked for it is derivable from position (an event after the log's + * last `request/header` was a runtime switch by the user). + */ 'approval/policy': { policy: ApprovalPolicy } ``` @@ -49,9 +144,8 @@ Source: [`packages/ui/user-approval/src/index.ts:68`](../packages/ui/user-approv #### `assistant/chunk` — log-only -Raw stream chunk — token-level replay fidelity. - ```ts persistence-catalog +/** Raw stream chunk — token-level replay fidelity. */ 'assistant/chunk': { turn: number; step: number; chunk: StreamChunk } ``` @@ -61,9 +155,13 @@ Source: [`packages/core/session/src/types.ts:219`](../packages/core/session/src/ #### `assistant/message` — surface -Assembled assistant message for one step (derived history uses this). Carries the step's `usage` when the adapter reported token accounting, so the model output and its accounting travel together (there is no separate usage record). `usage` is absent when the adapter reported none. - ```ts persistence-catalog +/** + * Assembled assistant message for one step (derived history uses this). + * Carries the step's `usage` when the adapter reported token accounting, so + * the model output and its accounting travel together (there is no separate + * usage record). `usage` is absent when the adapter reported none. + */ 'assistant/message': { turn: number; step: number; content: ContentBlock[]; provenance: AssistantProvenance; usage?: TokenUsage } ``` @@ -75,9 +173,12 @@ Source: [`packages/core/session/src/types.ts:226`](../packages/core/session/src/ #### `bash/sandbox-mode` — log-only -Durable log-only sandbox-mode override; never a surface event or model message. Execution and ACP option reporting fold the latest event through effectiveSandboxMode without adding a prompt notice. - ```ts persistence-catalog +/** + * Durable log-only sandbox-mode override; never a surface event or model + * message. Execution and ACP option reporting fold the latest event through + * {@link effectiveSandboxMode} without adding a prompt notice. + */ 'bash/sandbox-mode': { mode: SandboxMode } ``` @@ -87,9 +188,8 @@ Source: [`packages/bash/bash/src/session-mode.ts:20`](../packages/bash/bash/src/ #### `compact/end` — log-only -Marks the end of a compaction — log-only, releases the lock. `error` set if summarization failed. - ```ts persistence-catalog +/** Marks the end of a compaction — log-only, releases the lock. `error` set if summarization failed. */ 'compact/end': { turn: number; error?: string } ``` @@ -97,9 +197,8 @@ Source: [`packages/compact/compact/src/types.ts:40`](../packages/compact/compact #### `compact/start` — log-only -Marks the start of a compaction — log-only, holds the lock until `compact/end`. - ```ts persistence-catalog +/** Marks the start of a compaction — log-only, holds the lock until `compact/end`. */ 'compact/start': { turn: number } ``` @@ -107,10 +206,30 @@ Source: [`packages/compact/compact/src/types.ts:15`](../packages/compact/compact #### `compact/summary` — log-only -Provenance record of a completed summarization — log-only, no surfaceOp. The summary content is in `data.summary`; the actual surface replacement is performed by a subsequent `user/message` event that shadows the compacted range. - ```ts persistence-catalog -'compact/summary': { summary: ContentBlock[]; shadowedRange: { start: number; end: number }; shadowedSeqs: number[]; shadowedTokenCount: number; provider: string; model: string; maxTokens?: number } +/** + * Provenance record of a completed summarization — log-only, no surfaceOp. + * The summary content is in `data.summary`; the actual surface replacement + * is performed by a subsequent `user/message` event that shadows the + * compacted range. + */ +'compact/summary': { + summary: ContentBlock[] + shadowedRange: { start: number; end: number } + shadowedSeqs: number[] + shadowedTokenCount: number + /** The provider route that wrote the summary. */ + provider: string + /** + * The model that wrote the summary — the summarize call's envelope, + * reported by the backend that made the call, logged so the one-shot + * request is reconstructable from log + code and "which model wrote + * this summary" has a durable answer (the reconstructability RFC). + */ + model: string + /** The generation cap the summarize call sent, when one applied. */ + maxTokens?: number +} ``` Types: [ContentBlock](core-data-structures/core.md) @@ -121,10 +240,20 @@ Source: [`packages/compact/compact/src/types.ts:22`](../packages/compact/compact #### `context/message` — surface -In-session context injection (file-change notices, subdir AGENTS.md, skill content, cron notifications, …). Rendered into the derived history as synthetic context — NOT a user prompt. `envelope: 'raw'` lets a caller own the complete model-facing frame; `meta` is durable JSON state omitted from the model projection. - ```ts persistence-catalog -'context/message': { content: ContentBlock[]; source: MessageSource; envelope?: ContextEnvelope; meta?: JsonValue } +/** + * In-session context injection (file-change notices, subdir AGENTS.md, + * skill content, cron notifications, …). Rendered into the derived history + * as synthetic context — NOT a user prompt. `envelope: 'raw'` lets a caller + * own the complete model-facing frame; `meta` is durable JSON state omitted + * from the model projection. + */ +'context/message': { + content: ContentBlock[] + source: MessageSource + envelope?: ContextEnvelope + meta?: JsonValue +} ``` Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md) @@ -135,20 +264,44 @@ Source: [`packages/core/session/src/types.ts:212`](../packages/core/session/src/ #### `hook/invoked` — log-only -A hook command was invoked at a hook point — log-only provenance (like `compact/*`; NOT a SurfaceEventType, carries no `surfaceOp`). `dialect` is the bridge that ran it (`claude`/`codex`), `point` the hook point (`PreToolUse`, `Stop`, …), `matcher` the matcher-group pattern that selected it (absent for match-all), `handlerId` a stable id for the command (so an invoked/result pair correlates). `turn` is the open turn the invocation lives inside. - ```ts persistence-catalog -'hook/invoked': { turn: number; point: string; dialect: HookDialect; matcher?: string; handlerId: string } +/** + * A hook command was invoked at a hook point — log-only provenance (like + * `compact/*`; NOT a {@link SurfaceEventType}, carries no `surfaceOp`). + * `dialect` is the bridge that ran it (`claude`/`codex`), `point` + * the hook point (`PreToolUse`, `Stop`, …), `matcher` the matcher-group + * pattern that selected it (absent for match-all), `handlerId` a stable id + * for the command (so an invoked/result pair correlates). `turn` is the open + * turn the invocation lives inside. + */ +'hook/invoked': { + turn: number + point: string + dialect: HookDialect + matcher?: string + handlerId: string +} ``` Source: [`packages/hooks/hook-protocol/src/types.ts:19`](../packages/hooks/hook-protocol/src/types.ts) #### `hook/result` — log-only -Log-only outcome paired to `hook/invoked` by `handlerId`. Decision is the parsed permission result, `stop` for `continue:false`, or `pass`; exit code may be absent, stderr is bounded, and duration is wall-clock runtime. - ```ts persistence-catalog -'hook/result': { turn: number; point: string; handlerId: string; decision: string; exitCode?: number; stderrSummary?: string; durationMs: number } +/** + * Log-only outcome paired to `hook/invoked` by `handlerId`. Decision is the + * parsed permission result, `stop` for `continue:false`, or `pass`; exit code + * may be absent, stderr is bounded, and duration is wall-clock runtime. + */ +'hook/result': { + turn: number + point: string + handlerId: string + decision: string + exitCode?: number + stderrSummary?: string + durationMs: number +} ``` Source: [`packages/hooks/hook-protocol/src/types.ts:31`](../packages/hooks/hook-protocol/src/types.ts) @@ -157,9 +310,13 @@ Source: [`packages/hooks/hook-protocol/src/types.ts:31`](../packages/hooks/hook- #### `permission/preset` — log-only -Records the selected preset as durable, log-only user intent. The knob events follow in the same turn and control execution; this event stays out of the model transcript and lets effectivePermissionPreset preserve a selection when bundles match. - ```ts persistence-catalog +/** + * Records the selected preset as durable, log-only user intent. The knob + * events follow in the same turn and control execution; this event stays + * out of the model transcript and lets {@link effectivePermissionPreset} + * preserve a selection when bundles match. + */ 'permission/preset': { preset: string } ``` @@ -169,9 +326,11 @@ Source: [`packages/ui/permission/src/index.ts:33`](../packages/ui/permission/src #### `prompt/blocked` — log-only -Durable record of a prompt veto and its reason. It is log-only: the blocked prompt never enters the model-visible surface, including in a mixed batch. - ```ts persistence-catalog +/** + * Durable record of a prompt veto and its reason. It is log-only: the blocked + * prompt never enters the model-visible surface, including in a mixed batch. + */ 'prompt/blocked': { content: ContentBlock[]; source: MessageSource; reason: string } ``` @@ -183,9 +342,11 @@ Source: [`packages/core/session/src/types.ts:204`](../packages/core/session/src/ #### `request/header` — log-only -Full header for the next request, appended inside its step before dispatch. It is log-only; the latest snapshot reconstructs the request header. - ```ts persistence-catalog +/** + * Full header for the next request, appended inside its step before dispatch. + * It is log-only; the latest snapshot reconstructs the request header. + */ 'request/header': { header: EpochHeader; reason: RequestHeaderReason } ``` @@ -195,9 +356,8 @@ Source: [`packages/core/session/src/types.ts:251`](../packages/core/session/src/ #### `steering/message` — surface -Steering content injected between steps of a running turn. - ```ts persistence-catalog +/** Steering content injected between steps of a running turn. */ 'steering/message': { turn: number; content: ContentBlock[]; source: MessageSource } ``` @@ -209,9 +369,8 @@ Source: [`packages/core/session/src/types.ts:244`](../packages/core/session/src/ #### `step/end` — log-only -Closes step `step` of turn `turn`. - ```ts persistence-catalog +/** Closes step `step` of turn `turn`. */ 'step/end': { turn: number; step: number } ``` @@ -219,9 +378,8 @@ Source: [`packages/core/session/src/types.ts:197`](../packages/core/session/src/ #### `step/start` — log-only -Opens step `step` of turn `turn` — one model call plus the tool executions it requested. - ```ts persistence-catalog +/** Opens step `step` of turn `turn` — one model call plus the tool executions it requested. */ 'step/start': { turn: number; step: number } ``` @@ -231,9 +389,8 @@ Source: [`packages/core/session/src/types.ts:195`](../packages/core/session/src/ #### `todo/write` — log-only -Whole-list snapshot; latest write wins on replay. Log-only UI state; never derived history. - ```ts persistence-catalog +/** Whole-list snapshot; latest write wins on replay. Log-only UI state; never derived history. */ 'todo/write': { todos: TodoItem[] } ``` @@ -245,9 +402,12 @@ Source: [`packages/core/session/src/types.ts:246`](../packages/core/session/src/ #### `tool/call` — log-only -The model requested one tool invocation: `name` with the raw `arguments` JSON string exactly as the model produced it (unparsed). `callId` pairs the call with its `tool/result`. - ```ts persistence-catalog +/** + * The model requested one tool invocation: `name` with the raw `arguments` + * JSON string exactly as the model produced it (unparsed). `callId` pairs the + * call with its `tool/result`. + */ 'tool/call': { turn: number; step: number; callId: CallId; name: string; arguments: string } ``` @@ -257,9 +417,22 @@ Source: [`packages/core/session/src/types.ts:232`](../packages/core/session/src/ #### `tool/code-dispatch` — log-only -One bridged sub-dispatch from a `run_code` program: the parent `run_code` call id, the deterministic sub-call id (`:code:`), the tool `name` with its JSON-normalized `arguments` — the exact value dispatched, normalized BEFORE dispatch, so this append can never fail on payload shape — whether the sub-call errored, and a bounded `resultSummary` of its model-facing text. Before bounding, occurrences of a non-root session workspace path are normalized to `.` so host-specific absolute path lengths cannot change the summary. Log-only: `deriveMessages()` ignores it, so sub-calls never re-enter model context; persistence and UIs get every call. Appended inside the parent `run_code`'s execution (the bridge drains its queue before returning), so the turn-enclosure invariant holds by construction. - ```ts persistence-catalog +/** + * One bridged sub-dispatch from a `run_code` program: the parent + * `run_code` call id, the deterministic sub-call id + * (`:code:`), the tool `name` with its JSON-normalized + * `arguments` — the exact value dispatched, normalized BEFORE dispatch, + * so this append can never fail on payload shape — whether the sub-call + * errored, and a bounded `resultSummary` of its model-facing text. Before + * bounding, occurrences of a non-root session workspace path are + * normalized to `.` so host-specific absolute path lengths cannot change + * the summary. + * Log-only: `deriveMessages()` ignores it, so sub-calls never re-enter + * model context; persistence and UIs get every call. Appended inside the + * parent `run_code`'s execution (the bridge drains its queue before + * returning), so the turn-enclosure invariant holds by construction. + */ 'tool/code-dispatch': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown; isError: boolean; resultSummary: string } ``` @@ -269,9 +442,16 @@ Source: [`packages/core/tools/src/code-mode.ts:34`](../packages/core/tools/src/c #### `tool/result` — surface -A completed tool call's model-facing result, plus an optional tool-private `meta` presentation payload. `meta` is opaque to the core (`unknown` — the producing tool owns its shape and reads it back in `presentResult`) but MUST be JSON-serializable: `Session.append` runtime-validates all event data with `isJsonValue`, so a non-serializable `meta` is rejected at the source, and the durable log reproduces the identical card on replay. Absent unless the tool attaches one (e.g. `dsh-tool-fs` carries its result-time contextual diff here). - ```ts persistence-catalog +/** + * A completed tool call's model-facing result, plus an optional tool-private + * `meta` presentation payload. `meta` is opaque to the core (`unknown` — the + * producing tool owns its shape and reads it back in `presentResult`) but MUST + * be JSON-serializable: `Session.append` runtime-validates all event data with + * `isJsonValue`, so a non-serializable `meta` is rejected at the source, and the + * durable log reproduces the identical card on replay. Absent unless the tool + * attaches one (e.g. `dsh-tool-fs` carries its result-time contextual diff here). + */ 'tool/result': { turn: number; step: number; callId: CallId; content: ContentBlock[]; isError: boolean; error?: { name: string; code: string }; meta?: unknown } ``` @@ -283,9 +463,12 @@ Source: [`packages/core/session/src/types.ts:242`](../packages/core/session/src/ #### `turn/end` — log-only -Closes turn `turn` with the TurnEndReason that ended it. The loop fires the awaited `session/flush` checkpoint at every turn end, so the turn boundary is also the durable-commit boundary. - ```ts persistence-catalog +/** + * Closes turn `turn` with the {@link TurnEndReason} that ended it. The loop + * fires the awaited `session/flush` checkpoint at every turn end, so the turn + * boundary is also the durable-commit boundary. + */ 'turn/end': { turn: number; reason: TurnEndReason } ``` @@ -295,9 +478,13 @@ Source: [`packages/core/session/src/types.ts:193`](../packages/core/session/src/ #### `turn/start` — log-only -Opens turn `turn`. `trigger` records what started it — a drained message batch or an idle-time injection. The turn is the durability/replay boundary: every event sits between a `turn/start` and its matching `turn/end` (the turn-enclosure invariant). - ```ts persistence-catalog +/** + * Opens turn `turn`. `trigger` records what started it — a drained message + * batch or an idle-time injection. The turn is the durability/replay + * boundary: every event sits between a `turn/start` and its matching + * `turn/end` (the turn-enclosure invariant). + */ 'turn/start': { turn: number; trigger: TurnTrigger } ``` @@ -309,9 +496,8 @@ Source: [`packages/core/session/src/types.ts:187`](../packages/core/session/src/ #### `user/message` — surface -A user-visible prompt (queued message drained at turn start). - ```ts persistence-catalog +/** A user-visible prompt (queued message drained at turn start). */ 'user/message': { content: ContentBlock[]; source: MessageSource } ``` diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md index 91e67e8730..ecb66326b3 100644 --- a/docs/rfc/INDEX.md +++ b/docs/rfc/INDEX.md @@ -81,6 +81,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; | [The self-referential cordis toolset](implemented/feature/2026-07-08-self-referential-cordis-toolset.md) | 2026-07-08 | | [Bash-backed grep and glob discovery tools](implemented/feature/2026-07-09-bash-backed-grep-glob-discovery.md) | 2026-07-09 | | [Expose agent session identity and JSONL location to tools and hooks](implemented/feature/2026-07-10-agent-session-identity-and-log-location.md) | 2026-07-10 | +| [Parallel tool-call execution by per-call safety](implemented/feature/2026-07-10-parallel-tool-call-execution.md) | 2026-07-10 | | [Exact session query service](implemented/feature/2026-07-10-session-query-service.md) | 2026-07-10 | | [Configure subagent persona, tool visibility, and depth](implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md) | 2026-07-12 | | [Session query relationship tracing](implemented/feature/2026-07-13-session-query-tracing.md) | 2026-07-13 | @@ -191,6 +192,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; | [A gated Known-Limitations section in every package README](implemented/process/2026-07-10-readme-known-limitations-gate.md) | 2026-07-10 | | [Package Model Experience contract](implemented/process/2026-07-12-package-model-experience-contract.md) | 2026-07-12 | | [TypeScript Program-backed semantic gates](implemented/process/2026-07-14-typescript-program-backed-semantic-gates.md) | 2026-07-14 | +| [Run CI examples from built lib](implemented/process/2026-07-17-run-ci-examples-from-built-lib.md) | 2026-07-17 | ### Testing diff --git a/docs/rfc/implemented/architecture/2026-06-15-turn-enclosure-invariant.md b/docs/rfc/implemented/architecture/2026-06-15-turn-enclosure-invariant.md index e55cd0853e..a54f735219 100644 --- a/docs/rfc/implemented/architecture/2026-06-15-turn-enclosure-invariant.md +++ b/docs/rfc/implemented/architecture/2026-06-15-turn-enclosure-invariant.md @@ -18,7 +18,7 @@ In case 2, if the injected `context/message` is the last event before a flush/di **Every session event lives inside a turn** — between a `turn/start` and its matching `turn/end`. Concretely: - The loop appends queued `user/message` events **after** `turn/start` (inside the turn), not before it. `turn/end` is therefore owed the moment those messages are recorded, and the existing finalizer guarantees it. -- An `agent.inject()` made while the agent is **running** appends its `context/message` into the already-open turn (unchanged). +- An `agent.inject()` made while the agent is **running** joins the already-open turn. While the current step executes assistant tool calls, accepted context waits in arrival order until that batch settles, then appends after every recorded result and before the turn closes even when execution is interrupted. - An `agent.inject()` made while **idle** wraps its `context/message` in a one-shot turn: `turn/start{trigger:{kind:'injection'}}` → `context/message` → `turn/end{completed}`. A new `injection` variant joins the merge-extensible `TurnTriggerMap`. - The loop derives the next turn number from the log each iteration (`lastTurnNumber(session) + 1`) instead of keeping a private counter, so an idle injection's one-shot turn cannot collide with the next real turn's number. - The `dsh-invariants` plugin **enforces** the invariant in dev: a `user/message` / `context/message` / `steering/message` appended while no turn is open throws an `InvariantError`. diff --git a/docs/rfc/implemented/feature/2026-06-30-interception-seams.md b/docs/rfc/implemented/feature/2026-06-30-interception-seams.md index 8a2af04494..1356afa06b 100644 --- a/docs/rfc/implemented/feature/2026-06-30-interception-seams.md +++ b/docs/rfc/implemented/feature/2026-06-30-interception-seams.md @@ -36,7 +36,7 @@ Core dispatch and the tool body sit inside normalization boundaries, so tool, li 1. **Open the turn before prompt policy.** A fully blocked batch becomes a zero-step `rejected` turn, preserving enclosure and giving ACP a durable terminal event. Every veto also records `prompt/blocked` with the original prompt and reason, so mixed batches retain blocked inputs. Every allowed `additionalContexts` entry is injected into the open turn. -2. **Post-tool `additionalContexts` are buffered and appended AFTER all `tool/result`s.** `content`/`feedback` shape the result `execute()` returns, but each context is a SEPARATE `context/message`, and a single step or composite tool can produce many. Appending context immediately would interleave `result(c1) → context → result(c2)` or place nested context before its outer result, breaking tool-call/result adjacency. `ToolRunContext.deferContext()` therefore collects nested-dispatch context through failures, `execute()` surfaces the ordered array on `ToolExecutionResult`, and the loop appends every entry only after every `tool/result` in the step. An accepted outer call preserves deferred contexts before decision contexts; an outer block discards deferred contexts and exposes only contexts explicitly supplied by the blocking decision. +2. **Post-tool `additionalContexts` and asynchronous injections enter the active-batch FIFO and append when that batch settles.** `content`/`feedback` shape the result `execute()` returns, but each context is a separate `context/message`, and a single step or composite tool can produce many. Appending context immediately would interleave `result(c1) → context → result(c2)` or place nested context before its outer result, breaking tool-call/result adjacency. `ToolRunContext.deferContext()` therefore collects nested-dispatch context through failures, `execute()` surfaces the ordered array on `ToolExecutionResult`, and the loop accepts it into the same FIFO as `agent.inject()` calls made during execution. The FIFO appends after every recorded result when the batch settles, including before an interrupted turn closes. An accepted outer call preserves deferred contexts before decision contexts; an outer block discards deferred contexts and exposes only contexts explicitly supplied by the blocking decision. 3. **A forced `continue` `reason` is enqueued through the steering channel**, so the next step's top-of-loop drain records it as steering for the continued turn — next-*step* steering within the SAME turn, not a next-*turn* prompt (matching the existing `hasSteering` force-continue override). diff --git a/docs/rfc/implemented/feature/2026-07-10-parallel-tool-call-execution.md b/docs/rfc/implemented/feature/2026-07-10-parallel-tool-call-execution.md new file mode 100644 index 0000000000..90fbc1cfb4 --- /dev/null +++ b/docs/rfc/implemented/feature/2026-07-10-parallel-tool-call-execution.md @@ -0,0 +1,101 @@ +# RFC: Parallel tool-call execution by per-call safety + +Status: implemented + +## Problem + +An assistant message may contain several sibling `tool-call` blocks. Running them serially adds the latency of independent reads and web requests even though the model has already requested them together. + +Concurrency is a host scheduling concern, not model-facing tool metadata. The loop needs to decide which calls may overlap without hardcoding tool names or exposing scheduler policy in the JSON schema. + +The session log remains authoritative: every started call has an audit event, every started call receives a result, and model history observes results in the original call order regardless of completion order. + +## Decision + +Each tool may provide an optional `isConcurrencySafe(args)` classifier. It is synchronous and pure: it examines only the current call's parsed arguments and performs no I/O or mutation. Only an explicit `true` opts in; a missing classifier, invalid arguments, a thrown classifier, or any other return value makes the call exclusive. The canonical type contract lives in the [tool data structures](../../../core-data-structures/tools.md). + +The classifier is deliberately unary. Returning `true` is the tool's promise that this call may overlap with any sibling call that also returns `true`; the scheduler does not compare calls or prove that their resource accesses are compatible. + +The unary classifier remains input-sensitive. A tool may classify a read-only operation as parallel and a mutating operation as exclusive. The interface cannot express relational rules such as "these writes are safe only when their paths differ," so a call whose safety depends on a sibling remains exclusive. + +`defineTool()` validates arguments before invoking a typed classifier. Invalid arguments classify as exclusive and produce the ordinary argument error only if the call executes. `ctx.tools.executionMode(exec)` resolves the live tool definition and returns the tagged `parallel` or `exclusive` mode; unknown tools fail closed to exclusive. + +A tagged mode, rather than a public boolean scheduler API, keeps resource-aware variants representable without changing the classifier contract. + +## Scheduling and ordering + +The loop waits for the complete assistant message, parses every call once, creates a distinct `ToolExecution` for each call, and scans them in model order. Consecutive parallel calls form one group; every exclusive call forms a singleton group and an ordering barrier. Groups execute sequentially. Classification is lazy: the scheduler resolves the next call after each barrier and reclassifies every later call before replenishing a parallel pool. If a registry mutation makes that call exclusive, the current pool drains before the call starts as the next barrier. + +For example: + +```text +[parallel read(A), parallel read(B), exclusive write(A), parallel read(C)] + +→ [read(A), read(B)] +→ [write(A)] +→ [read(C)] +``` + +`read(A)` and `read(B)` may overlap. `write(A)` starts after both finish, and `read(C)` starts after the write finishes. + +Every group uses a rolling pool bounded by `maxParallelToolCalls`: the loop starts calls in model order up to the cap and starts another whenever one settles. An exclusive group is a pool of one. A cap of `1` preserves serial execution. + +Only dispatch and the tool body overlap. `tools/pre-execute` and `tools/post-execute` run in model order because middleware may maintain ordering-sensitive state. `tools/execute` wrappers run around concurrent dispatches and therefore must be reentrant across distinct executions. + +Each started call appends `tool/call` immediately before its pre-execute gate. Completed dispatches occupy model-order slots, and a commit cursor appends `tool/result` and collects `additionalContexts` only when the next slot is ready. Live surfaces may show several pending calls, but results and post-tool context remain model-ordered. + +An abort before a group starts records no calls from that group. An abort during a group stops replenishment, waits for already-started calls, commits their results in order, drains accepted batch context after those results, and then ends the step through the existing abort path. Calls that never start have no audit event. + +Code Mode remains outside this scheduler because the model emits one native `run_code` call. `run_code` and its internal dispatch queue remain serial; native sibling calls in `mode: 'both'` use the normal scheduler. + +## Safety contract + +A tool that returns `true` promises that its body is safe to run at the same time as other parallel calls. It must not directly mutate the parent session or other parent-owned state; it returns its outputs to the loop, which commits them in model order. + +Any shared state touched during execution must be concurrency-safe. This includes tool wrappers and providers: they may serialize internally or enforce their own capacity, but they must support concurrent dispatch without corrupting state. + +## Configuration and declarations + +`maxParallelToolCalls` is a positive AgentLoop deployment cap shared by every agent the factory creates. It defaults to `10`; `1` preserves serial execution. Exact fields and defaults live in the generated [configuration catalog](../../../config-catalog.md). + +The shipped declarations are conservative. Web search, web fetch, and filesystem read opt in. Filesystem writes and edits, bash tools, subagent delegation, workflow, user interaction, todo mutation, Code Mode, and Cordis mutation tools remain exclusive. A subagent may share its parent's workspace or external resources, and the unary classifier cannot prove that sibling delegations have disjoint effects. Bash has no proven input-sensitive classifier and remains exclusive. + +Filesystem read relies on a narrow recorder exception: its synchronous observation updates may settle out of order, but write and edit re-check the observed version before mutation, so stale state only produces `FS_STALE_VERSION`. + +## Verification + +Unit coverage pins fail-closed classification, typed argument validation, grouping, barriers, live reclassification after registry replacement, the rolling cap, distinct execution objects, middleware order, ordered results and context, and abort draining. First-party tests pin each parallel declaration. + +Snapshot coverage pins the visible multi-call transcript: pending calls may overlap while completed results remain model-ordered. Code Mode coverage pins its serial boundary. No provider-backed e2e is required because scheduling is deterministic loop behavior. + +## Alternatives considered + +**Keep serial execution.** This avoids new ordering and abort cases but retains unnecessary latency for independent sibling calls. + +**Use one tool-level boolean.** A fixed `supportsParallelToolCalls` flag is smaller but cannot distinguish a tool's read-only and mutating operations. The argument-sensitive classifier preserves that distinction. + +**Use stateful classification.** Giving the classifier a live agent, registry, or I/O access makes the decision depend on when it runs and creates a gap between classification and dispatch. Mutable authorization and stale-state checks remain execution-time responsibilities. + +**Use sibling-aware or resource-aware classification.** The scheduler could compare calls pairwise or let each call declare resource read/write claims. This can parallelize non-conflicting writes, but it requires shared resource identity and conflict semantics across unrelated tools. The unary contract instead gives up that concurrency and fails closed when safety is relational. + +**Parallelize the complete tool pipeline.** This keeps the loop on the public one-call API but runs pre- and post-execute middleware concurrently. Existing guards and hook bridges may carry ordered state, so only dispatch overlaps. + +**Expose staged methods or a scheduling waterfall.** Public `prepare` / `dispatch` / `finalize` methods or a `tools/execution-mode` event add extension surface before another consumer needs it. The loop uses an internal scheduler view, while `executionMode(exec)` leaves an insertion point for a policy seam. + +**Start calls while the model streams.** This may reduce latency further but changes assistant-message authority, replay, and call/result pairing. The scheduler starts only after the assistant message is complete. + +**Use fixed-size windows.** Waiting for every call in one window before starting the next leaves capacity idle behind a slow call. The rolling pool preserves the cap without that delay. + +**Expose concurrency metadata to the model.** The model can already emit sibling calls. Host scheduling metadata would enlarge requests without improving tool choice. + +## Consequences + +The design is fail-closed and simple for tool authors, but it cannot exploit concurrency whose safety depends on comparing siblings. A tool that opts in too broadly can expose latent shared-state races. + +Parallel calls may begin in cases where serial execution would have aborted before reaching them. The scheduler therefore records only started calls, drains them on abort, and never starts replacements after cancellation. + +Ordered commits may hold a fast result behind a slow earlier sibling. This preserves replay and model-history order while live surfaces still show pending progress. + +Concurrent external calls can compete for quota or process capacity. Providers own their capacity controls; the loop cap only limits calls from one agent step. + +Tool registration is a scheduling boundary. Registry mutations affect not-yet-started calls because the scheduler reclassifies after each barrier and before every pool replenishment. Already-started calls retain the scheduling decision under which they entered the pool. diff --git a/docs/rfc/implemented/process/2026-07-04-persistence-log-catalog.md b/docs/rfc/implemented/process/2026-07-04-persistence-log-catalog.md index 0de6255322..70a6d60c1a 100644 --- a/docs/rfc/implemented/process/2026-07-04-persistence-log-catalog.md +++ b/docs/rfc/implemented/process/2026-07-04-persistence-log-catalog.md @@ -4,19 +4,19 @@ Status: implemented ## Problem -`SessionEventMap` is the on-disk vocabulary, but its declarations are split across the owning session package and declaration merges. The generated persistence catalog is the single reference for every event and payload; hand-maintained tables drift and are removed. These records are not Cordis events—observers receive them through the single `session/event` bus event—so the Cordis catalog cannot cover them. The generator discovers all declarations and the doc-sync freshness gate rejects omissions or stale output. +`SessionEventMap` is the on-disk vocabulary, but its declarations are split across the owning session package and declaration merges. The generated persistence catalog is the single reference for every event, its complete payload declaration and source JSDoc, and the shared `SessionEvent` envelope; hand-maintained tables drift and are removed. These records are not Cordis events—observers receive them through the single `session/event` bus event—so the Cordis catalog cannot cover them. The generator discovers all declarations and the doc-sync freshness gate rejects omissions or stale output. ## Decision Generate `docs/persistence-catalog.md` from source, with a freshness gate, as the fourth reference surface: the *records* a persisted session log can contain, complementing the cordis catalog (wiring), core-data-structures (vocabulary), and the tool catalog (tools). -`gen-persistence-catalog.ts` scans every owning and declaration-merged `SessionEventMap` with the TypeScript AST. It renders source JSDoc, payload type, derived surface badge, reference links, and source location. The doc-sync freshness check rejects a vocabulary change whose catalog was not regenerated. +`gen-persistence-catalog.ts` scans every owning and declaration-merged `SessionEventMap` with the TypeScript AST. It renders each member from its leading JSDoc through the complete payload type, retaining nested property comments and removing only its containing indentation, and also pastes the owning `SessionEventType`, `SurfaceEventType`, `SurfaceOp`, and `SessionEvent` declarations that compose the persisted envelope. Derived surface badges, reference links, and source locations remain outside the declaration blocks. The doc-sync freshness check rejects a vocabulary or envelope change whose catalog was not regenerated. Specific choices: -- **JSDoc completeness, enforced.** Every member must carry description prose — the JSDoc becomes the catalog entry, the same forcing function the cordis catalog applies to bus events. An `@mode` tag on a member is a hard error: dispatch modes belong to cordis bus events, and a log event has none — the tag would misread as "this fires on the bus with mode X". Violations aggregate into one error listing every offender. +- **JSDoc completeness, enforced.** Every member and rendered envelope type must carry description prose, and the full source JSDoc stays attached to its declaration in the catalog. An `@mode` tag is a hard error: dispatch modes belong to cordis bus events, and persisted records have none. Violations aggregate into one error listing every offender. - **The surface badge is derived, not hand-listed.** `SurfaceEventType` — the subset that produces LLM messages and may carry `surfaceOp` — is parsed from its union declaration in the owning package; a union member naming no declared event is a hard error (a stale union member would otherwise silently badge nothing). Everything else renders **log-only**. -- **A dedicated fence.** Payload blocks use a ` ```ts persistence-catalog ` info string that `doc-typecheck` recognizes and skips, excluded from the opt-out ratio — the same treatment as `ts cordis-catalog` (a bare payload fragment is not standalone-compilable). +- **A dedicated fence.** Declaration blocks use a ` ```ts persistence-catalog ` info string that `doc-typecheck` recognizes and skips, excluded from the opt-out ratio — the same treatment as `ts cordis-catalog` (the declarations reference types from their owning modules and are not standalone-compilable). - **Repo scope.** The catalog enumerates the packages in this repo, matching the siblings' packages-only scope; a downstream plugin can merge further event types, which are outside the catalog by construction. The walk defends its own assumptions with hard errors: the owning top-level `interface SessionEventMap` must be the single exported declaration in `@deepseek-ai/dsh-session` (an unrelated, local, or duplicate same-named interface cannot be catalogued as the on-disk vocabulary), no declaration may carry `extends` (inherited keys would join `keyof SessionEventMap` without a catalog row), every member must be a property signature with an explicit payload type (a method-form member would join `keyof` yet slip past a silent walk), and a duplicate member across declarations fails. This supersedes the hand-copies: the session.md `hook/*` table, the compact README's event table, the hook-protocol README's payload bullets, and the session README's name-list now link the catalog instead of restating payloads (the surrounding semantics prose stays where it was). The two stray `@mode emit` tags on the hook-protocol merge members are removed — the new gate rejects them as the category error they were. @@ -28,7 +28,7 @@ This supersedes the hand-copies: the session.md `hook/*` table, the compact READ ## Consequences -- The catalog cannot drift: a vocabulary change the committed file doesn't reflect fails `verify-persistence-catalog` in the pre-push hook and CI, and a new merged event with no JSDoc fails the generator outright — a plugin can no longer add an undocumented on-disk record type. -- Event prose has a single home, the JSDoc at the declaration; thin JSDoc yields a thin catalog entry, pressuring authors to document at the source. +- The catalog cannot drift: a vocabulary or envelope change the committed file doesn't reflect fails `verify-persistence-catalog` in the pre-push hook and CI, and a new merged event with no JSDoc fails the generator outright — a plugin can no longer add an undocumented on-disk record type. +- Event prose has a single home, the JSDoc at the declaration; the catalog preserves that JSDoc and any nested field comments without flattening or paraphrasing them. - The `SurfaceEventType` union is now structurally load-bearing for docs: renaming an event without updating the union (or vice versa) fails the generator, not just the compiler. - The badge derivation assumes the union stays a closed set of string literals with exactly one owner; a refactor away from that shape must update the generator in the same change. diff --git a/docs/rfc/implemented/process/2026-07-17-run-ci-examples-from-built-lib.i18n.yaml b/docs/rfc/implemented/process/2026-07-17-run-ci-examples-from-built-lib.i18n.yaml new file mode 100644 index 0000000000..9424f2aa24 --- /dev/null +++ b/docs/rfc/implemented/process/2026-07-17-run-ci-examples-from-built-lib.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write +2026-07-17-run-ci-examples-from-built-lib.md: aae88ee965b4e2211f3a53aeb9c0ee4944d95c2a +2026-07-17-run-ci-examples-from-built-lib.zh.md: 0cd3822a71b8f7399be93beaac74b2177fcbe7ca diff --git a/docs/rfc/implemented/process/2026-07-17-run-ci-examples-from-built-lib.md b/docs/rfc/implemented/process/2026-07-17-run-ci-examples-from-built-lib.md new file mode 100644 index 0000000000..aae88ee965 --- /dev/null +++ b/docs/rfc/implemented/process/2026-07-17-run-ci-examples-from-built-lib.md @@ -0,0 +1,42 @@ +# RFC: Run CI examples from built lib + +Status: implemented + +English | [中文](2026-07-17-run-ci-examples-from-built-lib.zh.md) + +## Problem + +CI boots examples and Cordis-backed test projects through `node --import tsx` and the root tsconfig `paths` map. This adds TypeScript transformation cost and changes package resolution: imports resolve to workspace source instead of following package `exports` into built `lib/`. + +These runs therefore do not test the same code or resolution behavior as an installed consumer. A package can pass CI while its built export graph is incomplete or resolves differently. + +## Decision + +Execution has two modes. `src` is the default local-development mode and uses tsx; `lib` is the strict CI mode and starts built bins with plain Node, without tsx or tsconfig path mapping. + +- CI subprocesses that boot an example or a checked-in `cordis.yml` use `lib` mode. +- TypeScript fixtures that only implement an ACP or MCP peer and do not load Cordis run directly with Node. An explicit source-path regression may remain in `src` mode. + +### Resolution topology + +Every test Cordis config must resolve its bare modules by walking upward from the config directory. + +- `examples/` is one pnpm workspace member and provides the shared `examples/node_modules` resolution root. +- Every checked-in test Cordis config, including snapshot configs and package-owned fixtures, lives under its corresponding `examples//` tree. A config owned by `packages///` maps to `examples//tests/fixtures///cordis.yml`; the test driver and assertions remain package-local. +- Every package named by an example Cordis config is declared in both `examples/package.json` for `lib` resolution and the root `tsconfig.json` references for `src` mode. + +### Launch policy + +The shared Loader test harness selects `src` or `lib` from `DSH_EXAMPLE_MODE`. CI builds first and selects `lib`; an unset mode keeps the fast local source loop. + +## Alternatives considered + +- **Keep CI on tsx** — rejected because it preserves transformation overhead and source-only resolution behavior. +- **Use lib everywhere** — rejected because local development would require a build before every run. Dual mode keeps that cost out of the development loop. +- **Build a private `node_modules` tree per test** — rejected because it duplicates consumer scaffolding. The `examples/` workspace root gives every Cordis config one real and declared resolution path. + +## Consequences + +- CI validates built package exports without tsx changing module resolution; local development retains the no-build source loop. +- CI must build before these tests, and manual `lib` runs can observe stale local artifacts. +- Cordis config dependencies are not visible to normal TypeScript import analysis, so `examples/package.json` and the root tsconfig references must stay synchronized with the configs. diff --git a/docs/rfc/implemented/process/2026-07-17-run-ci-examples-from-built-lib.zh.md b/docs/rfc/implemented/process/2026-07-17-run-ci-examples-from-built-lib.zh.md new file mode 100644 index 0000000000..0cd3822a71 --- /dev/null +++ b/docs/rfc/implemented/process/2026-07-17-run-ci-examples-from-built-lib.zh.md @@ -0,0 +1,42 @@ +# RFC: 在 CI 中从构建后的 lib 运行示例 + +Status: implemented + +[English](2026-07-17-run-ci-examples-from-built-lib.md) | 中文 + +## 问题 + +CI 通过 `node --import tsx` 和根 tsconfig 的 `paths` 映射启动示例与加载 Cordis 配置的测试项目。这种方式既增加了 TypeScript 转换开销，也改变了包解析行为：import 会解析到 workspace 源码，而不是经包的 `exports` 进入构建后的 `lib/`。 + +因此，这些测试没有覆盖已安装消费方实际运行的代码和解析路径。即使包的构建导出图不完整或解析结果不同，CI 仍可能通过。 + +## 决策 + +执行机制包含两种模式。`src` 是本地开发的默认模式并使用 tsx；`lib` 是严格的 CI 模式，通过 plain Node 启动构建后的 bin，不加载 tsx，也不使用 tsconfig 路径映射。 + +- CI 中启动示例或签入仓库的 `cordis.yml` 的子进程使用 `lib` 模式。 +- 仅实现 ACP 或 MCP 对端、且不加载 Cordis 的 TypeScript fixture（测试前置数据）直接由 Node 运行。只有显式验证源码路径的回归测试可以保留 `src` 模式。 + +### 解析拓扑 + +每个测试 Cordis 配置都必须能从配置文件所在目录向上解析裸模块。 + +- `examples/` 作为一个 pnpm workspace 成员，提供统一的 `examples/node_modules` 解析根目录。 +- 所有签入仓库的测试 Cordis 配置，包括快照配置和包内测试 fixture，都放在对应的 `examples//` 目录树下。归属 `packages///` 的配置映射到 `examples//tests/fixtures///cordis.yml`；测试驱动和断言仍留在包内。 +- 示例 Cordis 配置中引用的每个包都同时登记在 `examples/package.json` 和根 `tsconfig.json` 的 references 中，分别支持 `lib` 与 `src` 解析。 + +### 启动策略 + +共享 Loader 测试 harness 通过 `DSH_EXAMPLE_MODE` 选择 `src` 或 `lib`。CI 先构建再选择 `lib`；未设置模式时保留快速的本地源码开发回路。 + +## 曾考虑的替代方案 + +- **CI 继续使用 tsx**：不予采纳，因为它会保留转换开销和仅适用于源码的解析行为。 +- **所有环境只使用 lib**：不予采纳，因为本地开发每次运行前都必须构建。双模式避免把这项成本带入开发回路。 +- **每个测试单独构造 `node_modules`**：不予采纳，因为它会重复消费方脚手架。以 `examples/` 作为 workspace 根，可让每个 Cordis 配置通过同一条真实且显式声明的路径解析模块。 + +## 后果 + +- CI 可以验证构建后的包导出，不再受 tsx 模块解析影响；本地开发仍保留免构建的源码回路。 +- CI 必须先构建再运行这些测试；手动执行 `lib` 模式时可能读取陈旧的本地产物。 +- 常规 TypeScript import 分析无法识别 Cordis 配置依赖，因此 `examples/package.json`、根 tsconfig references 与配置文件必须保持同步。 diff --git a/docs/testing.md b/docs/testing.md index d4acdc33c4..8d4f0f554f 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -26,7 +26,12 @@ An e2e assertion re-runs the command or re-reads the file externally; a keyword - Product-visible plugins require a non-unit REAL-composition test. Hand-built `ctx.plugin(...)` suites are insufficient: boot test-only `cordis.yml` through Loader and app/process, mock only external/nondeterministic boundaries, and assert model-visible request/log, durable state, or user-visible output. Keep opt-ins out of shipped defaults. - A guard only guards if the regression actually fails it. For a plugin without `inject` (bundle/composition plugins), a Loader smoke stays green under a broken export shape — add an explicit `expect('default' in mod).toBe(false)` plus an `unwrapExports` round-trip assertion, and prove it: introduce the regression, watch red, revert. - "Real entry path" means the published artifact: the package `bin` points at built `lib/bin.js` under plain `node`, which tsx masks (settle races, module resolution, a swallowed load failure exiting 0). The same applies to any non-index runtime entry the built package resolves at run time (the worker-thread runtime's sibling `lib/worker.cjs`). Keep the built-artifact smokes green (`packages/ui/*/tests/built-bin.e2e.ts`, `packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts`), and assert a genuinely-missing config exits non-zero. -- An e2e that spawns an example from a temp cwd sets `TSX_TSCONFIG_PATH` to the repo-root tsconfig, or it silently falls back to stale built `lib/` ([examples/AGENTS.md](../examples/AGENTS.md)). + +## Test subprocess launch modes + +- CI and build-having test lanes run every example or Cordis-config subprocess from built `lib/` through the shared dual-mode launcher. Do not hand-write `--import tsx` for these subprocesses. +- Protocol and operating-system fixtures that do not load Cordis run erasable `.ts` directly with Node, without tsx or the root paths map. +- Only a test whose subject is source-path resolution may select `src`; state that contract in the test. ## When a snapshot test is required diff --git a/docs/tool-execution-pipeline.md b/docs/tool-execution-pipeline.md index 8db1a68099..5fc21db2f5 100644 --- a/docs/tool-execution-pipeline.md +++ b/docs/tool-execution-pipeline.md @@ -20,9 +20,9 @@ flowchart TD owned["Tool-owned session events
todo/write, fs/observed, hook/invoked, hook/result, tool/code-dispatch"] post["tools/post-execute waterfall
accept, block, replace, add context"] final["tools/result synchronous notification
frozen authoritative outcome"] - context["Buffered additionalContexts
context/message after all tool results"] + context["Active-batch additionalContexts FIFO
context/message after recorded tool results"] toolResult["Session event: tool/result
single model-facing outcome"] - allResults["All calls in the step settled
and tool/result events recorded"] + allResults["Tool batch settled
recorded tool/result events complete"] presentResult["UI completed card
presentResult(args, result)"] model --> toolCall toolCall --> presentCall diff --git a/examples/AGENTS.md b/examples/AGENTS.md index df330de838..6b820368e4 100644 --- a/examples/AGENTS.md +++ b/examples/AGENTS.md @@ -1,6 +1,6 @@ # AGENTS.md — Examples -Runnable harness compositions. **Examples are NOT workspaces**: their private `package.json` files are dependency-free stubs, and the cordis Loader boots each `cordis.yml` unbuilt through `tsx` plus the root tsconfig paths. +Runnable harness compositions. `examples/` is one workspace member and the module-resolution root for runnable and test Cordis configs; it is not a build target. [package.json](package.json) declares the packages loaded by those configs, while each leaf's private `package.json` remains metadata only. Extract reusable logic into `packages/`, where per-file coverage and README gates apply. Examples keep only `cordis.yml` wiring, demo artifacts, and e2e/snapshot scenarios; app package bins own boot glue. @@ -13,7 +13,7 @@ Each example has both: Mock-only examples require only the keyless tier; state that exception in the test. -Keyless stdio smokes use `@deepseek-ai/dsh-loader-smoke` for isolation, root-tsconfig loading, subprocess lifecycle, diagnostics, EOF, and cleanup; tests supply paths, environment, input, and assertions. +Keyless stdio smokes use `@deepseek-ai/dsh-loader-smoke`; tests supply paths, environment, input, and assertions. Every checked-in test Cordis config lives under its corresponding `examples//` leaf. Map a package-owned config to `examples//tests/fixtures///cordis.yml`, keep its driver and assertions package-local, and declare every package it names in both root `tsconfig.json` references and `examples/package.json`. Do not inventory example tests here; the `tests/` trees and root scripts are authoritative. diff --git a/examples/acp-agent/tests/acp.e2e.ts b/examples/acp-agent/tests/acp.e2e.ts index 23c6f58301..b19bc9bfb1 100644 --- a/examples/acp-agent/tests/acp.e2e.ts +++ b/examples/acp-agent/tests/acp.e2e.ts @@ -15,6 +15,7 @@ import { type RequestPermissionResponse, type SessionNotification, } from '@agentclientprotocol/sdk' +import { resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke' /** * Boots examples/acp-agent as an ACP subprocess. The key-gated prompt leg @@ -25,8 +26,6 @@ import { // The child runs from a temp cwd, so its bin and config path are absolute. const binScript = fileURLToPath(new URL('../../../packages/examples/acp-demo/src/bin.ts', import.meta.url)) const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url)) -// Resolve tsx absolutely because the subprocess runs outside the repo. -const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) // The root tsconfig supplies unbuilt workspace `paths`; making it explicit // avoids accidental resolution through stale built output. const repoTsconfig = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url)) @@ -38,24 +37,21 @@ interface Spawned { stderr: string[] } -// TODO(acp-test-harness): this subprocess/client boot glue is duplicated with -// hooks.e2e.ts and partly with dsh-acp-snapshot's harness. Migrate both e2e -// files onto that launcher before the TSX/env/permission-stub details drift. function spawnAcpAgent(cwd: string, env: NodeJS.ProcessEnv = process.env): Spawned { - const child = spawn( - process.execPath, - ['--import', tsxLoader, binScript, '--config', configPath], - { - cwd, - env: { - ...env, - TSX_TSCONFIG_PATH: repoTsconfig, - DSH_PERMISSION_MODE: 'danger-full-access', - DSH_HOME: join(cwd, '.dsh'), - DSH_AGENTS_HOME: join(cwd, '.agents'), - }, - stdio: ['pipe', 'pipe', 'pipe'], + const launch = resolveExampleLaunch({ + srcBin: binScript, + configArgs: ['--config', configPath], + tsconfigPath: repoTsconfig, + env: { + DSH_PERMISSION_MODE: 'danger-full-access', + DSH_HOME: join(cwd, '.dsh'), + DSH_AGENTS_HOME: join(cwd, '.agents'), }, + }) + const child = spawn( + launch.command, + launch.args, + { cwd, env: { ...env, ...launch.env }, stdio: ['pipe', 'pipe', 'pipe'] }, ) const stderr: string[] = [] child.stderr.setEncoding('utf8') @@ -138,16 +134,20 @@ describe('acp-agent over real stdio (no key required)', () => { workdir = await mkdtemp(join(tmpdir(), 'acp-e2e-')) // Collect raw stdout bytes directly (bypass the SDK framing) to inspect. // A dummy key boots the adapter; this purity test sends no prompt and makes no model call. - const child = spawn(process.execPath, ['--import', tsxLoader, binScript, '--config', configPath], { - cwd: workdir, + const launch = resolveExampleLaunch({ + srcBin: binScript, + configArgs: ['--config', configPath], + tsconfigPath: repoTsconfig, env: { - ...process.env, DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? 'sk-dummy-for-boot', - TSX_TSCONFIG_PATH: repoTsconfig, DSH_PERMISSION_MODE: 'danger-full-access', DSH_HOME: join(workdir, '.dsh'), DSH_AGENTS_HOME: join(workdir, '.agents'), }, + }) + const child = spawn(launch.command, launch.args, { + cwd: workdir, + env: { ...process.env, ...launch.env }, stdio: ['pipe', 'pipe', 'pipe'], }) const out: string[] = [] diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts index 23eca9dbc0..e190163a18 100644 --- a/examples/acp-agent/tests/acp.snapshot.ts +++ b/examples/acp-agent/tests/acp.snapshot.ts @@ -53,6 +53,13 @@ const SCENARIOS: Scenario[] = [ // Its prompt and tool-schema sidecars pin the composed header. { name: 'text-turn', hasModelTurn: true, recorded: true, pinsHeader: true }, { name: 'tool-call-turn', hasModelTurn: true, recorded: true }, + { + name: 'parallel-tool-calls', + hasModelTurn: true, + recorded: false, + headerClass: 'fs', + configPath: FS_CONFIG, + }, { name: 'bash-spill', hasModelTurn: true, recorded: false, headerClass: 'fs', configPath: FS_CONFIG }, { name: 'fs-terminal-card', hasModelTurn: true, recorded: true }, { name: 'todo-plan', hasModelTurn: true, recorded: true }, diff --git a/examples/acp-agent/tests/escalation.e2e.ts b/examples/acp-agent/tests/escalation.e2e.ts index e18ecd2f4c..7e1024c23f 100644 --- a/examples/acp-agent/tests/escalation.e2e.ts +++ b/examples/acp-agent/tests/escalation.e2e.ts @@ -15,6 +15,7 @@ import { type RequestPermissionResponse, type SessionNotification, } from '@agentclientprotocol/sdk' +import { resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke' /** * Exercises the default ACP composition through the real bin and Loader. The @@ -28,9 +29,8 @@ import { const binScript = fileURLToPath(new URL('../../../packages/examples/acp-demo/src/bin.ts', import.meta.url)) const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url)) -const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) // The subprocess runs from a temp cwd outside the repo; point tsx at the repo -// tsconfig so the unbuilt `paths` map resolves (see examples/AGENTS.md). +// tsconfig so the unbuilt `paths` map resolves in src mode (see examples/AGENTS.md). const repoTsconfig = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url)) // Without a usable bwrap/Seatbelt runner, the strict attempt fails closed with @@ -55,17 +55,19 @@ interface Spawned { /** Boot the example as an ACP subprocess; the scripted client answers every permission prompt with `answer`. */ function spawnAcpAgent(cwd: string, answer: 'allow-once' | 'reject-once'): Spawned { + const launch = resolveExampleLaunch({ + srcBin: binScript, + configArgs: ['--config', configPath], + tsconfigPath: repoTsconfig, + // A dummy key lets the deepseek adapter boot keyless (presence-checked at + // apply, used only on a real model call); the with-key tests carry the + // real key, so the fallback is inert there. + env: { DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY || 'sk-dummy-for-boot' }, + }) const child = spawn( - process.execPath, - ['--import', tsxLoader, binScript, '--config', configPath], - { - cwd, - // A dummy key lets the deepseek adapter boot keyless (presence-checked at - // apply, used only on a real model call); the with-key tests carry the - // real key, so the fallback is inert there. - env: { ...process.env, DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY || 'sk-dummy-for-boot', TSX_TSCONFIG_PATH: repoTsconfig }, - stdio: ['pipe', 'pipe', 'pipe'], - }, + launch.command, + launch.args, + { cwd, env: { ...process.env, ...launch.env }, stdio: ['pipe', 'pipe', 'pipe'] }, ) const stderr: string[] = [] child.stderr.setEncoding('utf8') diff --git a/examples/acp-agent/tests/hooks.e2e.ts b/examples/acp-agent/tests/hooks.e2e.ts index 99cebb907e..68dc2648bf 100644 --- a/examples/acp-agent/tests/hooks.e2e.ts +++ b/examples/acp-agent/tests/hooks.e2e.ts @@ -15,6 +15,7 @@ import { type RequestPermissionResponse, type SessionNotification, } from '@agentclientprotocol/sdk' +import { resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke' /** * With-key e2e for the Claude hook bridge. The process-level `./hooks.json` is @@ -25,7 +26,6 @@ import { const binScript = fileURLToPath(new URL('../../../packages/examples/acp-demo/src/bin.ts', import.meta.url)) const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url)) -const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) const repoTsconfig = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url)) interface Spawned { @@ -36,10 +36,16 @@ interface Spawned { } function spawnAcpAgent(cwd: string): Spawned { + const launch = resolveExampleLaunch({ + srcBin: binScript, + configArgs: ['--config', configPath], + tsconfigPath: repoTsconfig, + env: { DSH_PERMISSION_MODE: 'danger-full-access' }, + }) const child = spawn( - process.execPath, - ['--import', tsxLoader, binScript, '--config', configPath], - { cwd, env: { ...process.env, TSX_TSCONFIG_PATH: repoTsconfig, DSH_PERMISSION_MODE: 'danger-full-access' }, stdio: ['pipe', 'pipe', 'pipe'] }, + launch.command, + launch.args, + { cwd, env: { ...process.env, ...launch.env }, stdio: ['pipe', 'pipe', 'pipe'] }, ) const stderr: string[] = [] child.stderr.setEncoding('utf8') diff --git a/examples/acp-agent/tests/snapshots/parallel-tool-calls/input.json b/examples/acp-agent/tests/snapshots/parallel-tool-calls/input.json new file mode 100644 index 0000000000..e5356e4af5 --- /dev/null +++ b/examples/acp-agent/tests/snapshots/parallel-tool-calls/input.json @@ -0,0 +1,7 @@ +{ + "steps": [ + { "op": "initialize" }, + { "op": "newSession" }, + { "op": "prompt", "text": "Use the read tool twice in the same assistant message: read a.txt and b.txt. Then reply DONE." } + ] +} diff --git a/examples/acp-agent/tests/snapshots/parallel-tool-calls/session.jsonl b/examples/acp-agent/tests/snapshots/parallel-tool-calls/session.jsonl new file mode 100644 index 0000000000..81503dc4cf --- /dev/null +++ b/examples/acp-agent/tests/snapshots/parallel-tool-calls/session.jsonl @@ -0,0 +1,28 @@ +{"type":"session","version":0,"id":"{{sessionId}}","createdAt":0,"cwd":"{{cwd}}"} +{"type":"turn/start","seq":0,"time":0,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} +{"type":"user/message","seq":1,"time":0,"data":{"content":[{"type":"text","text":"Use the read tool twice in the same assistant message: read a.txt and b.txt. Then reply DONE."}],"source":{"kind":"user"}},"surfaceOp":"append"} +{"type":"step/start","seq":2,"time":0,"data":{"turn":1,"step":1}} +{"type":"request/header","seq":3,"time":0,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}} +{"type":"assistant/chunk","seq":4,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}} +{"type":"assistant/chunk","seq":5,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"call_read_a","name":"read","argumentsDelta":"{\"file_path\":\"a.txt\"}"}}} +{"type":"assistant/chunk","seq":6,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_read_a","name":"read","arguments":"{\"file_path\":\"a.txt\"}"}}}} +{"type":"assistant/chunk","seq":7,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}} +{"type":"assistant/chunk","seq":8,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_read_b","name":"read","argumentsDelta":"{\"file_path\":\"b.txt\"}"}}} +{"type":"assistant/chunk","seq":9,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_read_b","name":"read","arguments":"{\"file_path\":\"b.txt\"}"}}}} +{"type":"assistant/chunk","seq":10,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}} +{"type":"assistant/chunk","seq":11,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","seq":12,"time":0,"data":{"turn":1,"step":1,"content":[{"type":"tool-call","id":"call_read_a","name":"read","arguments":"{\"file_path\":\"a.txt\"}"},{"type":"tool-call","id":"call_read_b","name":"read","arguments":"{\"file_path\":\"b.txt\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[4,5,6,7,8,9,10,11],"surfaceOp":"append"} +{"type":"tool/call","seq":13,"time":0,"data":{"turn":1,"step":1,"callId":"call_read_a","name":"read","arguments":"{\"file_path\":\"a.txt\"}"}} +{"type":"tool/call","seq":14,"time":0,"data":{"turn":1,"step":1,"callId":"call_read_b","name":"read","arguments":"{\"file_path\":\"b.txt\"}"}} +{"type":"tool/result","seq":15,"time":0,"data":{"turn":1,"step":1,"callId":"call_read_a","content":[{"type":"text","text":"{{cwd}}/a.txt\nfile\n\n1: alpha\n\n(End of file - total 1 lines)\n"}],"isError":false},"sourceEventSeqs":[13],"surfaceOp":"append"} +{"type":"tool/result","seq":16,"time":0,"data":{"turn":1,"step":1,"callId":"call_read_b","content":[{"type":"text","text":"{{cwd}}/b.txt\nfile\n\n1: beta\n\n(End of file - total 1 lines)\n"}],"isError":false},"sourceEventSeqs":[14],"surfaceOp":"append"} +{"type":"step/end","seq":17,"time":0,"data":{"turn":1,"step":1}} +{"type":"step/start","seq":18,"time":0,"data":{"turn":1,"step":2}} +{"type":"assistant/chunk","seq":19,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"text"}}} +{"type":"assistant/chunk","seq":20,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":0,"text":"DONE"}}} +{"type":"assistant/chunk","seq":21,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DONE"}}}} +{"type":"assistant/chunk","seq":22,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":1}}}} +{"type":"assistant/chunk","seq":23,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","seq":24,"time":0,"data":{"turn":1,"step":2,"content":[{"type":"text","text":"DONE"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":10,"outputTokens":1}},"sourceEventSeqs":[19,20,21,22,23],"surfaceOp":"append"} +{"type":"step/end","seq":25,"time":0,"data":{"turn":1,"step":2}} +{"type":"turn/end","seq":26,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/examples/acp-agent/tests/snapshots/parallel-tool-calls/stdout.golden.jsonl b/examples/acp-agent/tests/snapshots/parallel-tool-calls/stdout.golden.jsonl new file mode 100644 index 0000000000..6d7bc199e8 --- /dev/null +++ b/examples/acp-agent/tests/snapshots/parallel-tool-calls/stdout.golden.jsonl @@ -0,0 +1,8 @@ +{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}} +{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"Sets this session's sandbox and approval behavior.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_read_a","title":"Read a.txt","kind":"read","status":"in_progress","locations":[{"path":"a.txt","line":1}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_read_b","title":"Read b.txt","kind":"read","status":"in_progress","locations":[{"path":"b.txt","line":1}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_read_a","status":"completed","content":[{"type":"content","content":{"type":"text","text":"{{cwd}}/a.txt\nfile\n\n1: alpha\n\n(End of file - total 1 lines)\n"}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_read_b","status":"completed","content":[{"type":"content","content":{"type":"text","text":"{{cwd}}/b.txt\nfile\n\n1: beta\n\n(End of file - total 1 lines)\n"}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"DONE"}}}} +{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}} diff --git a/examples/acp-agent/tests/snapshots/parallel-tool-calls/workspace/a.txt b/examples/acp-agent/tests/snapshots/parallel-tool-calls/workspace/a.txt new file mode 100644 index 0000000000..4a58007052 --- /dev/null +++ b/examples/acp-agent/tests/snapshots/parallel-tool-calls/workspace/a.txt @@ -0,0 +1 @@ +alpha diff --git a/examples/acp-agent/tests/snapshots/parallel-tool-calls/workspace/b.txt b/examples/acp-agent/tests/snapshots/parallel-tool-calls/workspace/b.txt new file mode 100644 index 0000000000..65b2df87f7 --- /dev/null +++ b/examples/acp-agent/tests/snapshots/parallel-tool-calls/workspace/b.txt @@ -0,0 +1 @@ +beta diff --git a/packages/context/time-context/tests/fixtures/cordis.yml b/examples/echo-agent/tests/fixtures/context/time-context/cordis.yml similarity index 88% rename from packages/context/time-context/tests/fixtures/cordis.yml rename to examples/echo-agent/tests/fixtures/context/time-context/cordis.yml index 480a93c39b..9b59e2ded9 100644 --- a/packages/context/time-context/tests/fixtures/cordis.yml +++ b/examples/echo-agent/tests/fixtures/context/time-context/cordis.yml @@ -1,6 +1,6 @@ # Test-only composition: keep time-context opt-in while exercising its real Loader/app path. - id: mock-llm - name: '../../../../../examples/echo-agent/src/mock-llm.ts' + name: '../../../../src/mock-llm.ts' - id: bash name: '@deepseek-ai/dsh-bash-local' diff --git a/examples/package.json b/examples/package.json new file mode 100644 index 0000000000..8d77731a05 --- /dev/null +++ b/examples/package.json @@ -0,0 +1,46 @@ +{ + "name": "dsh-examples", + "private": true, + "version": "0.0.1", + "type": "module", + "description": "Workspace umbrella for runnable demos and example-owned test compositions: declares their cordis.yml packages so plain Node resolves real exports→lib. Not a build target.", + "dependencies": { + "@cordisjs/plugin-hmr": "workspace:*", + "@cordisjs/plugin-include": "workspace:*", + "@deepseek-ai/dsh-acp-demo": "workspace:*", + "@deepseek-ai/dsh-bash-local": "workspace:*", + "@deepseek-ai/dsh-bash-sandbox": "workspace:*", + "@deepseek-ai/dsh-code-runtime-worker": "workspace:*", + "@deepseek-ai/dsh-compact-basic": "workspace:*", + "@deepseek-ai/dsh-fs-local": "workspace:*", + "@deepseek-ai/dsh-fs-policy": "workspace:*", + "@deepseek-ai/dsh-hooks-claude": "workspace:*", + "@deepseek-ai/dsh-hooks-codex": "workspace:*", + "@deepseek-ai/dsh-llm": "workspace:*", + "@deepseek-ai/dsh-llm-deepseek": "workspace:*", + "@deepseek-ai/dsh-llm-replay": "workspace:*", + "@deepseek-ai/dsh-permission": "workspace:*", + "@deepseek-ai/dsh-repeat-tool-guard": "workspace:*", + "@deepseek-ai/dsh-sandbox-local": "workspace:*", + "@deepseek-ai/dsh-spill-local": "workspace:*", + "@deepseek-ai/dsh-spill-policy": "workspace:*", + "@deepseek-ai/dsh-stdio-demo": "workspace:*", + "@deepseek-ai/dsh-subagent": "workspace:*", + "@deepseek-ai/dsh-subagent-fork": "workspace:*", + "@deepseek-ai/dsh-subagent-spawn": "workspace:*", + "@deepseek-ai/dsh-time-context": "workspace:*", + "@deepseek-ai/dsh-timeout-policy": "workspace:*", + "@deepseek-ai/dsh-token-meter": "workspace:*", + "@deepseek-ai/dsh-tool-cordis": "workspace:*", + "@deepseek-ai/dsh-tool-fs": "workspace:*", + "@deepseek-ai/dsh-tool-fs-search": "workspace:*", + "@deepseek-ai/dsh-tool-subagent": "workspace:*", + "@deepseek-ai/dsh-tool-todo": "workspace:*", + "@deepseek-ai/dsh-tool-workflow": "workspace:*", + "@deepseek-ai/dsh-tools": "workspace:*", + "@deepseek-ai/dsh-user-approval": "workspace:*", + "@deepseek-ai/dsh-web": "workspace:*", + "@deepseek-ai/dsh-web-fetch-local": "workspace:*", + "@deepseek-ai/dsh-workflow-workerthread": "workspace:*" + } +} diff --git a/knip.json b/knip.json index 9c644cebb7..ad83bbbd2e 100644 --- a/knip.json +++ b/knip.json @@ -5,15 +5,16 @@ "ignoreWorkspaces": ["vendor/*", "python/sdk-runtime", "website"], "workspaces": { ".": { + "project": ["scripts/**/*.ts"] + }, + "examples": { "entry": [ - "examples/echo-agent/src/*.ts", - "examples/echo-agent/tests/**/*.e2e.ts", - "examples/coding-agent/tests/**/*.e2e.ts", - "examples/cordis-agent/tests/**/*.e2e.ts", - "examples/acp-agent/tests/**/*.e2e.ts", - "examples/*/tests/**/*.snapshot.ts" + "echo-agent/src/*.ts", + "*/tests/**/*.e2e.ts", + "*/tests/**/*.snapshot.ts" ], - "project": ["scripts/**/*.ts", "examples/**/*.ts"] + "project": ["**/*.ts"], + "ignoreDependencies": ["@deepseek-ai/.+", "@cordisjs/.+"] }, "packages/*/*": { "entry": ["tests/**/*.spec.ts"], @@ -52,8 +53,7 @@ }, "packages/support/acp-snapshot": { "entry": ["tests/**/*.spec.ts", "tests/fixtures/fake-acp-agent.ts"], - "project": ["src/**/*.ts", "tests/**/*.ts"], - "ignoreDependencies": ["cordis"] + "project": ["src/**/*.ts", "tests/**/*.ts"] }, "packages/support/loader-smoke": { "entry": ["tests/**/*.spec.ts", "tests/fixtures/*.ts"], diff --git a/packages/context/time-context/package.json b/packages/context/time-context/package.json index 8900eaf900..c0d69a75cb 100644 --- a/packages/context/time-context/package.json +++ b/packages/context/time-context/package.json @@ -33,6 +33,7 @@ "@deepseek-ai/dsh-agent-loop": "workspace:^", "@deepseek-ai/dsh-agent-loop-testkit": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", + "@deepseek-ai/dsh-loader-smoke": "workspace:^", "@deepseek-ai/dsh-session": "workspace:^", "@deepseek-ai/dsh-system-prompt": "workspace:^", "@deepseek-ai/dsh-tools": "workspace:^", diff --git a/packages/context/time-context/tests/time-context.e2e.ts b/packages/context/time-context/tests/time-context.e2e.ts index 5c9b4e8e62..f14981ea36 100644 --- a/packages/context/time-context/tests/time-context.e2e.ts +++ b/packages/context/time-context/tests/time-context.e2e.ts @@ -4,12 +4,17 @@ import { tmpdir } from 'node:os' import { join } from 'node:path' import { fileURLToPath } from 'node:url' import { afterEach, describe, expect, it } from 'vitest' -import type { SessionEvent } from '@deepseek-ai/dsh-session' +import { type SessionEvent } from '@deepseek-ai/dsh-session' +import { resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke' +// Keep the Loader config under examples so both modes exercise the same deployable +// topology: local fixture source plus bare plugins owned by the examples workspace. const binScript = fileURLToPath(new URL('../../../examples/stdio-demo/src/bin.ts', import.meta.url)) -const configPath = fileURLToPath(new URL('./fixtures/cordis.yml', import.meta.url)) +const configPath = fileURLToPath(new URL( + '../../../../examples/echo-agent/tests/fixtures/context/time-context/cordis.yml', + import.meta.url, +)) const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url)) -const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) const PROCESS_TIMEOUT_MS = 30_000 const TEST_TIMEOUT_MS = PROCESS_TIMEOUT_MS + 15_000 const FIRST_REPLY = '[main turn 1] You said: "Time sampled while preparing turn 1, step 1:' @@ -39,21 +44,22 @@ async function runTwoTurns(): Promise<{ stdout: string; stderr: string }> { workdir = await mkdtemp(join(tmpdir(), 'time-context-e2e-')) const cwd = workdir return new Promise((resolve, reject) => { - const proc = spawn( - process.execPath, - ['--expose-internals', '--import', tsxLoader, binScript, configPath], - { - cwd, - env: { - ...process.env, - TZ: 'Asia/Shanghai', - TSX_TSCONFIG_PATH: repoTsconfig, - DSH_HOME: join(cwd, '.dsh'), - DSH_AGENTS_HOME: join(cwd, '.agents'), - }, - stdio: ['pipe', 'pipe', 'pipe'], + const launch = resolveExampleLaunch({ + srcBin: binScript, + configArgs: [configPath], + tsconfigPath: repoTsconfig, + exposeInternals: true, + env: { + TZ: 'Asia/Shanghai', + DSH_HOME: join(cwd, '.dsh'), + DSH_AGENTS_HOME: join(cwd, '.agents'), }, - ) + }) + const proc = spawn(launch.command, launch.args, { + cwd, + env: { ...process.env, ...launch.env }, + stdio: ['pipe', 'pipe', 'pipe'], + }) child = proc let stdout = '' let stderr = '' diff --git a/packages/context/time-context/tsconfig.json b/packages/context/time-context/tsconfig.json index f8e14d8aa2..7815242b55 100644 --- a/packages/context/time-context/tsconfig.json +++ b/packages/context/time-context/tsconfig.json @@ -10,6 +10,9 @@ { "path": "../../../vendor/cordis" }, { "path": "../../../vendor/schemastery" }, { "path": "../../llm/llm" }, - { "path": "../../core/agent" } + { "path": "../../core/agent" }, + { "path": "../../core/system-prompt" }, + { "path": "../../core/agent" }, + { "path": "../../support/loader-smoke" } ] } diff --git a/packages/context/workspace-context/README.md b/packages/context/workspace-context/README.md index 910c1cfdac..430ffe8a41 100644 --- a/packages/context/workspace-context/README.md +++ b/packages/context/workspace-context/README.md @@ -46,7 +46,7 @@ The core `context/message` envelope is disabled for these messages because the p ## State And Refresh -Model-visible text contains no hidden state markers. Each dynamic context event instead carries JSON metadata with a versioned list of `{ action, scope, path, previousPath?, digest? }` changes. On every relevant tool touch, the plugin reconstructs loaded state from its visible session events and overlays a short in-memory pending window for context present on the immutable top-level `tools/result` but not yet appended by the loop. A matching durable `context/message` confirms the pending transition. If the owning `step/end` arrives first because a later tool aborted the step and the loop discarded its context buffer, the plugin clears the pending transition and its version fast path so the next successful touch can load it again. Nested Code Mode results stage pending changes under the outer execution token for same-run duplicate suppression; the outer result rolls that state back and recommits only contexts that survived outer policy. +Model-visible text contains no hidden state markers. Each dynamic context event instead carries JSON metadata with a versioned list of `{ action, scope, path, previousPath?, digest? }` changes. On every relevant tool touch, the plugin reconstructs loaded state from its visible session events and overlays a short in-memory pending window for context present on the immutable top-level `tools/result` but not yet appended by the loop. A matching durable `context/message` confirms the pending transition. If the owning `step/end` arrives before a matching context reaches the log, the plugin clears the pending transition and its version fast path so the next successful touch can load it again. Nested Code Mode results stage pending changes under the outer execution token for same-run duplicate suppression; the outer result rolls that state back and recommits only contexts that survived outer policy. An unchanged path and SHA-1 content digest is not injected again. A per-session, per-scope metadata cache stores only `{ path, version, digest }`: when the provider's opaque `FsVersion` and the effective visible state both match, reconciliation skips the content read; a changed version triggers a bounded read and SHA-1 confirmation before any model-visible update. Resume works because SHA-1 state is persisted in the session log, while an empty in-memory version cache merely causes one confirming read. Compaction re-arms a scope after its context event leaves the visible surface even when the cached version is unchanged. A removal is a tombstone, so a later candidate reappearance is loaded again. Only model-visible changes actually rendered within the byte budget enter metadata, pending state, and the version cache; an omitted change remains eligible for a later touch, while a same-digest version refresh updates metadata only. diff --git a/packages/context/workspace-context/src/state.ts b/packages/context/workspace-context/src/state.ts index 98b8fcc066..4e8ee7de56 100644 --- a/packages/context/workspace-context/src/state.ts +++ b/packages/context/workspace-context/src/state.ts @@ -255,8 +255,8 @@ function invalidateInstructionVersions( /** * Settle provisional tool-result state against durable session events. * A matching context event confirms the transition. If its owning step closes - * first, the loop discarded its context buffer, so both duplicate suppression - * and the metadata fast path must be re-armed for the next successful touch. + * first, both duplicate suppression and the metadata fast path are re-armed for + * the next successful touch. * @param session - session whose append-only log emitted `event`. * @param event - newly committed session event. * @param pendingBySession - provisional transitions awaiting log confirmation. diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts index b3a9947221..2894937c9c 100644 --- a/packages/context/workspace-context/tests/workspace-context.spec.ts +++ b/packages/context/workspace-context/tests/workspace-context.spec.ts @@ -1562,7 +1562,7 @@ describe('workspace context request injection', () => { }) describe('dynamic nested workspace context injection', () => { - it('re-arms a buffered instruction change when a later tool aborts the step before context append', async () => { + it('commits a buffered instruction change before a later tool abort closes the step', async () => { const root = await tempRepo() const home = await tempRepo() const ctx = new Context() @@ -1604,12 +1604,14 @@ describe('dynamic nested workspace context injection', () => { agent.send([{ type: 'text', text: 'read and abort' }]) await agent.whenIdle() - expect(agent.session.events.filter(event => event.type === 'context/message')).toHaveLength(0) + expect(agent.session.events.filter(event => event.type === 'context/message')).toHaveLength(1) agent.send([{ type: 'text', text: 'retry the read' }]) await agent.whenIdle() const contexts = agent.session.events.filter(event => event.type === 'context/message') + // The aborted batch drained its accepted context before step close, so the + // retry sees durable history without producing a duplicate instruction. expect(contexts).toHaveLength(1) expect(adapter.requests).toHaveLength(3) expect(adapter.requests[2]?.messages.map(blocks => blocksText(blocks.content)).join('\n')) diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts index b49cb54026..07b6228d62 100644 --- a/packages/cordis/tool-cordis/src/api-catalog.ts +++ b/packages/cordis/tool-cordis/src/api-catalog.ts @@ -260,6 +260,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ 'guard(guard: ToolGuard): () => void', 'get(name: string, scope?: ScopeKey): ToolDefinition | undefined', 'schemas(scope?: ScopeKey): ToolSchema[]', + 'executionMode(exec: ToolExecutionInput): ToolExecutionMode', 'async execute(exec: ToolExecutionInput): Promise', ], }, @@ -1124,7 +1125,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'ToolDefinition', - declaration: 'export interface ToolDefinition extends ToolSchema {\n execute(args: unknown, exec: ToolRunContext): Promise;\n timeoutMs?: number;\n presentCall?(args: unknown): ToolCallView | undefined;\n presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n}', + declaration: 'export interface ToolDefinition extends ToolSchema {\n execute(args: unknown, exec: ToolRunContext): Promise;\n timeoutMs?: number;\n isConcurrencySafe?(args: unknown): boolean;\n presentCall?(args: unknown): ToolCallView | undefined;\n presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n}', }, { name: 'ToolErrorInfo', @@ -1142,6 +1143,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'ToolExecutionInput', declaration: 'export interface ToolExecutionInput {\n readonly callId: CallId;\n readonly name: string;\n readonly arguments: unknown;\n readonly agent?: Agent;\n readonly parent?: ToolExecutionToken;\n signal?: AbortSignal;\n}', }, + { + name: 'ToolExecutionMode', + declaration: 'export type ToolExecutionMode = {\n kind: \'parallel\';\n} | {\n kind: \'exclusive\';\n};', + }, { name: 'ToolExecutionResult', declaration: 'export interface ToolExecutionResult {\n content: ContentBlock[];\n isError: boolean;\n error?: ToolErrorInfo;\n additionalContexts?: HookContext[];\n meta?: unknown;\n}', diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md index 0f26a457c2..cdbf2e49a2 100644 --- a/packages/core/agent-loop/README.md +++ b/packages/core/agent-loop/README.md @@ -29,6 +29,7 @@ The config-driven `ctx.agentLoop.create()` path keeps its agent owned by the loo ```ts interface Config { + maxParallelToolCalls?: number // default 10; 1 is serial agents: Array<{ id: string // required provider?: string @@ -39,13 +40,13 @@ interface Config { } ``` -Configured agents start automatically. A model call requires both `provider` and `model`; `agent/request` may supply a missing pair before dispatch. `cwd` applies only to fresh sessions, while `resumeSessionId` retains persisted metadata. Configured agents use the deployment persona, and programmatic setup can shadow it per agent. This plugin supplies the per-agent `provider`, `model`, and `cwd` prompt variables; harness identity and deployment persona belong to `dsh-system-prompt`. +Configured agents start automatically. A model call requires both `provider` and `model`; `agent/request` may supply a missing pair before dispatch. `maxParallelToolCalls` bounds every agent's rolling pool for parallel-safe calls and defaults to `10`. `cwd` applies only to fresh sessions, while `resumeSessionId` retains persisted metadata. Configured agents use the deployment persona, and programmatic setup can shadow it per agent. This plugin supplies the per-agent `provider`, `model`, and `cwd` prompt variables; harness identity and deployment persona belong to `dsh-system-prompt`. ### Exported concrete class - `ReactLoopAgent` — the concrete `Agent` implementation. Its inbox is a JavaScript native-private field, and one prepared session can be claimed by only one concrete driver. Everything observable happens through session events and the `agent/*` event taxonomy. -`Inbox`, `runLoop`, and the instance-bound publication/start controls are package-internal. The package root does not export them, and the package exports map exposes no `./src/*` escape hatch; lifecycle owners create agents through `ctx.agents` rather than constructing or starting the driver internals. `ReactLoopAgent.send()` and running `steer()` materialize content plus resolved source once as detached, deeply frozen lossless JSON, then share that accepted record between `agent/queued` and the inbox; malformed data throws before either boundary. +`Inbox`, `runLoop`, and the instance-bound publication/start controls are package-internal. The package root does not export them, and the package exports map exposes no `./src/*` escape hatch; lifecycle owners create agents through `ctx.agents` rather than constructing or starting the driver internals. `ReactLoopAgent.send()`, running `steer()`, and open-turn `inject()` materialize content plus resolved source once as detached, deeply frozen lossless JSON; malformed data throws before enqueue or append. An injection that arrives while the current step executes assistant tool calls stays in a FIFO until the batch settles; successful batches place it after the complete result batch, and interrupted batches drain it before the turn closes. ### Loop lifecycle (`loop.ts`) @@ -55,6 +56,8 @@ Every provider call that reaches a successful finish appends exactly one `assist Plugin failure ends the current turn, not the loop. Cancellation clears pending work and aborts the current step without leaking to the next prompt. Terminal continuation stops remain authoritative through turn close and durability flush. +Within a step, exclusive calls form barriers; parallel-safe calls use a bounded rolling pool and are reclassified before start. Only dispatch/body overlaps. Policy, durable results, and result context remain model-ordered. Abort stops new calls, drains started results, then drains accepted batch context before the turn closes through the normal abort path. + ### What belongs to plugins Everything that goes beyond "call the model, run the tools, repeat" belongs to plugins listening on the event taxonomy: @@ -81,7 +84,7 @@ Everything that goes beyond "call the model, run the tools, repeat" belongs to p ## Known Limitations and Deferred Work -- **Tool calls within a step execute sequentially** — parallel execution waits on concurrency-safety metadata in the tool contract (see `dsh-tools`). +- **Classification is unary** — calls whose safety depends on comparing siblings or resources must remain exclusive ([rationale](../../../docs/rfc/implemented/feature/2026-07-10-parallel-tool-call-execution.md)). - **No resume-or-create policy on the config path** — config-driven `create()` starts a fresh `${id}-session-` every run (`TODO(demo)`), and a config `resumeSessionId` whose resume fails logs a warning and creates no agent. - **Config agents have no per-agent persona field or setup hook** — they use the deployment persona; scoped persona/tool composition is available only through the programmatic `ctx.agents.create()` / `resume()` factory options. - **No built-in turn budget** — the default continuation is `continue` whenever a step had tool calls or steering; bounding a runaway turn requires an `agent/turn-continuation` force-stop plugin. diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts index 2cd7f16682..c8784453b9 100644 --- a/packages/core/agent-loop/src/agent.ts +++ b/packages/core/agent-loop/src/agent.ts @@ -8,7 +8,7 @@ import type { Context } from 'cordis' import { agentEvents } from '@deepseek-ai/dsh-agent' -import type { AgentId, AgentOptions, AgentStatus, InjectOptions, SendOptions } from '@deepseek-ai/dsh-agent' +import type { AgentId, AgentOptions, AgentStatus, HookContext, InjectOptions, SendOptions } from '@deepseek-ai/dsh-agent' import type { Agent } from '@deepseek-ai/dsh-agent' import { deepFreeze } from '@deepseek-ai/dsh-llm' import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm' @@ -54,15 +54,16 @@ export interface PreparedReactLoopAgent { * @param id - the concrete agent identity. * @param options - loop options for the agent. * @param session - the prepared session the agent will own. + * @param maxParallelToolCalls - resolved in-flight cap for this agent. * @returns the agent and closures bound only to that exact instance. */ export function prepareReactLoopAgent( - ctx: Context, id: AgentId, options: AgentOptions, session: Session, + ctx: Context, id: AgentId, options: AgentOptions, session: Session, maxParallelToolCalls: number, ): PreparedReactLoopAgent { if (claimedDriverSessions.has(session)) { throw new Error(`session "${session.id}" already has a concrete agent driver`) } - const agent = new ReactLoopAgent(ctx, id, options, session) + const agent = new ReactLoopAgent(ctx, id, options, session, maxParallelToolCalls) claimedDriverSessions.add(session) const dispose = () => agent[stopDriver]() return { @@ -143,19 +144,27 @@ export class ReactLoopAgent implements Agent { * the `disposed` transition fires and leave the promise hanging. */ private idleWaiters: (() => void)[] = [] + /** Maximum parallel-safe calls allowed in one step. */ + private readonly maxParallelToolCalls: number /** * Durability checkpoints started by idle {@link inject} calls. `inject()` is * synchronous, so it cannot await them itself; the driver disposer drains * this set before the lifecycle unregisters the agent or detaches its session. */ private pendingIdleFlushes = new Set>() + /** Whether the current step is executing an assistant tool-call batch. */ + private toolBatchActive = false + /** Open-turn injections waiting for the active assistant tool-call batch to close. */ + private deferredInjections: HookContext[] = [] constructor( private loopCtx: Context, public readonly id: AgentId, public readonly options: AgentOptions, public readonly session: Session, + maxParallelToolCalls: number, ) { + this.maxParallelToolCalls = maxParallelToolCalls const { promise, resolve } = Promise.withResolvers() this.disposed = promise this.resolveDisposed = resolve @@ -189,12 +198,11 @@ export class ReactLoopAgent implements Agent { } /** - * Accept one public send/steer payload as the exact detached record shared by - * the live notification and inbox. Lossless-JSON materialization reads every - * nested field once; deep freeze prevents an observer from rewriting queued - * work before the loop drains it. + * Accept one public message payload as a detached record. Lossless-JSON + * materialization reads every nested field once; deep freeze prevents later + * caller mutation before an inbox or deferred-injection queue drains it. */ - private acceptInboxMessage(content: ContentBlock[], options?: SendOptions): InboxMessage { + private acceptMessage(content: ContentBlock[], options?: SendOptions): InboxMessage { const source = this.resolveSource(options) const accepted = snapshotJsonValue({ content, source }) if (accepted === undefined) { @@ -203,6 +211,15 @@ export class ReactLoopAgent implements Agent { return deepFreeze(accepted) } + /** Detach one context before it can outlive its caller in the active-batch FIFO. */ + private acceptContext(context: HookContext): HookContext { + const accepted = snapshotJsonValue(context) + if (accepted === undefined) { + throw new TypeError('agent context must be losslessly JSON-serializable') + } + return deepFreeze(accepted) + } + /** Reject a driving operation once teardown has synchronously closed the agent. */ private assertNotDisposed(): void { if (this._status === 'disposed') throw new Error(`agent "${this.id}" is disposed`) @@ -210,7 +227,7 @@ export class ReactLoopAgent implements Agent { send(content: ContentBlock[], options?: SendOptions): void { this.assertNotDisposed() - const accepted = this.acceptInboxMessage(content, options) + const accepted = this.acceptMessage(content, options) this.#inbox.enqueue(accepted) const info = { source: accepted.source, steering: false } as const agentEvents(this.loopCtx, this).emit('agent/queued', accepted.content, info) @@ -219,7 +236,7 @@ export class ReactLoopAgent implements Agent { steer(content: ContentBlock[], options?: SendOptions): void { this.assertNotDisposed() if (this._status !== 'running') { this.send(content, options); return } - const accepted = this.acceptInboxMessage(content, options) + const accepted = this.acceptMessage(content, options) this.#inbox.steer(accepted) const info = { source: accepted.source, steering: true } as const agentEvents(this.loopCtx, this).emit('agent/queued', accepted.content, info) @@ -235,10 +252,15 @@ export class ReactLoopAgent implements Agent { ...options?.meta !== undefined ? { meta: options.meta } : {}, } if (isTurnOpen(this.session)) { - // A turn is open in the LOG (decided from the log, not agent status — - // status can be `running` with no turn open): the context/message is - // turn-enclosed by that turn, so append it directly. - this.session.append('context/message', context, { surfaceOp: 'append' }) + const accepted = this.acceptContext(context) + // Provider protocols require every assistant tool-call batch to be + // followed only by its tool results. Historical interrupted batches do + // not own new context; only the currently executing batch may defer it. + if (this.toolBatchActive) { + this.deferredInjections.push(accepted) + return + } + this.session.append('context/message', accepted, { surfaceOp: 'append' }) return } // No turn open: wrap the injection in a one-shot turn so every event stays @@ -278,6 +300,34 @@ export class ReactLoopAgent implements Agent { } } + /** Append deferred open-turn injections after the loop closes a tool-result batch. */ + private drainDeferredInjections(): void { + const pending = this.deferredInjections.splice(0) + for (const accepted of pending) { + this.session.append('context/message', accepted, { surfaceOp: 'append' }) + } + } + + /** + * Run one tool-call batch and drain its deferred context before settlement. + * The loop-owned acceptor remains valid after public disposal begins because + * the interrupted turn stays open until this batch settles. + */ + private async withToolBatch( + run: (acceptContext: (context: HookContext) => void) => Promise, + ): Promise { + this.toolBatchActive = true + const acceptContext = (context: HookContext): void => { + this.deferredInjections.push(this.acceptContext(context)) + } + try { + return await run(acceptContext) + } finally { + this.toolBatchActive = false + this.drainDeferredInjections() + } + } + cancel(reason?: string): void { // Arm only for current work; an idle marker would cancel the next prompt. if (this._status === 'running' || this.currentAbort !== undefined || this.#inbox.hasQueued || this.#inbox.hasSteering) { @@ -335,6 +385,7 @@ export class ReactLoopAgent implements Agent { this.driverStarted = true this.done = runLoop(this.loopCtx, this, { inbox: this.#inbox, + maxParallelToolCalls: this.maxParallelToolCalls, setStatus: (status) => { this.setStatus(status) }, setAbort: controller => void (this.currentAbort = controller), disposed: this.disposed, @@ -342,6 +393,7 @@ export class ReactLoopAgent implements Agent { isCancelled: () => this.cancelRequested, cancelReason: () => this.cancelReason, clearCancel: () => { this.cancelRequested = false }, + withToolBatch: run => this.withToolBatch(run), // Pre-step cancellation re-parks without emitting a status transition. settleIdle: () => { this.settleIdleWaiters() }, }) diff --git a/packages/core/agent-loop/src/constants.ts b/packages/core/agent-loop/src/constants.ts new file mode 100644 index 0000000000..3f5510967a --- /dev/null +++ b/packages/core/agent-loop/src/constants.ts @@ -0,0 +1,6 @@ +/** Shared agent-loop scheduler defaults. + * @module dsh-agent-loop/constants + */ + +/** Default maximum in-flight parallel-safe calls per agent step. */ +export const DEFAULT_MAX_PARALLEL_TOOL_CALLS = 10 diff --git a/packages/core/agent-loop/src/index.ts b/packages/core/agent-loop/src/index.ts index a4d23671e7..5f5b9a9eb6 100644 --- a/packages/core/agent-loop/src/index.ts +++ b/packages/core/agent-loop/src/index.ts @@ -32,6 +32,7 @@ import { ReactLoopAgent, } from './agent.ts' import type { PreparedReactLoopAgent } from './agent.ts' +import { DEFAULT_MAX_PARALLEL_TOOL_CALLS } from './constants.ts' export { ReactLoopAgent } from './agent.ts' @@ -73,6 +74,15 @@ function signalAbortError(id: AgentId, signal: AbortSignal): Error { return new Error(`agent "${id}" creation aborted`, { cause: signal.reason }) } +/** Resolve the deployment-wide scheduler cap at the owning config boundary. */ +function resolveMaxParallelToolCalls(value: number | undefined): number { + const maxParallelToolCalls = value ?? DEFAULT_MAX_PARALLEL_TOOL_CALLS + if (!Number.isInteger(maxParallelToolCalls) || maxParallelToolCalls < 1) { + throw new Error('maxParallelToolCalls must be a positive integer') + } + return maxParallelToolCalls +} + /** * Caller-owned create/resume transaction through rollback-covered publication * and quiescent teardown. Resources remain private until the final registry @@ -163,13 +173,13 @@ class AgentCreationTransaction { } /** Construct the driver and scope, then install their complete ordered lifecycle. */ - prepare(options: AgentOptions, session: Session): ReactLoopAgent { + prepare(options: AgentOptions, session: Session, maxParallelToolCalls: number): ReactLoopAgent { this.assertActive() const gate = Promise.withResolvers() this.preparing = gate.promise try { this.session = session - const driver = prepareReactLoopAgent(this.loopCtx, this.id, options, session) + const driver = prepareReactLoopAgent(this.loopCtx, this.id, options, session, maxParallelToolCalls) this.driver = driver const agent = driver.agent const scope = createScope(this.loopCtx, agent) @@ -318,8 +328,15 @@ declare module 'cordis' { } } -/** Plugin configuration for declarative startup agents. */ +export { DEFAULT_MAX_PARALLEL_TOOL_CALLS } + +/** Agent-loop plugin configuration. */ export interface Config { + /** + * Maximum parallel-safe calls in flight per agent step. `1` is serial; + * omission defaults to {@link DEFAULT_MAX_PARALLEL_TOOL_CALLS}. + */ + maxParallelToolCalls?: number /** Agents created or resumed at plugin startup. */ agents: (AgentOptions & { /** Registry identity for the live agent. */ @@ -337,6 +354,7 @@ export class AgentLoop extends Service implements AgentFactory { /** Runtime schema for declarative agents. */ static Config = z.object({ + maxParallelToolCalls: z.number().step(1).min(1).default(DEFAULT_MAX_PARALLEL_TOOL_CALLS), agents: z.array(z.object({ id: z.string().required(), provider: z.string(), @@ -347,11 +365,14 @@ export class AgentLoop extends Service implements AgentFactory { }) as unknown as z private readonly ownership: FactoryOwnership + /** Resolved concurrency cap for every driver created by this factory. */ + private readonly maxParallelToolCalls: number /** Plain holder prevents Cordis from re-tracing the factory's dependency context through a caller shadow. */ private readonly runtime: { ctx: Context } constructor(ctx: Context, public config: Config) { super(ctx, 'agentLoop') + this.maxParallelToolCalls = resolveMaxParallelToolCalls(config.maxParallelToolCalls) this.ownership = new FactoryOwnership(ctx.fiber) this.runtime = { ctx } ctx.effect(() => () => this.ownership.dispose(), 'agentLoop.transactions()') @@ -394,7 +415,7 @@ export class AgentLoop extends Service implements AgentFactory { try { const sessionId = SessionId(`${id}-session-${randomUUID()}`) const session = loopCtx.sessions.prepare(sessionId, { meta }) - const agent = transaction.prepare(options, session) + const agent = transaction.prepare(options, session, this.maxParallelToolCalls) transaction.publish('startup') return agent } catch (error: unknown) { @@ -412,6 +433,7 @@ export class AgentLoop extends Service implements AgentFactory { * @returns the published handle. */ async createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise { + const agentOptions = options.agentOptions ?? {} const transaction = new AgentCreationTransaction( this.runtime.ctx, ownerCtx, @@ -424,7 +446,7 @@ export class AgentLoop extends Service implements AgentFactory { ...options.seed === undefined ? {} : { seed: options.seed }, ...options.meta === undefined ? {} : { meta: options.meta }, }) - const agent = transaction.prepare(options.agentOptions ?? {}, session) + const agent = transaction.prepare(agentOptions, session, this.maxParallelToolCalls) await transaction.waitFor(options.setup?.(agent.ctx)) transaction.assertActive() return transaction.publish('startup') @@ -456,6 +478,7 @@ export class AgentLoop extends Service implements AgentFactory { persistence: SessionPersistence, options: ResumeAgentOptions, ): Promise { + const agentOptions = options.agentOptions ?? {} const transaction = new AgentCreationTransaction( this.runtime.ctx, ownerCtx, @@ -475,7 +498,7 @@ export class AgentLoop extends Service implements AgentFactory { ...loaded.meta.seedLength === undefined ? {} : { seedLength: loaded.meta.seedLength }, }, }) - const agent = transaction.prepare(options.agentOptions ?? {}, session) + const agent = transaction.prepare(agentOptions, session, this.maxParallelToolCalls) await transaction.waitFor(options.setup?.(agent.ctx)) transaction.assertActive() return transaction.publish('resume') diff --git a/packages/core/agent-loop/src/loop.ts b/packages/core/agent-loop/src/loop.ts index a4427c5311..a153eba7e4 100644 --- a/packages/core/agent-loop/src/loop.ts +++ b/packages/core/agent-loop/src/loop.ts @@ -18,6 +18,7 @@ import type { TransmissionLog } from './request-log.ts' import { renderPrompt } from '@deepseek-ai/dsh-system-prompt' import type { PromptAssembly } from '@deepseek-ai/dsh-system-prompt' import type {} from '@deepseek-ai/dsh-tools' +import { executeToolCalls } from './tool-calls.ts' import type { ReactLoopAgent } from './agent.ts' import type { Inbox } from './inbox.ts' @@ -73,6 +74,8 @@ function stepFinishReason(finish: FinishReason): TurnEndReason | undefined { export interface LoopHandle { /** Native-private agent inbox handed to the driver only at internal startup. */ readonly inbox: Inbox + /** Maximum parallel-safe calls allowed in one step. */ + readonly maxParallelToolCalls: number setStatus(status: 'idle' | 'running'): void setAbort(controller: AbortController | undefined): void /** Resolves when the agent is disposed — unblocks the idle wait. */ @@ -86,6 +89,8 @@ export interface LoopHandle { clearCancel(): void /** Settle idle waiters when pre-running cancellation skips a turn, without emitting `agent/status`. */ settleIdle(): void + /** Run an active tool-call batch, accepting post-tool context into the FIFO drained before settlement. */ + readonly withToolBatch: (run: (acceptContext: (context: HookContext) => void) => Promise) => Promise } /** @@ -331,7 +336,7 @@ async function runTurn( let stepOutcome: { hadToolCalls: boolean; finish: FinishReason } | { error: Error } try { stepOutcome = await runStep( - ctx, events, agent, turn, step, assembly, fullSystemPrompt, boundaryMessages, transmission, abort.signal) + ctx, events, agent, handle, turn, step, assembly, fullSystemPrompt, boundaryMessages, transmission, abort.signal) } catch (error: unknown) { stepOutcome = { error: toError(error) } } finally { @@ -468,6 +473,7 @@ async function runStep( ctx: Context, events: AgentEventDispatch, agent: ReactLoopAgent, + handle: LoopHandle, turn: number, step: number, assembly: PromptAssembly, @@ -556,58 +562,15 @@ async function runStep( // empty chunk provenance for a contentless, usage-less provider response. recordAssistantMessage(session, turn, step, header.config, assembledContent, message, assembler, chunkSeqs) - // Tool execution stays sequential; recheck abort around each normalized result. + // Dispatch may overlap; policy, durable results, and result context stay model-ordered. const toolCalls = message.content.filter(block => block.type === 'tool-call') - // Buffer context until all results are appended to preserve call/result adjacency. - const pendingContext: HookContext[] = [] - for (const call of toolCalls) { - /* v8 ignore next -- signal.reason always set: cancel()/disposal provide a default */ - if (signal.aborted) throw new Error(String(signal.reason ?? 'aborted')) - const callEvent = session.append('tool/call', { turn, step, callId: call.id, name: call.name, arguments: call.arguments }) - let parsedArguments: unknown - try { - parsedArguments = call.arguments ? JSON.parse(call.arguments) : {} - } catch { - parsedArguments = call.arguments - } - // TODO(pre-tool-input-rewrite): Keep logged history and live presentation aligned; - // see docs/rfc/proposed/feature/2026-06-30-pre-tool-input-rewrite.md. - const result = await ctx.tools.execute({ - callId: call.id, - name: call.name, - arguments: parsedArguments, - agent, - signal, - }) - session.append('tool/result', { - turn, step, - // Correlation comes from the immutable execution input; the result does - // not duplicate this authoritative transcript identity. - callId: call.id, - content: result.content, - isError: result.isError, - ...result.error ? { error: result.error } : {}, - // Persist tool-owned presentation data for replay. - ...result.meta !== undefined ? { meta: result.meta } : {}, - }, { surfaceOp: 'append', sourceEventSeqs: [callEvent.seq] }) - pendingContext.push(...result.additionalContexts ?? []) - // The signal may flip while the tool is awaited. - /* v8 ignore start -- signal.reason default unreachable: cancel()/disposal always set it */ - // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition - if (signal.aborted) throw new Error(String(signal.reason ?? 'aborted')) - /* v8 ignore stop */ - } - - // Append buffered context after the complete result batch. - for (const context of pendingContext) { - agent.inject(context.content, { - source: context.source, - ...context.envelope !== undefined ? { envelope: context.envelope } : {}, - ...context.meta !== undefined ? { meta: context.meta } : {}, - }) - } - - return { hadToolCalls: toolCalls.length > 0, finish: assembler.finish } + if (toolCalls.length === 0) return { hadToolCalls: false, finish: assembler.finish } + return handle.withToolBatch(async (acceptContext) => { + await executeToolCalls( + ctx, agent, turn, step, toolCalls, signal, handle.maxParallelToolCalls, acceptContext, + ) + return { hadToolCalls: true, finish: assembler.finish } + }) } /** Preserve successful-call accounting without retaining output that result processing rejected. */ diff --git a/packages/core/agent-loop/src/tool-calls.ts b/packages/core/agent-loop/src/tool-calls.ts new file mode 100644 index 0000000000..3f3581c70a --- /dev/null +++ b/packages/core/agent-loop/src/tool-calls.ts @@ -0,0 +1,229 @@ +/** + * Schedules one assistant step's tool calls. Exclusive calls form barriers; + * parallel calls use a bounded rolling pool and are reclassified before start. + * Dispatch may overlap, while policy, results, and result context remain + * model-ordered. Abort stops replenishment and drains started calls. + * + * Each started call records `tool/call`; `tool/result` commits in model order, + * preserving derived history when audit events interleave with earlier results. + * @module dsh-agent-loop/tool-calls + */ + +import type { Context } from 'cordis' +import { assertNever, type ToolCallBlock } from '@deepseek-ai/dsh-llm' +import type { HookContext } from '@deepseek-ai/dsh-agent' +import type { Session } from '@deepseek-ai/dsh-session' +import { TOOL_REGISTRY_SCHEDULER, type ToolExecutionInput, type ToolExecutionMode, type ToolExecutionResult, type ToolRunContext } from '@deepseek-ai/dsh-tools' +import type { ReactLoopAgent } from './agent.ts' + +/** One tool call after argument parsing, ready to schedule. */ +interface PlannedCall { + block: ToolCallBlock + exec: ToolExecutionInput +} + +/** Settled dispatch awaiting model-order finalization. */ +interface Slot { + exec: ToolRunContext + result: ToolExecutionResult + needsPost: boolean +} + +/** + * Schedule one assistant step's tool calls by their live concurrency mode. + * Started calls receive ordered results. Abort drains them and rethrows after + * accepting their context into the batch FIFO owned by the caller. + * + * @param ctx - loop context that owns the tool registry. + * @param agent - agent and session receiving the call lifecycle. + * @param turn - current turn number. + * @param step - current step number. + * @param toolCalls - assistant calls in model order. + * @param signal - abort signal shared by the step. + * @param maxParallel - validated in-flight cap. + * @param acceptContext - accepts committed result context into the active batch. + */ +export async function executeToolCalls( + ctx: Context, + agent: ReactLoopAgent, + turn: number, + step: number, + toolCalls: ToolCallBlock[], + signal: AbortSignal, + maxParallel: number, + acceptContext: (context: HookContext) => void, +): Promise { + const { session } = agent + + // Inputs are distinct because tools/execute wrappers may replace `exec.signal`. + const planned: PlannedCall[] = toolCalls.map(block => ({ + block, + exec: { + callId: block.id, + name: block.name, + arguments: parseArguments(block.arguments), + agent, + signal, + }, + })) + + let next = 0 + while (next < planned.length) { + // Commit before classifying again so registry changes affect unstarted calls. + // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- bounded by the loop condition + const first = planned[next]! + const mode = ctx.tools.executionMode(first.exec).kind + const group = mode === 'parallel' ? planned.slice(next) : [first] + next += await runGroup(ctx, session, turn, step, group, mode, signal, maxParallel, acceptContext) + } +} + +/** Parse model arguments, preserving invalid JSON as text and mapping empty input to `{}`. */ +function parseArguments(raw: string): unknown { + try { + return raw ? JSON.parse(raw) : {} + } catch { + return raw + } +} + +/** + * Run one exclusive barrier or parallel pool. Later calls are reclassified + * before start; an exclusive reclassification waits for the current pool to + * drain and remains for the caller's next barrier. Results and contexts commit + * in model order. Abort stops starts, drains and commits started calls, accepts + * their contexts into the owning batch, and throws. + */ +async function runGroup( + ctx: Context, + session: Session, + turn: number, + step: number, + group: PlannedCall[], + mode: ToolExecutionMode['kind'], + signal: AbortSignal, + maxParallel: number, + acceptContext: (context: HookContext) => void, +): Promise { + /* v8 ignore next -- signal.reason always set: cancel()/disposal provide a default */ + if (signal.aborted) throw new Error(String(signal.reason ?? 'aborted')) + const slots: (Slot | undefined)[] = group.map(() => undefined) + // Started slots retain their tool/call seq for result provenance. + const callSeqs: number[] = group.map(() => -1) + let nextToStart = 0 + let committed = 0 + let started = 0 + let aborted: boolean = signal.aborted + + // `committed` advances only across contiguous model-order slots. + const commitReady = async (): Promise => { + while (committed < group.length) { + const slot = slots[committed] + if (slot === undefined) break + const call = group[committed] + const result = slot.needsPost + ? await ctx.tools[TOOL_REGISTRY_SCHEDULER].finalize(slot.exec, slot.result) + : ctx.tools[TOOL_REGISTRY_SCHEDULER].finish(slot.exec, slot.result) + // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- bounded index + appendToolResult(session, turn, step, call!.block, result, callSeqs[committed]!) + for (const context of result.additionalContexts ?? []) acceptContext(context) + committed++ + } + } + + const inFlight = new Map>() + + const startCall = async (index: number): Promise => { + // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- bounded index + const call = group[index]! + callSeqs[index] = appendToolCall(session, turn, step, call.block) + started++ + const prepared = await ctx.tools[TOOL_REGISTRY_SCHEDULER].prepare(call.exec) + switch (prepared.kind) { + case 'dispatch': { + const promise = ctx.tools[TOOL_REGISTRY_SCHEDULER].dispatch(prepared.exec).then((outcome) => { + slots[index] = { exec: prepared.exec, result: outcome.result, needsPost: outcome.kind === 'post-result' } + return index + }) + inFlight.set(index, promise) + break + } + case 'post-result': + slots[index] = { exec: prepared.exec, result: prepared.result, needsPost: true } + break + case 'final-result': + slots[index] = { exec: prepared.exec, result: prepared.result, needsPost: false } + break + /* v8 ignore next -- closed-union exhaustiveness guard */ + default: + assertNever(prepared, 'tool-call scheduler prepare result') + } + } + + const fillPool = async (): Promise => { + while (!aborted && nextToStart < group.length && inFlight.size < maxParallel) { + // Re-read later modes after ordered commits so registry changes can create a barrier. + // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- bounded by the loop condition + const nextCall = group[nextToStart]! + if (nextToStart > 0 && mode === 'parallel' + && ctx.tools.executionMode(nextCall.exec).kind !== 'parallel') break + await startCall(nextToStart) + nextToStart++ + await commitReady() + // Abort may arrive while pre-execute awaits. + if (signal.aborted) aborted = true + } + } + + // Ordered pre-execute may await; only dispatch/body overlaps. + // TODO: Drain every started call before rethrowing a scheduler error; tool + // bodies must not outlive the failed turn. + await fillPool() + while (inFlight.size > 0) { + const settledIndex = await Promise.race(inFlight.values()) + inFlight.delete(settledIndex) + await commitReady() + // Abort may arrive while a tool or ordered commit awaits. + // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition + if (signal.aborted) aborted = true + await fillPool() + } + + if (aborted) { + // Started calls and accepted context settle before the turn records the abort. + /* v8 ignore next -- signal.reason always set: cancel()/disposal provide a default */ + throw new Error(String(signal.reason ?? 'aborted')) + } + /* v8 ignore next -- unreachable: a non-aborted group commits every started call */ + if (committed !== started) throw new Error('tool-call scheduler: uncommitted settled calls') + return started +} + +/** Append a started call and return its provenance sequence. */ +function appendToolCall(session: Session, turn: number, step: number, block: ToolCallBlock): number { + const event = session.append('tool/call', { turn, step, callId: block.id, name: block.name, arguments: block.arguments }) + return event.seq +} + +/** Append a model-ordered result linked to its call event. */ +function appendToolResult( + session: Session, + turn: number, + step: number, + block: ToolCallBlock, + result: ToolExecutionResult, + callSeq: number, +): void { + session.append('tool/result', { + turn, step, + // Correlation stays with the loop's authoritative model-transcript call id; + // registry results deliberately do not duplicate it. + callId: block.id, + content: result.content, + isError: result.isError, + ...result.error ? { error: result.error } : {}, + // The tool's private presentation payload (e.g. a result-time diff), + // persisted so a UI bridge reproduces the card on replay. + ...result.meta !== undefined ? { meta: result.meta } : {}, + }, { surfaceOp: 'append', sourceEventSeqs: [callSeq] }) +} diff --git a/packages/core/agent-loop/tests/agent.spec.ts b/packages/core/agent-loop/tests/agent.spec.ts index 70c596cd10..8c2a550b12 100644 --- a/packages/core/agent-loop/tests/agent.spec.ts +++ b/packages/core/agent-loop/tests/agent.spec.ts @@ -6,7 +6,7 @@ import SessionStore, { SessionId } from '@deepseek-ai/dsh-session' import SystemPrompt from '@deepseek-ai/dsh-system-prompt' import ToolRegistry from '@deepseek-ai/dsh-tools' import AgentRegistry from '@deepseek-ai/dsh-agent' -import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop' +import AgentLoop, { DEFAULT_MAX_PARALLEL_TOOL_CALLS, ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop' import { bindReactLoopAgentContext, prepareReactLoopAgent } from '../src/agent.ts' import { MockAdapter, textResponse } from './mock-adapter.ts' @@ -53,10 +53,14 @@ describe('ReactLoopAgent', () => { const ctx = new Context() await ctx.plugin(SessionStore) const session = ctx.sessions.create(SessionId('exclusive-driver')) - const prepared = prepareReactLoopAgent(ctx, AgentId('first-driver'), { provider: 'mock', model: 'mock' }, session) + const prepared = prepareReactLoopAgent( + ctx, AgentId('first-driver'), { provider: 'mock', model: 'mock' }, session, DEFAULT_MAX_PARALLEL_TOOL_CALLS, + ) expect(() => prepared.agent.ctx).toThrow('context is not bound') - expect(() => prepareReactLoopAgent(ctx, AgentId('second-driver'), { provider: 'mock', model: 'mock' }, session)) + expect(() => prepareReactLoopAgent( + ctx, AgentId('second-driver'), { provider: 'mock', model: 'mock' }, session, DEFAULT_MAX_PARALLEL_TOOL_CALLS, + )) .toThrow('already has a concrete agent driver') await prepared.dispose() @@ -254,7 +258,9 @@ describe('ReactLoopAgent', () => { const ctx = new Context() await ctx.plugin(SessionStore) const session = ctx.sessions.create(SessionId('test')) - const prepared = prepareReactLoopAgent(ctx, AgentId('bare'), { provider: 'mock', model: 'mock' }, session) + const prepared = prepareReactLoopAgent( + ctx, AgentId('bare'), { provider: 'mock', model: 'mock' }, session, DEFAULT_MAX_PARALLEL_TOOL_CALLS, + ) const { agent } = prepared prepared.markPublished() @@ -272,7 +278,9 @@ describe('ReactLoopAgent', () => { const ctx = new Context() await ctx.plugin(SessionStore) const session = ctx.sessions.create(SessionId('pre-start-dispose')) - const prepared = prepareReactLoopAgent(ctx, AgentId('pre-start-dispose'), { provider: 'mock', model: 'mock' }, session) + const prepared = prepareReactLoopAgent( + ctx, AgentId('pre-start-dispose'), { provider: 'mock', model: 'mock' }, session, DEFAULT_MAX_PARALLEL_TOOL_CALLS, + ) await prepared.dispose() expect(prepared.agent.status).toBe('disposed') @@ -369,7 +377,9 @@ describe('ReactLoopAgent', () => { const adapter = new MockAdapter(['hang']) ctx.llm.registerAdapter(['mock'], adapter) const session = ctx.sessions.create(SessionId('bare')) - const prepared = prepareReactLoopAgent(ctx, AgentId('bare'), { provider: 'mock', model: 'mock' }, session) + const prepared = prepareReactLoopAgent( + ctx, AgentId('bare'), { provider: 'mock', model: 'mock' }, session, DEFAULT_MAX_PARALLEL_TOOL_CALLS, + ) const { agent } = prepared prepared.markPublished() const dispose = prepared.startDriver() diff --git a/packages/core/agent-loop/tests/contract-regressions.spec.ts b/packages/core/agent-loop/tests/contract-regressions.spec.ts index 43fb30ec29..12460039b1 100644 --- a/packages/core/agent-loop/tests/contract-regressions.spec.ts +++ b/packages/core/agent-loop/tests/contract-regressions.spec.ts @@ -3,9 +3,9 @@ import { Context } from 'cordis' import LlmService, { CallId, ContentBlock, MessageSource, StreamChunk } from '@deepseek-ai/dsh-llm' import SessionStore, { Session, SessionEvent, SessionId, TurnEndReason } from '@deepseek-ai/dsh-session' import SystemPrompt from '@deepseek-ai/dsh-system-prompt' -import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools' +import ToolRegistry, { defineTool, type PostToolDecision } from '@deepseek-ai/dsh-tools' import AgentRegistry, { AgentId, type ContinuationDecision } from '@deepseek-ai/dsh-agent' -import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop' +import AgentLoop, { DEFAULT_MAX_PARALLEL_TOOL_CALLS, ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop' import { prepareReactLoopAgent } from '../src/agent.ts' import * as Invariants from '@deepseek-ai/dsh-invariants' import { maxTokensResponse, MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts' @@ -249,6 +249,190 @@ describe('abort during tool execution ends the turn', () => { expect(adapter.requests).toHaveLength(1) // no follow-up model call expect(reasons).toEqual([{ kind: 'aborted', reason: 'user interrupt' }]) }) + + it('records context accepted before a tool-step abort in the same turn', async () => { + const adapter = new MockAdapter([toolCallResponse('c1', 'aborter', {})]) + const ctx = await harness(adapter) + const agent = ctx.agentLoop.create(AgentId('a-abort-injection'), { provider: 'mock', model: 'mock' }) + ctx.tools.register(defineTool({ + name: 'aborter', + description: '', + parameters: {}, + async execute() { + agent.inject([{ type: 'text', text: 'accepted before abort' }], { source: { kind: 'plugin', plugin: 'test' } }) + ;(agent as unknown as { currentAbort?: AbortController }).currentAbort?.abort('user interrupt') + return [{ type: 'text', text: 'done' }] + }, + })) + ctx.on('tools/post-execute', async (): Promise => ({ + kind: 'accept', + additionalContexts: [{ + content: [{ type: 'text', text: 'accepted result context after abort' }], + source: { kind: 'plugin', plugin: 'test' }, + }], + })) + + send(agent, 'go') + await waitForIdle(ctx, agent) + + const events = [...agent.session.events] + expect(events + .filter(event => event.type === 'tool/result' || event.type === 'context/message' + || event.type === 'step/end' || event.type === 'turn/end') + .map(event => event.type)) + .toEqual(['tool/result', 'context/message', 'context/message', 'step/end', 'turn/end']) + expect(events + .filter(event => event.type === 'context/message') + .map(event => event.data.content)) + .toEqual([ + [{ type: 'text', text: 'accepted before abort' }], + [{ type: 'text', text: 'accepted result context after abort' }], + ]) + }) + + it('records post-tool context when a later call aborts the batch', async () => { + const adapter = new MockAdapter([[ + { type: 'block-start', index: 0, blockType: 'tool-call' }, + { type: 'block-end', index: 0, block: { type: 'tool-call', id: CallId('c1'), name: 'first', arguments: '{}' } }, + { type: 'block-start', index: 1, blockType: 'tool-call' }, + { type: 'block-end', index: 1, block: { type: 'tool-call', id: CallId('c2'), name: 'aborter', arguments: '{}' } }, + { type: 'finish', reason: { kind: 'tool-calls' } }, + ] satisfies StreamChunk[]]) + const ctx = await harness(adapter) + const agent = ctx.agentLoop.create(AgentId('a-later-abort-context'), { provider: 'mock', model: 'mock' }) + ctx.tools.register(defineTool({ + name: 'first', + description: '', + parameters: {}, + async execute() { + return [{ type: 'text', text: 'first done' }] + }, + })) + ctx.tools.register(defineTool({ + name: 'aborter', + description: '', + parameters: {}, + async execute() { + ;(agent as unknown as { currentAbort?: AbortController }).currentAbort?.abort('user interrupt') + return [{ type: 'text', text: 'aborted' }] + }, + })) + ctx.on('tools/post-execute', async (exec, _result, next): Promise => { + if (exec.callId !== CallId('c1')) return next() + return { + kind: 'accept', + additionalContexts: [{ + content: [{ type: 'text', text: 'accepted after first result' }], + source: { kind: 'plugin', plugin: 'test' }, + }], + } + }) + + send(agent, 'go') + await waitForIdle(ctx, agent) + + const events = [...agent.session.events] + expect(events + .filter(event => event.type === 'tool/result' || event.type === 'context/message' + || event.type === 'step/end' || event.type === 'turn/end') + .map(event => event.type)) + .toEqual(['tool/result', 'tool/result', 'context/message', 'step/end', 'turn/end']) + expect(events.find(event => event.type === 'context/message')?.data.content) + .toEqual([{ type: 'text', text: 'accepted after first result' }]) + }) + + it('drains deferred context before disposal reaches quiescence', async () => { + const adapter = new MockAdapter([toolCallResponse('c1', 'waiter', {})]) + const ctx = await harness(adapter) + const started = Promise.withResolvers() + let agent!: ReactLoopAgent + const fiber = await ctx.plugin(Object.assign((inner: Context) => { + agent = inner.agentLoop.create(AgentId('a-dispose-injection'), { provider: 'mock', model: 'mock' }) + }, { inject: ['agentLoop'] })) + ctx.tools.register(defineTool({ + name: 'waiter', + description: '', + parameters: {}, + async execute(_args, exec) { + agent.inject([{ type: 'text', text: 'accepted before disposal' }], { source: { kind: 'plugin', plugin: 'test' } }) + started.resolve(undefined) + const signal = exec.signal + if (!signal) throw new Error('tool execution signal is missing') + await new Promise((resolve) => { + if (signal.aborted) resolve() + else signal.addEventListener('abort', () => { resolve() }, { once: true }) + }) + return [{ type: 'text', text: 'done' }] + }, + })) + ctx.on('tools/post-execute', async (): Promise => ({ + kind: 'accept', + additionalContexts: [{ + content: [{ type: 'text', text: 'accepted result context during disposal' }], + source: { kind: 'plugin', plugin: 'test' }, + }], + })) + + send(agent, 'go') + await started.promise + await fiber.dispose() + + expect(agent.session.events + .filter(event => event.type === 'context/message') + .map(event => event.data.content)) + .toEqual([ + [{ type: 'text', text: 'accepted before disposal' }], + [{ type: 'text', text: 'accepted result context during disposal' }], + ]) + expect(agent.session.events.find(event => event.type === 'turn/end')?.data.reason) + .toEqual({ kind: 'disposed' }) + }) + + it('limits injection deferral to the current tool batch', async () => { + const adapter = new MockAdapter([ + [ + { type: 'block-start', index: 0, blockType: 'tool-call' }, + { type: 'block-end', index: 0, block: { type: 'tool-call', id: CallId('c1'), name: 'aborter', arguments: '{}' } }, + { type: 'block-start', index: 1, blockType: 'tool-call' }, + { type: 'block-end', index: 1, block: { type: 'tool-call', id: CallId('c2'), name: 'second', arguments: '{}' } }, + { type: 'finish', reason: { kind: 'tool-calls' } }, + ] satisfies StreamChunk[], + textResponse('later turn'), + ]) + const ctx = await harness(adapter) + const agent = ctx.agentLoop.create(AgentId('a-historical-tool-pair'), { provider: 'mock', model: 'mock' }) + ctx.tools.register(defineTool({ + name: 'aborter', + description: '', + parameters: {}, + async execute() { + ;(agent as unknown as { currentAbort?: AbortController }).currentAbort?.abort('user interrupt') + return [{ type: 'text', text: 'done' }] + }, + })) + ctx.tools.register(defineTool({ + name: 'second', + description: '', + parameters: {}, + async execute() { + return [{ type: 'text', text: 'must not run' }] + }, + })) + + send(agent, 'leave an unmatched historical call') + await waitForIdle(ctx, agent) + ctx.on('agent/pre-step', (subject, turn) => { + if (subject === agent && turn === 2) { + agent.inject([{ type: 'text', text: 'new turn context' }], { source: { kind: 'plugin', plugin: 'test' } }) + } + }) + send(agent, 'start a text-only turn') + await waitForIdle(ctx, agent) + + expect(agent.session.events.find(event => event.type === 'context/message')?.data.content) + .toEqual([{ type: 'text', text: 'new turn context' }]) + expect(JSON.stringify(adapter.requests[1]?.messages)).toContain('new turn context') + }) }) describe('steering from late extension points is never stranded', () => { @@ -638,7 +822,9 @@ describe('turn numbering continues across seeded sessions', () => { ctx2.llm.registerAdapter(['mock'], second) const seeded = ctx2.sessions.create(SessionId('forked'), { seed: [...agent.session.events] }) - const prepared = prepareReactLoopAgent(ctx2, AgentId('forked-agent'), { provider: 'mock', model: 'mock' }, seeded) + const prepared = prepareReactLoopAgent( + ctx2, AgentId('forked-agent'), { provider: 'mock', model: 'mock' }, seeded, DEFAULT_MAX_PARALLEL_TOOL_CALLS, + ) const forked = prepared.agent prepared.markPublished() ctx2.effect(() => prepared.startDriver()) diff --git a/packages/core/agent-loop/tests/loop.spec.ts b/packages/core/agent-loop/tests/loop.spec.ts index f3d58c4a6c..6f4f15ba0c 100644 --- a/packages/core/agent-loop/tests/loop.spec.ts +++ b/packages/core/agent-loop/tests/loop.spec.ts @@ -410,22 +410,30 @@ describe('agent loop', () => { expect(requestText).not.toContain(' { + it('defers inject() during tool execution until after the tool result', async () => { const adapter = new MockAdapter([ toolCallResponse('c1', 'noticer', {}, 'calling'), textResponse('done'), ]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' }) - // A tool that injects mid-execution: at this point the agent is running, so - // inject must append the context/message into the ALREADY-open turn rather - // than wrap it in its own one-shot turn. + let visibleDuringTool = false + const meta = { kind: 'deferred-test', version: 1 } ctx.tools.register(defineTool({ name: 'noticer', description: 'injects a notice', parameters: {}, async execute() { - agent.inject([{ type: 'text', text: 'mid-turn notice' }], { source: { kind: 'plugin', plugin: 'x' } }) + await Promise.resolve() + const first = { type: 'text' as const, text: 'mid-turn notice' } + agent.inject([first], { + source: { kind: 'plugin', plugin: 'x' }, + envelope: 'raw', + meta, + }) + first.text = 'mutated after inject' + agent.inject([{ type: 'text', text: 'second notice' }], { source: { kind: 'plugin', plugin: 'x' } }) + visibleDuringTool = agent.session.events.some(e => e.type === 'context/message') return [{ type: 'text', text: 'ok' }] }, })) @@ -433,13 +441,67 @@ describe('agent loop', () => { send(agent, 'go') await waitForIdle(ctx, agent) - // Exactly ONE turn ran (no synthetic injection turn), and the mid-turn - // context/message sits inside it. + expect(visibleDuringTool).toBe(false) + + // The injection stays in the open turn, but its user-role context cannot + // split the assistant tool call from the provider's tool-result message. const turnStarts = agent.session.events.filter(e => e.type === 'turn/start') expect(turnStarts).toHaveLength(1) const ts0 = turnStarts[0]! expect(ts0.type === 'turn/start' && ts0.data.trigger.kind).toBe('message') - expect(agent.session.events.some(e => e.type === 'context/message')).toBe(true) + const result = agent.session.events.find(e => e.type === 'tool/result')! + const contexts = agent.session.events.filter(e => e.type === 'context/message') + expect(contexts).toHaveLength(2) + expect(result.seq).toBeLessThan(contexts[0]!.seq) + expect(contexts[0]?.type === 'context/message' && contexts[0].data).toMatchObject({ + envelope: 'raw', + meta, + }) + expect(contexts.flatMap(event => event.type === 'context/message' ? event.data.content : [])) + .toEqual([ + { type: 'text', text: 'mid-turn notice' }, + { type: 'text', text: 'second notice' }, + ]) + + const secondRequest = adapter.requests[1]!.messages + const resultIndex = secondRequest.findIndex(message => + message.content.some(block => block.type === 'tool-result')) + const contextIndexes = secondRequest.flatMap((message, index) => + message.content.some(block => block.type === 'text' + && (block.text.includes('mid-turn notice') || block.text.includes('second notice'))) + ? [index] + : []) + expect(resultIndex).toBeGreaterThanOrEqual(0) + expect(contextIndexes).toHaveLength(2) + expect(contextIndexes.every(index => index > resultIndex)).toBe(true) + }) + + it('rejects non-JSON context before it enters the active tool-batch FIFO', async () => { + const adapter = new MockAdapter([ + toolCallResponse('c1', 'invalid-injector', {}, 'calling'), + textResponse('done'), + ]) + const ctx = await harness(adapter) + const agent = ctx.agentLoop.create(AgentId('invalid-context'), { provider: 'mock', model: 'mock' }) + ctx.tools.register(defineTool({ + name: 'invalid-injector', + description: 'attempts an invalid context injection', + parameters: {}, + async execute() { + expect(() => { + agent.inject([{ type: 'text', text: 'invalid' }], { + source: { kind: 'plugin', plugin: 'test' }, + meta: { bigint: 1n } as never, + }) + }).toThrow('agent context must be losslessly JSON-serializable') + return [{ type: 'text', text: 'rejected invalid context' }] + }, + })) + + send(agent, 'go') + await waitForIdle(ctx, agent) + + expect(agent.session.events.some(event => event.type === 'context/message')).toBe(false) }) it('agent/turn-continuation can force-continue (/loop pattern) and force-stop', async () => { diff --git a/packages/core/agent-loop/tests/tool-calls.spec.ts b/packages/core/agent-loop/tests/tool-calls.spec.ts new file mode 100644 index 0000000000..8feb20bd96 --- /dev/null +++ b/packages/core/agent-loop/tests/tool-calls.spec.ts @@ -0,0 +1,571 @@ +/** + * Exercises scheduler ordering and cancellation with deterministic gated tools. + * ACP goldens own transcript-facing coverage. + */ + +import { describe, expect, it } from 'vitest' +import { Context } from 'cordis' +import { CallId, StreamChunk } from '@deepseek-ai/dsh-llm' +import SessionStore, { SessionEvent } from '@deepseek-ai/dsh-session' +import SystemPrompt from '@deepseek-ai/dsh-system-prompt' +import LlmService from '@deepseek-ai/dsh-llm' +import ToolRegistry, { defineTool, type PostToolDecision, type PreToolDecision } from '@deepseek-ai/dsh-tools' +import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent' +import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop' +import { MockAdapter, textResponse } from './mock-adapter.ts' + +async function harness(adapter: MockAdapter, maxParallelToolCalls?: number) { + const ctx = new Context() + await ctx.plugin(LlmService) + await ctx.plugin(SessionStore) + await ctx.plugin(SystemPrompt, { persona: '' }) + await ctx.plugin(ToolRegistry) + await ctx.plugin(AgentRegistry) + await ctx.plugin(AgentLoop, { + agents: [], + ...maxParallelToolCalls === undefined ? {} : { maxParallelToolCalls }, + }) + ctx.llm.registerAdapter(['mock'], adapter) + return ctx +} + +function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise { + return new Promise((resolve) => { + const dispose = ctx.on('agent/status', (subject, status) => { + if (subject === agent && status === 'idle') { dispose(); resolve() } + }) + }) +} + +function events(agent: ReactLoopAgent): SessionEvent[] { + return [...agent.session.events] +} + +/** Build one assistant response containing the supplied tool calls. */ +function multiCall(calls: { id: string; name: string; args: object }[]): StreamChunk[] { + const chunks: StreamChunk[] = [] + calls.forEach((call, index) => { + chunks.push( + { type: 'block-start', index, blockType: 'tool-call' }, + { type: 'block-end', index, block: { type: 'tool-call', id: CallId(call.id), name: call.name, arguments: JSON.stringify(call.args) } }, + ) + }) + chunks.push( + { type: 'usage', usage: { inputTokens: 5, outputTokens: 5 } }, + { type: 'finish', reason: { kind: 'tool-calls' } }, + ) + return chunks +} + +/** A tool whose calls block until the test releases them by callId. */ +function gatedTool(name: string, parallel: boolean) { + const gates = new Map void>() + const started: string[] = [] + const tool = defineTool({ + name, + description: `gated ${name}`, + parameters: { id: { type: 'string', required: true } }, + ...parallel ? { isConcurrencySafe: () => true } : {}, + async execute(args) { + started.push(args.id) + await new Promise((resolve) => { gates.set(args.id, resolve) }) + return [{ type: 'text', text: `done-${args.id}` }] + }, + }) + return { + tool, + started, + release(id: string) { gates.get(id)?.(); gates.delete(id) }, + pending() { return [...gates.keys()] }, + } +} + +function gatedParallelTool(name: string) { + return gatedTool(name, true) +} + +function gatedExclusiveTool(name: string) { + return gatedTool(name, false) +} + +/** Poll until `predicate` holds, letting microtasks/timers drain between checks. */ +async function until(predicate: () => boolean): Promise { + for (let i = 0; i < 1000 && !predicate(); i++) await new Promise(r => setTimeout(r, 0)) + if (!predicate()) throw new Error('until: condition never held') +} + +describe('tool-call scheduler: grouping and barriers', () => { + it('runs parallel-safe siblings concurrently (all start before any completes)', async () => { + const adapter = new MockAdapter([ + multiCall([{ id: 'c1', name: 'p', args: { id: '1' } }, { id: 'c2', name: 'p', args: { id: '2' } }, { id: 'c3', name: 'p', args: { id: '3' } }]), + textResponse('done'), + ]) + const ctx = await harness(adapter) + const gated = gatedParallelTool('p') + ctx.tools.register(gated.tool) + const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' }) + + agent.send([{ type: 'text', text: 'go' }]) + await until(() => gated.started.length === 3) + expect(gated.started).toEqual(['1', '2', '3']) + gated.release('1'); gated.release('2'); gated.release('3') + await waitForIdle(ctx, agent) + }) + + it('an exclusive call between two parallel-safe calls forms a barrier (3 groups)', async () => { + const order: string[] = [] + const adapter = new MockAdapter([ + multiCall([ + { id: 'c1', name: 'r', args: { id: 'A1' } }, + { id: 'c2', name: 'w', args: { id: 'A2' } }, + { id: 'c3', name: 'r', args: { id: 'A3' } }, + ]), + textResponse('done'), + ]) + const ctx = await harness(adapter) + ctx.tools.register(defineTool({ + name: 'r', description: 'read', parameters: { id: { type: 'string', required: true } }, + isConcurrencySafe: () => true, + async execute(args) { order.push(`r-start-${args.id}`); order.push(`r-end-${args.id}`); return [{ type: 'text', text: 'r' }] }, + })) + ctx.tools.register(defineTool({ + name: 'w', description: 'write', parameters: { id: { type: 'string', required: true } }, + async execute(args) { order.push(`w-${args.id}`); return [{ type: 'text', text: 'w' }] }, + })) + const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' }) + agent.send([{ type: 'text', text: 'go' }]) + await waitForIdle(ctx, agent) + + expect(order).toEqual(['r-start-A1', 'r-end-A1', 'w-A2', 'r-start-A3', 'r-end-A3']) + }) + + it('reclassifies pending calls after an exclusive barrier replaces their tool', async () => { + const adapter = new MockAdapter([ + multiCall([ + { id: 'c1', name: 'replace', args: { id: '0' } }, + { id: 'c2', name: 'x', args: { id: '1' } }, + { id: 'c3', name: 'x', args: { id: '2' } }, + ]), + textResponse('done'), + ]) + const ctx = await harness(adapter) + const replacement = gatedExclusiveTool('x') + const disposeSafe = ctx.tools.register(defineTool({ + name: 'x', + description: 'initially safe', + parameters: { id: { type: 'string', required: true } }, + isConcurrencySafe: () => true, + async execute(args) { return [{ type: 'text', text: `old-${args.id}` }] }, + })) + ctx.tools.register(defineTool({ + name: 'replace', + description: 'replace x', + parameters: { id: { type: 'string', required: true } }, + async execute() { + disposeSafe() + ctx.tools.register(replacement.tool) + return [{ type: 'text', text: 'replaced' }] + }, + })) + const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' }) + + agent.send([{ type: 'text', text: 'go' }]) + await until(() => replacement.started.length === 1) + await new Promise(r => setTimeout(r, 5)) + expect(replacement.started).toEqual(['1']) + replacement.release('1') + await until(() => replacement.started.length === 2) + expect(replacement.started).toEqual(['1', '2']) + replacement.release('2') + await waitForIdle(ctx, agent) + }) + + it('stops replenishing when a result observer makes the next call exclusive', async () => { + const adapter = new MockAdapter([ + multiCall([ + { id: 'c1', name: 'x', args: { id: '1' } }, + { id: 'c2', name: 'x', args: { id: '2' } }, + { id: 'c3', name: 'x', args: { id: '3' } }, + ]), + textResponse('done'), + ]) + const ctx = await harness(adapter, 2) + const initial = gatedParallelTool('x') + const replacement = gatedExclusiveTool('x') + const disposeInitial = ctx.tools.register(initial.tool) + ctx.on('tools/result', (exec) => { + if (exec.callId !== CallId('c1')) return + disposeInitial() + ctx.tools.register(replacement.tool) + }) + const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' }) + + agent.send([{ type: 'text', text: 'go' }]) + await until(() => initial.started.length === 2) + initial.release('1') + await until(() => events(agent).some(event => + event.type === 'tool/result' && event.data.callId === CallId('c1'))) + await new Promise(r => setTimeout(r, 5)) + expect(replacement.started).toEqual([]) + initial.release('2') + await until(() => replacement.started.length === 1) + expect(replacement.started).toEqual(['3']) + replacement.release('3') + await waitForIdle(ctx, agent) + }) +}) + +describe('tool-call scheduler: model-order results despite out-of-order settlement', () => { + it('commits tool/result in model order even when a later call settles first', async () => { + const adapter = new MockAdapter([ + multiCall([{ id: 'c1', name: 'p', args: { id: '1' } }, { id: 'c2', name: 'p', args: { id: '2' } }]), + textResponse('done'), + ]) + const ctx = await harness(adapter) + const gated = gatedParallelTool('p') + ctx.tools.register(gated.tool) + const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' }) + + agent.send([{ type: 'text', text: 'go' }]) + await until(() => gated.started.length === 2) + gated.release('2') + await new Promise(r => setTimeout(r, 5)) + const beforeFirst = events(agent).filter(e => e.type === 'tool/result') + expect(beforeFirst).toEqual([]) + gated.release('1') + await waitForIdle(ctx, agent) + + const results = events(agent).filter(e => e.type === 'tool/result') + expect(results.map(e => e.data.callId)).toEqual([CallId('c1'), CallId('c2')]) + }) + + it('derived history pairs calls in model order regardless of tool/call log interleaving', async () => { + const adapter = new MockAdapter([ + multiCall([{ id: 'c1', name: 'p', args: { id: '1' } }, { id: 'c2', name: 'p', args: { id: '2' } }]), + textResponse('done'), + ]) + const ctx = await harness(adapter) + const gated = gatedParallelTool('p') + ctx.tools.register(gated.tool) + const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' }) + agent.send([{ type: 'text', text: 'go' }]) + await until(() => gated.started.length === 2) + gated.release('2'); gated.release('1') + await waitForIdle(ctx, agent) + + const messages = agent.session.deriveMessages() + const toolResults = messages.flatMap(m => m.content.filter(b => b.type === 'tool-result')) + expect(toolResults.map(b => b.toolCallId)).toEqual([CallId('c1'), CallId('c2')]) + }) +}) + +describe('tool-call scheduler: rolling pool honors maxParallelToolCalls', () => { + it('rejects invalid global maxParallelToolCalls config at plugin load', async () => { + await expect(harness(new MockAdapter([]), 0)).rejects.toThrow() + await expect(harness(new MockAdapter([]), 1.5)).rejects.toThrow() + }) + + it('defensively rejects invalid caps when direct construction bypasses the config schema', () => { + expect(() => new AgentLoop(new Context(), { agents: [], maxParallelToolCalls: 0 })) + .toThrow('maxParallelToolCalls must be a positive integer') + expect(() => new AgentLoop(new Context(), { agents: [], maxParallelToolCalls: 1.5 })) + .toThrow('maxParallelToolCalls must be a positive integer') + }) + + it('defaults the cap when direct construction bypasses the config schema', async () => { + const ctx = new Context() + await ctx.plugin(LlmService) + await ctx.plugin(SessionStore) + await ctx.plugin(SystemPrompt, { persona: '' }) + await ctx.plugin(ToolRegistry) + await ctx.plugin(AgentRegistry) + + expect(() => new AgentLoop(ctx, { agents: [] })).not.toThrow() + await ctx.fiber.dispose() + }) + + it('starts at most the cap, replenishing as calls settle', async () => { + const adapter = new MockAdapter([ + multiCall([1, 2, 3, 4].map(n => ({ id: `c${n}`, name: 'p', args: { id: String(n) } }))), + textResponse('done'), + ]) + const ctx = await harness(adapter, 2) + const gated = gatedParallelTool('p') + ctx.tools.register(gated.tool) + const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' }) + + agent.send([{ type: 'text', text: 'go' }]) + await until(() => gated.started.length === 2) + await new Promise(r => setTimeout(r, 5)) + expect(gated.started).toEqual(['1', '2']) + gated.release('1') + await until(() => gated.started.length === 3) + expect(gated.started).toEqual(['1', '2', '3']) + expect(events(agent) + .filter(e => e.type === 'tool/call' || e.type === 'tool/result') + .map(e => `${e.type}:${String(e.data.callId)}`) + .slice(0, 4)) + .toEqual(['tool/call:c1', 'tool/call:c2', 'tool/result:c1', 'tool/call:c3']) + gated.release('2'); gated.release('3') + await until(() => gated.started.length === 4) + gated.release('4') + await waitForIdle(ctx, agent) + expect(events(agent).filter(e => e.type === 'tool/result').map(e => e.data.callId)) + .toEqual([CallId('c1'), CallId('c2'), CallId('c3'), CallId('c4')]) + }) + + it('maxParallelToolCalls: 1 is fully serial (no second start before the first settles)', async () => { + const adapter = new MockAdapter([ + multiCall([{ id: 'c1', name: 'p', args: { id: '1' } }, { id: 'c2', name: 'p', args: { id: '2' } }]), + textResponse('done'), + ]) + const ctx = await harness(adapter, 1) + const gated = gatedParallelTool('p') + ctx.tools.register(gated.tool) + const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' }) + agent.send([{ type: 'text', text: 'go' }]) + await until(() => gated.started.length === 1) + await new Promise(r => setTimeout(r, 5)) + expect(gated.started).toEqual(['1']) + gated.release('1') + await until(() => gated.started.length === 2) + gated.release('2') + await waitForIdle(ctx, agent) + }) + + it('applies the configured cap to every factory-created agent', async () => { + const adapter = new MockAdapter([ + multiCall([{ id: 'c1', name: 'p', args: { id: '1' } }, { id: 'c2', name: 'p', args: { id: '2' } }]), + textResponse('done'), + ]) + const ctx = new Context() + await ctx.plugin(LlmService) + await ctx.plugin(SessionStore) + await ctx.plugin(SystemPrompt, { persona: '' }) + await ctx.plugin(ToolRegistry) + await ctx.plugin(AgentRegistry) + await ctx.plugin(AgentLoop, { agents: [], maxParallelToolCalls: 1 }) + ctx.llm.registerAdapter(['mock'], adapter) + const gated = gatedParallelTool('p') + ctx.tools.register(gated.tool) + const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' }) + agent.send([{ type: 'text', text: 'go' }]) + await until(() => gated.started.length === 1) + await new Promise(r => setTimeout(r, 5)) + expect(gated.started).toEqual(['1']) + gated.release('1') + await until(() => gated.started.length === 2) + gated.release('2') + await waitForIdle(ctx, agent) + }) + +}) + +describe('tool-call scheduler: ordered middleware and additional contexts', () => { + it('tools/pre-execute and tools/post-execute observe model call order', async () => { + const adapter = new MockAdapter([ + multiCall([{ id: 'c1', name: 'p', args: { id: '1' } }, { id: 'c2', name: 'p', args: { id: '2' } }, { id: 'c3', name: 'p', args: { id: '3' } }]), + textResponse('done'), + ]) + const ctx = await harness(adapter) + const gated = gatedParallelTool('p') + ctx.tools.register(gated.tool) + const pre: string[] = [] + const post: string[] = [] + ctx.on('tools/pre-execute', async (exec, next): Promise => { pre.push(String(exec.callId)); return next() }) + ctx.on('tools/post-execute', async (exec, _result, next): Promise => { post.push(String(exec.callId)); return next() }) + const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' }) + + agent.send([{ type: 'text', text: 'go' }]) + await until(() => gated.started.length === 3) + gated.release('3'); gated.release('2'); gated.release('1') + await waitForIdle(ctx, agent) + + expect(pre).toEqual([CallId('c1'), CallId('c2'), CallId('c3')].map(String)) + expect(post).toEqual([CallId('c1'), CallId('c2'), CallId('c3')].map(String)) + }) + + it('injects additional contexts in model call order, not settlement order', async () => { + const adapter = new MockAdapter([ + multiCall([{ id: 'c1', name: 'p', args: { id: '1' } }, { id: 'c2', name: 'p', args: { id: '2' } }]), + textResponse('done'), + ]) + const ctx = await harness(adapter, 2) + const gated = gatedParallelTool('p') + ctx.tools.register(gated.tool) + ctx.on('tools/post-execute', async (exec, _result): Promise => + ({ kind: 'accept', additionalContexts: [{ content: [{ type: 'text', text: `ctx-${exec.callId}` }], source: { kind: 'plugin', plugin: 'p' } }] })) + const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' }) + + agent.send([{ type: 'text', text: 'go' }]) + await until(() => gated.started.length === 2) + gated.release('2'); gated.release('1') + await waitForIdle(ctx, agent) + + const log = events(agent) + const contextTexts = log.filter(e => e.type === 'context/message') + .map(e => (e.data.content[0] as { text: string }).text) + expect(contextTexts).toEqual(['ctx-c1', 'ctx-c2']) + const lastResult = log.findLastIndex(e => e.type === 'tool/result') + const firstContext = log.findIndex(e => e.type === 'context/message') + expect(lastResult).toBeLessThan(firstContext) + }) + + it('orders pre-execute denials and errors without dispatching them', async () => { + const adapter = new MockAdapter([ + multiCall([ + { id: 'c1', name: 'p', args: { id: '1' } }, + { id: 'c2', name: 'p', args: { id: '2' } }, + { id: 'c3', name: 'p', args: { id: '3' } }, + ]), + textResponse('done'), + ]) + const ctx = await harness(adapter) + const gated = gatedParallelTool('p') + ctx.tools.register(gated.tool) + const post: string[] = [] + ctx.on('tools/pre-execute', async (exec, next): Promise => { + if (exec.callId === CallId('c2')) return { kind: 'deny', reason: 'blocked by policy' } + if (exec.callId === CallId('c3')) throw new Error('pre exploded') + return next() + }) + ctx.on('tools/post-execute', async (exec, _result, next): Promise => { + post.push(String(exec.callId)) + return next() + }) + const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' }) + + agent.send([{ type: 'text', text: 'go' }]) + await until(() => gated.started.length === 1) + gated.release('1') + await waitForIdle(ctx, agent) + + expect(gated.started).toEqual(['1']) + expect(post).toEqual(['c1', 'c2']) + const results = events(agent).filter(e => e.type === 'tool/result') + expect(results.map(e => e.data.callId)).toEqual([CallId('c1'), CallId('c2'), CallId('c3')]) + expect((results[1]!.data.content[0] as { text: string }).text).toContain('blocked by policy') + expect((results[2]!.data.content[0] as { text: string }).text).toContain('pre exploded') + }) +}) + +describe('tool-call scheduler: abort handling', () => { + it('starts no calls when the signal is already aborted before a parallel group', async () => { + const adapter = new MockAdapter([ + multiCall([{ id: 'c1', name: 'p', args: { id: '1' } }, { id: 'c2', name: 'p', args: { id: '2' } }]), + textResponse('should never be requested'), + ]) + const ctx = await harness(adapter) + const gated = gatedParallelTool('p') + ctx.tools.register(gated.tool) + const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' }) + ctx.on('session/event', (session, event) => { + if (session === agent.session && event.type === 'assistant/message') { + ;(agent as unknown as { currentAbort?: AbortController }).currentAbort?.abort('already aborted') + } + }) + + agent.send([{ type: 'text', text: 'go' }]) + await waitForIdle(ctx, agent) + + expect(gated.started).toEqual([]) + expect(events(agent).filter(e => e.type === 'tool/call')).toEqual([]) + expect(events(agent).filter(e => e.type === 'tool/result')).toEqual([]) + }) + + it('stops starting siblings when abort fires during ordered pre-execute', async () => { + const adapter = new MockAdapter([ + multiCall([{ id: 'c1', name: 'p', args: { id: '1' } }, { id: 'c2', name: 'p', args: { id: '2' } }]), + textResponse('should never be requested'), + ]) + const ctx = await harness(adapter) + const gated = gatedParallelTool('p') + ctx.tools.register(gated.tool) + const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' }) + ctx.on('tools/pre-execute', async (exec, next): Promise => { + if (exec.callId === CallId('c1')) { + ;(agent as unknown as { currentAbort?: AbortController }).currentAbort?.abort('pre cancelled') + } + return next() + }) + + agent.send([{ type: 'text', text: 'go' }]) + await until(() => gated.started.length === 1) + await new Promise(r => setTimeout(r, 5)) + expect(gated.started).toEqual(['1']) + gated.release('1') + await waitForIdle(ctx, agent) + + expect(events(agent).filter(e => e.type === 'tool/call').map(e => e.data.callId)) + .toEqual([CallId('c1')]) + expect(events(agent).filter(e => e.type === 'tool/result').map(e => e.data.callId)) + .toEqual([CallId('c1')]) + }) + + it('stops replenishing after abort, commits started results, and drains accepted additional contexts', async () => { + const adapter = new MockAdapter([ + multiCall([1, 2, 3, 4].map(n => ({ id: `c${n}`, name: 'p', args: { id: String(n) } }))), + textResponse('should never be requested'), + ]) + const ctx = await harness(adapter, 2) + const gated = gatedParallelTool('p') + ctx.tools.register(gated.tool) + ctx.on('tools/post-execute', async (exec, _result, next): Promise => ({ + ...await next(), + additionalContexts: [{ content: [{ type: 'text', text: `ctx-${exec.callId}` }], source: { kind: 'plugin', plugin: 'p' } }], + })) + const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' }) + + agent.send([{ type: 'text', text: 'go' }]) + await until(() => gated.started.length === 2) + ;(agent as unknown as { currentAbort?: AbortController }).currentAbort?.abort('stop now') + gated.release('1') + gated.release('2') + await waitForIdle(ctx, agent) + + expect(gated.started).toEqual(['1', '2']) + expect(events(agent).filter(e => e.type === 'tool/call').map(e => e.data.callId)) + .toEqual([CallId('c1'), CallId('c2')]) + expect(events(agent).filter(e => e.type === 'tool/result').map(e => e.data.callId)) + .toEqual([CallId('c1'), CallId('c2')]) + const settled = events(agent).filter(e => e.type === 'tool/result' || e.type === 'context/message') + expect(settled.map(e => e.type)) + .toEqual(['tool/result', 'tool/result', 'context/message', 'context/message']) + expect(settled.filter(e => e.type === 'context/message') + .map(e => (e.data.content[0] as { text: string }).text)) + .toEqual(['ctx-c1', 'ctx-c2']) + }) + + it('does not run an exclusive barrier after a parallel group aborts', async () => { + const adapter = new MockAdapter([ + multiCall([ + { id: 'c1', name: 'p', args: { id: '1' } }, + { id: 'c2', name: 'p', args: { id: '2' } }, + { id: 'c3', name: 'x', args: { id: '3' } }, + ]), + textResponse('should never be requested'), + ]) + const ctx = await harness(adapter, 2) + const gated = gatedParallelTool('p') + const exclusive: string[] = [] + ctx.tools.register(gated.tool) + ctx.tools.register(defineTool({ + name: 'x', + description: 'exclusive', + parameters: { id: { type: 'string', required: true } }, + async execute(args) { exclusive.push(args.id); return [{ type: 'text', text: 'x' }] }, + })) + const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' }) + + agent.send([{ type: 'text', text: 'go' }]) + await until(() => gated.started.length === 2) + ;(agent as unknown as { currentAbort?: AbortController }).currentAbort?.abort('stop before barrier') + gated.release('1') + gated.release('2') + await waitForIdle(ctx, agent) + + expect(exclusive).toEqual([]) + expect(events(agent).filter(e => e.type === 'tool/call').map(e => e.data.callId)) + .toEqual([CallId('c1'), CallId('c2')]) + }) +}) diff --git a/packages/core/agent/README.md b/packages/core/agent/README.md index ca031995ef..1255731484 100644 --- a/packages/core/agent/README.md +++ b/packages/core/agent/README.md @@ -43,7 +43,7 @@ The handle every plugin programs against: - `agent.send(content, options?)` — queue a message; starts a turn when idle. Content and resolved source become one detached, deeply frozen lossless-JSON record before `agent/queued` and enqueue; invalid data throws synchronously, and caller or notification-listener in-place mutation cannot change the log or model input (`agent/prompt-submit` still rewrites by returning replacement content). - `agent.steer(content, options?)` — steer a running turn (inject between steps); uses the same owned acceptance boundary and behaves like `send` when idle -- `agent.inject(content, options?)` — inject in-session context (`context/message` event); the next request sees it. `options.envelope` defaults to the canonical `` framing and may be `'raw'` when the caller owns a complete familiar frame; `options.meta` persists opaque JSON state without rendering it. Does not run the model. While a turn is open it joins that turn; while idle it is wrapped in a one-shot `injection` turn so every event stays turn-enclosed ([the turn-enclosure invariant](../../../docs/rfc/implemented/architecture/2026-06-15-turn-enclosure-invariant.md)) +- `agent.inject(content, options?)` — accept detached in-session context without running the model; the next request sees its `context/message`. `options.envelope` defaults to the canonical `` framing and may be `'raw'` when the caller owns a complete familiar frame; `options.meta` persists opaque JSON state without rendering it. While a turn is open it joins that turn, deferring FIFO while the current tool batch executes and draining before turn close if execution is interrupted; while idle it is wrapped in a one-shot `injection` turn and durability checkpoint ([the turn-enclosure invariant](../../../docs/rfc/implemented/architecture/2026-06-15-turn-enclosure-invariant.md)). - `agent.cancel(reason?)` — cancel ALL pending work: clears the queued + steering FIFOs, aborts the in-flight step, and drops a turn about to start (the pre-step window) so a queued-but-not-started prompt never runs. A UI/ACP `session/cancel` maps to this. The single public stop primitive. Idle with nothing pending → a safe no-op. - `agent.whenIdle()` — resolve once the agent reaches quiescence after settling out of `running` (idle → immediately; disposed → awaits the loop exit). A non-owner's quiescence-observation hook: it observes the work settling WITHOUT tearing the agent down. Teardown is separate — a lifecycle owner stops and unregisters via `AgentHandle.dispose()`, which awaits the loop exit directly. - `agent.session`, `agent.status`, `agent.options`, `agent.id` diff --git a/packages/core/agent/src/types.ts b/packages/core/agent/src/types.ts index 5f411f4b9a..5c709c828b 100644 --- a/packages/core/agent/src/types.ts +++ b/packages/core/agent/src/types.ts @@ -117,10 +117,11 @@ export interface Agent { steer(content: ContentBlock[], options?: SendOptions): void /** - * Append model-facing context without running the model. Idle injection uses - * a one-shot turn and durability checkpoint, while injection during an open - * turn joins it at the current log position. Disposal awaits idle checkpoints; - * flush failures are reported through `agent/error`, not thrown to the caller. + * Append detached model-facing context without running the model. An open-turn + * injection joins at the current log position unless the current tool batch is + * executing; then it waits FIFO until that batch settles and drains before turn + * close even when interrupted. Idle injection uses a one-shot turn and durability + * checkpoint. Disposal awaits idle checkpoints; flush failures report through `agent/error`. */ inject(content: ContentBlock[], options?: InjectOptions): void diff --git a/packages/core/session/tests/gen-persistence-catalog.spec.ts b/packages/core/session/tests/gen-persistence-catalog.spec.ts index cca9cbfa61..9f18e75bbe 100644 --- a/packages/core/session/tests/gen-persistence-catalog.spec.ts +++ b/packages/core/session/tests/gen-persistence-catalog.spec.ts @@ -9,6 +9,7 @@ import { join } from 'node:path' import { afterEach, describe, expect, it } from 'vitest' import { annotateSurface, + collectEventEnvelopeTypes, collectLogEvents, collectSurfaceEventTypes, render, @@ -56,6 +57,7 @@ describe('gen-persistence-catalog collectLogEvents', () => { scope: 'fix', doc: 'A thing was recorded.', payload: '{ turn: number }', + declaration: '/** A thing was recorded. */\n\'fix/happened\': { turn: number }', source: 'packages/core/fix/src/types.ts:3', }) }) @@ -102,10 +104,13 @@ describe('gen-persistence-catalog collectLogEvents', () => { it('collapses a newline-separated multi-line payload to a valid one-line fragment', () => { const events = collectLogEvents(make({ 'packages/group/fix/src/types.ts': merge( - ' /** Wide payload. */\n \'fix/wide\': {\n alpha: string[]\n range: { start: number; end: number }\n count: number\n }', + ' /** Wide payload. */\n \'fix/wide\': {\n /** Alpha values. */\n alpha: string[]\n range: { start: number; end: number }\n count: number\n }', ), })) expect(events[0]?.payload).toBe('{ alpha: string[]; range: { start: number; end: number }; count: number }') + expect(events[0]?.declaration).toBe( + '/** Wide payload. */\n\'fix/wide\': {\n /** Alpha values. */\n alpha: string[]\n range: { start: number; end: number }\n count: number\n}', + ) }) it('hard-errors on a member with no description prose', () => { @@ -158,6 +163,59 @@ describe('gen-persistence-catalog collectLogEvents', () => { }) }) +describe('gen-persistence-catalog collectEventEnvelopeTypes', () => { + const declarations = `/** Event keys. */ +export type SessionEventType = keyof SessionEventMap +/** Surface-producing event keys. */ +export type SurfaceEventType = 'fix/message' +/** Surface placement. */ +export type SurfaceOp = 'append' +/** One persisted event. */ +export type SessionEvent = { type: T } +` + + it('extracts the envelope declarations with their complete JSDoc in canonical order', () => { + const entries = collectEventEnvelopeTypes(make({ + 'packages/core/fix/package.json': OWNER_MANIFEST, + 'packages/core/fix/src/types.ts': declarations, + })) + expect(entries.map(entry => entry.name)).toEqual([ + 'SessionEventType', + 'SurfaceEventType', + 'SurfaceOp', + 'SessionEvent', + ]) + expect(entries[3]).toMatchObject({ + declaration: '/** One persisted event. */\nexport type SessionEvent = { type: T }', + source: 'packages/core/fix/src/types.ts:8', + }) + }) + + it('hard-errors when an envelope declaration is missing', () => { + expect(() => collectEventEnvelopeTypes(make({ + 'packages/core/fix/package.json': OWNER_MANIFEST, + 'packages/core/fix/src/types.ts': declarations.replace('/** Surface placement. */\nexport type SurfaceOp = \'append\'\n', ''), + }))).toThrow(/missing event-envelope declaration\(s\): SurfaceOp/) + }) + + it('hard-errors on duplicate, unexported, undocumented, or mistagged envelope declarations', () => { + const violations = new RegExp([ + '4 JSDoc completeness violation\\(s\\)', + '[\\s\\S]*not exported', + '[\\s\\S]*@mode tag', + '[\\s\\S]*SurfaceOp.*no description prose', + '[\\s\\S]*SessionEvent.*already declared', + ].join('')) + expect(() => collectEventEnvelopeTypes(make({ + 'packages/core/fix/package.json': OWNER_MANIFEST, + 'packages/core/fix/src/types.ts': declarations + .replace('/** Event keys. */\nexport type SessionEventType', '/** Event keys.\n * @mode emit\n */\ntype SessionEventType') + .replace('/** Surface placement. */\n', '') + + '/** Duplicate event. */\nexport type SessionEvent = { type: never }\n', + }))).toThrow(violations) + }) +}) + describe('gen-persistence-catalog collectSurfaceEventTypes', () => { it('parses the literal union', () => { const types = collectSurfaceEventTypes(make({ @@ -192,9 +250,21 @@ describe('gen-persistence-catalog annotateSurface + render', () => { scope: name.split('/')[0] ?? name, payload: '{ turn: number }', doc: `Records ${name}.`, + declaration: `/** Records ${name}. */\n'${name}': { turn: number }`, source: 'packages/core/fix/src/types.ts:3', }) + const envelopeTypes = [ + 'SessionEventType', + 'SurfaceEventType', + 'SurfaceOp', + 'SessionEvent', + ].map(name => ({ + name: name as 'SessionEventType' | 'SurfaceEventType' | 'SurfaceOp' | 'SessionEvent', + declaration: `/** ${name}. */\nexport type ${name} = never`, + source: 'packages/core/fix/src/types.ts:1', + })) + it('badges union members surface and everything else log-only', () => { const annotated = annotateSurface([entry('fix/message'), entry('fix/marker')], ['fix/message']) expect(annotated.map(e => [e.name, e.surface])).toEqual([['fix/message', true], ['fix/marker', false]]) @@ -205,11 +275,13 @@ describe('gen-persistence-catalog annotateSurface + render', () => { .toThrow(/'fix\/ghost' name no declared log event/) }) - it('renders badges, payload fences, and the generated-file header', () => { - const out = render(annotateSurface([entry('fix/message'), entry('fix/marker')], ['fix/message'])) + it('renders badges, declaration fences, and the generated-file header', () => { + const out = render(annotateSurface([entry('fix/message'), entry('fix/marker')], ['fix/message']), envelopeTypes) expect(out).toContain('Generated by scripts/gen-persistence-catalog.ts') + expect(out).toContain('# Session Persistence Event Catalog') + expect(out).toContain('```ts persistence-catalog\n/** SessionEventType. */\nexport type SessionEventType = never') expect(out).toContain('#### `fix/message` — surface') expect(out).toContain('#### `fix/marker` — log-only') - expect(out).toContain('```ts persistence-catalog\n\'fix/marker\': { turn: number }\n```') + expect(out).toContain('```ts persistence-catalog\n/** Records fix/marker. */\n\'fix/marker\': { turn: number }\n```') }) }) diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md index 16fba41e54..cfe2fdf2fa 100644 --- a/packages/core/tools/README.md +++ b/packages/core/tools/README.md @@ -21,6 +21,7 @@ tools: - `ctx.tools.schemas(scope?: ScopeKey): ToolSchema[]` Schemas of everything the scope can see (without the `execute` functions). The shipped tools' schemas are catalogued in [docs/tool-catalog.md](../../../docs/tool-catalog.md), generated by booting each tool plugin and harvesting this method (see [the tool-schema-catalog RFC](../../../docs/rfc/implemented/process/2026-07-02-tool-schema-catalog.md)). - `ctx.tools.guard(guard: ToolGuard): () => void` Register a monotonic synchronous execution guard after `tools/pre-execute`: returning a reason denies the call, while `undefined` leaves it unchanged. A plain-context guard applies globally; an `agent.ctx` guard applies only to that agent. Later waterfall listeners cannot turn a guard denial back into permission. Disposed with the calling fiber. - `ctx.tools.execute(exec)` losslessly snapshots and freezes arguments, assigns an opaque token, runs the complete policy/dispatch/result pipeline, then independently snapshots the authoritative outcome before final observation. Invalid arguments use the same result path without reaching policy or the body; around wrappers may replace only `signal`. +- `ctx.tools.executionMode(exec)` returns `parallel` only when the visible definition's `isConcurrencySafe(exec.arguments)` classifier returns exactly `true`; unknown, hidden, undeclared, invalid, or throwing classifications are exclusive. ### Injected services @@ -32,7 +33,7 @@ The live registry pipeline has three transformable waterfalls followed by the ob ### Key types -- `ToolDefinition` — `ToolSchema` + `execute(args, exec)`, optional presentation callbacks, and cooperative `timeoutMs`. +- `ToolDefinition` — `ToolSchema` + `execute(args, exec)`, optional presentation callbacks, cooperative `timeoutMs`, and optional per-call `isConcurrencySafe(args)` classification. - `ToolExecutionInput` — the caller-supplied call description: `{ callId, name, arguments, agent?, parent?, signal? }`; callers may pass an enclosing execution's opaque token as `parent` but never choose the new execution's own token. - `ToolExecutionToken` — a fresh branded `Symbol` assigned by the registry. It supports equality correlation only and never crosses a model, log, or worker boundary. - `ToolExecution` — the pipeline-owned call: immutable `{ token, callId, name, arguments, agent?, parent? }` identity plus optional operational `signal`, which an around wrapper may add, replace, remove, and restore. A nested call's `parent` is a `ToolExecutionToken`, not an execution object. @@ -87,6 +88,8 @@ See `defineTool`, `validateArgs`, `ToolArgsError`, `SchemaSpec`, `InferArgs`, an Optional `timeoutMs` must be positive and finite; it is policy metadata, not model-visible schema. +Optional `isConcurrencySafe(args)` receives typed, softly validated arguments. Exact `true` permits concurrent dispatch/body execution; invalid input and all other outcomes remain exclusive. Opted-in bodies do not mutate parent-owned state, and shared-state races must commute or fail closed. The [parallel tool-call RFC](../../../docs/rfc/implemented/feature/2026-07-10-parallel-tool-call-execution.md) owns the full safety contract. + ### Structured-output schema subset `StructuredOutputSchema` is the object-rooted raw JSON Schema subset used by subagents and workflows for machine-readable results. It accepts one scalar `type`, object `properties`/`required`/boolean `additionalProperties`, array `items`, and scalar `enum`/`const`. The annotations `description`, `title`, `default`, and `examples` are ignored but must remain JSON data. Type arrays, undeclared required keys, and unsupported keywords fail through `OutputSchemaError` rather than being ignored; `validateStructuredValue()` returns path-qualified violations without throwing. @@ -108,6 +111,10 @@ Under `code` or `both`, the registry exposes the reserved `run_code` transport a - **The dispatch bridge** (`run_code`'s execute): every binding call is JSON-normalized before dispatch (a value that does not survive — `BigInt`, circulars — rejects that one call, so the dispatched form and logged form are the same JSON value by construction), serialized through a per-run queue (even `Promise.all` executes underlying calls one at a time in submission order), given the outer execution's opaque token as `parent`, and run through the complete pre-execute → guards → execute → post-execute → result pipeline. A denial reaches the program as a binding rejection, and each sub-call is logged as a `tool/code-dispatch` session event with deterministic id `:code:`; `deriveMessages()` does not surface that event. Token correlation lets commit-style observers defer an inner success until the final `run_code` result without exposing the live outer execution; ordinary tool side effects are not rolled back. Every sub-call `additionalContexts` entry is deferred through the outer `ToolRunContext` in dispatch order; the loop appends those contexts only after the parent `run_code` result, preserving adjacency and retaining each source/envelope/meta even when the program later fails. - **Settlement discipline**: the bridge owns a run-scoped abort that follows the outer signal in and fires when the run settles for any reason, so a budget expiry aborts an in-flight sub-tool instead of orphaning it; the bridge then drains its queue BEFORE returning, so every `tool/code-dispatch` lands inside the open turn. A failed run throws `CodeRunFailedError` (`code: 'CODE_RUN_FAILED'`, message = the failure kind + captured logs), which the pipeline converts to a structured `isError` the model self-corrects from. +### Parallel execution + +The agent loop groups consecutive `parallel` calls into a bounded rolling pool and treats each `exclusive` call as an ordering barrier. Only dispatch/body overlaps; policy, durable results, and context retain model order. Code Mode bindings remain serial. The [parallel tool-call RFC](../../../docs/rfc/implemented/feature/2026-07-10-parallel-tool-call-execution.md) owns the shipped declarations and rationale. + ## Model Experience ### Normal tool schemas @@ -145,7 +152,7 @@ The available tools: ## Known Limitations and Deferred Work -- **Native tool calls execute sequentially** — `ToolDefinition` carries no concurrency-safety metadata; adding it (and parallel execution in the loop) waits on the deferred tool-shapes review (`TODO(review)`). +- **Concurrency policy is not an event seam** — `executionMode()` reads the resolved tool definition directly; plugins can only declare a classifier on definitions they own. - **`tools/pre-execute` deliberately cannot rewrite `exec.arguments`** — logged and rendered args would desync from what ran; the rewrite design is [a proposed RFC](../../../docs/rfc/proposed/feature/2026-06-30-pre-tool-input-rewrite.md). - **`defineTool`'s schema DSL is a deliberate subset** — string/number/boolean/object/array with string-only `enum`; `validateArgs` tolerates extra keys and never applies `default` (`XXX(unused-default)` flags removing that field); raw-registered JSON-Schema tools validate their own input. - **`timeoutMs` on a definition is declarative only** — the registry never enforces deadlines; enforcement requires the `@deepseek-ai/dsh-timeout-policy` wrapper. diff --git a/packages/core/tools/src/index.ts b/packages/core/tools/src/index.ts index 4aeebe1d99..5fc045ace2 100644 --- a/packages/core/tools/src/index.ts +++ b/packages/core/tools/src/index.ts @@ -117,9 +117,6 @@ declare module 'cordis' { } } -// TODO(concurrency): revisit these shapes when concurrency metadata becomes useful -// (for example, a read-only hint that would permit safe parallel execution). - /** Tool output, optionally with lossless-JSON presentation metadata persisted for replay. */ export type ToolExecuteReturn = ContentBlock[] | { content: ContentBlock[]; meta?: unknown } @@ -134,6 +131,20 @@ export interface ToolDefinition extends ToolSchema { * cooperative implementation that can reach quiescence when the signal aborts. */ timeoutMs?: number + /** + * Pure synchronous classifier for overlap with sibling tool calls. Only + * `true` opts in; omission, exceptions, non-`true` returns, and invalid + * `defineTool` arguments are exclusive. This metadata is never model-visible. + * + * Opted-in executions must not mutate parent-owned state. Shared state must + * tolerate concurrent dispatch; recorder races are permitted only when they + * commute or fail closed. See the + * [parallel-tool-call RFC](../../../../docs/rfc/implemented/feature/2026-07-10-parallel-tool-call-execution.md) + * for the full contract. + * @param args - parsed arguments; `defineTool` validates before calling. + * @returns Whether this call may join a parallel group. + */ + isConcurrencySafe?(args: unknown): boolean /** * Optional: how to present the PENDING state of one call in a UI, derived from * the call's `args` (parsed arguments, `unknown` — the tool validates/narrows @@ -195,6 +206,14 @@ export interface ToolExecutionInput { signal?: AbortSignal } +/** + * Scheduling mode for one pending call. `parallel` may overlap with siblings; + * `exclusive` runs alone and forms an ordering barrier. + */ +export type ToolExecutionMode = + | { kind: 'parallel' } + | { kind: 'exclusive' } + /** * One pending tool call inside the registry pipeline. Parsed arguments cross * one lossless-JSON materialization boundary before policy and are deep-frozen; @@ -222,6 +241,47 @@ export interface ToolRunContext extends ToolExecution { deferContext(context: HookContext): void } +/** + * Scheduler-only result after ordered pre-execute and guards. A `post-result` + * still receives post-execute; a `final-result` bypasses it. + * @internal + */ +export type ScheduledToolPreparation = + | { kind: 'dispatch'; exec: ToolRunContext } + | { kind: 'post-result'; exec: ToolRunContext; result: ToolExecutionResult } + | { kind: 'final-result'; exec: ToolRunContext; result: ToolExecutionResult } + +/** + * Scheduler-only dispatch result. A `post-result` still receives post-execute; + * a `final-result` already matches {@link ToolRegistry.execute} failure semantics. + * @internal + */ +export type ScheduledToolDispatch = + | { kind: 'post-result'; result: ToolExecutionResult } + | { kind: 'final-result'; result: ToolExecutionResult } + +/** + * Symbol-keyed scheduler view that keeps pre/post policy ordered while + * overlapping dispatch. Ordinary callers use {@link ToolRegistry.execute}; + * this is not a plugin seam. + * @internal + */ +export interface ToolRegistryScheduler { + /** Materialize input, run the ordered pre-execute/guard gate, and decide what stage follows. */ + prepare(exec: ToolExecutionInput): Promise + /** Run only the around-dispatch/body stage. */ + dispatch(exec: ToolRunContext): Promise + /** Run ordered post-execute finalization, then materialize and notify the final outcome. */ + finalize(exec: ToolRunContext, result: ToolExecutionResult): Promise + /** Materialize and notify a final outcome that must bypass post-execute. */ + finish(exec: ToolRunContext, result: ToolExecutionResult): ToolExecutionResult +} + +/** + * Scheduler entry point omitted from the generated named service API. + * @internal + */ +export const TOOL_REGISTRY_SCHEDULER: unique symbol = Symbol('@deepseek-ai/dsh-tools.scheduler') /** Structured error metadata for a failed tool call (alongside the model-facing text). */ export interface ToolErrorInfo { name: string @@ -252,8 +312,8 @@ export interface ToolExecutionResult { */ error?: ToolErrorInfo /** - * Model-facing context for the next request, separate from this tool result. - * The loop buffers it until all step results are logged, preserving pairing. + * Model-facing context for the next request, separate from this tool result. The loop + * accepts it into the active-batch FIFO, then appends after recorded results even if interrupted. */ additionalContexts?: HookContext[] /** @@ -382,6 +442,16 @@ export class ToolRegistry extends Service { mode: z.union(['native', 'code', 'both'] as const).default('native'), }) + /** Internal staged view consumed by `dsh-agent-loop`'s parallel scheduler. */ + readonly [TOOL_REGISTRY_SCHEDULER]: ToolRegistryScheduler = { + prepare: exec => this.prepareScheduledExecution(exec), + dispatch: exec => this.dispatchScheduledExecution(exec), + finalize: (exec, result) => this.finalizeScheduledExecution(exec, result), + finish: (exec, result) => this.finishScheduledExecution(exec, result), + } + + /** Context deferred by a running tool body, keyed by its scheduler-owned execution. */ + private deferredContexts = new WeakMap() private global = new Map() private scoped = new Map>() /** Compiled restriction filters, per scope (see {@link restrict}). */ @@ -682,6 +752,24 @@ export class ToolRegistry extends Service { } } + /** + * Classify a pending call through the caller's visible tool definition. Only + * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or + * throwing classifiers are exclusive. + * @param exec - call name, parsed arguments, and optional agent scope. + * @returns the fail-closed scheduling mode. + */ + executionMode(exec: ToolExecutionInput): ToolExecutionMode { + const tool = this.get(exec.name, exec.agent) + if (!tool?.isConcurrencySafe) return { kind: 'exclusive' } + try { + const concurrencySafe: unknown = tool.isConcurrencySafe(exec.arguments) + return concurrencySafe === true ? { kind: 'parallel' } : { kind: 'exclusive' } + } catch { + return { kind: 'exclusive' } + } + } + /** * Execute through pre-policy, guards, around-dispatch, post-policy, and final * notification. Tool and listener failures resolve as materialized error @@ -692,6 +780,28 @@ export class ToolRegistry extends Service { * @returns the materialized final result. */ async execute(exec: ToolExecutionInput): Promise { + return this.prepareExecution(exec, prepared => this.completeScheduledExecution(prepared)) + } + + private async completeScheduledExecution(prepared: ScheduledToolPreparation): Promise { + switch (prepared.kind) { + case 'dispatch': { + const dispatched = await this.dispatchScheduledExecution(prepared.exec) + return dispatched.kind === 'post-result' + ? await this.finalizeScheduledExecution(prepared.exec, dispatched.result) + : this.finishScheduledExecution(prepared.exec, dispatched.result) + } + case 'post-result': + return await this.finalizeScheduledExecution(prepared.exec, prepared.result) + case 'final-result': + return this.finishScheduledExecution(prepared.exec, prepared.result) + /* v8 ignore next -- closed-union exhaustiveness guard */ + default: + return assertNever(prepared, 'scheduled tool preparation') + } + } + + private createExecution(exec: ToolExecutionInput): ScheduledToolPreparation | { kind: 'ready'; exec: ToolRunContext } { const deferredContexts: HookContext[] = [] const token = createExecutionToken() const callId = exec.callId @@ -710,105 +820,143 @@ export class ToolRegistry extends Service { deferredContexts.push(context) }, } - let execution: ToolRunContext try { const detached = snapshotJsonValue(exec.arguments) if (detached === undefined) { throw new TypeError('tool execution arguments must be losslessly JSON-serializable') } - execution = { - ...base, - arguments: deepFreeze(detached), - } + const execution: ToolRunContext = { ...base, arguments: deepFreeze(detached) } + this.deferredContexts.set(execution, deferredContexts) + return { kind: 'ready', exec: execution } } catch (error: unknown) { - execution = { ...base, arguments: undefined } - const result = this.materializeFinalResult(toolErrorResult(error)) - this.notifyResult(execution, result) - return result + const execution: ToolRunContext = { ...base, arguments: undefined } + return { kind: 'final-result', exec: execution, result: toolErrorResult(error) } } - let result: ToolExecutionResult + } + + /** + * Run the ordered pre-execute and monotonic guard stages for the scheduler. + * @param input - the caller-supplied execution input. + * @returns the prepared execution plus the next scheduler stage. + * @internal + */ + private async prepareScheduledExecution(input: ToolExecutionInput): Promise { + return this.prepareExecution(input, prepared => prepared) + } + + private async prepareExecution( + input: ToolExecutionInput, + next: (prepared: ScheduledToolPreparation) => T | PromiseLike, + ): Promise { + const created = this.createExecution(input) + if (created.kind !== 'ready') return next(created) + const exec = created.exec try { - result = this.materializeFinalResult(await this.executePipeline(execution, deferredContexts)) + const carrier = scopeTarget(this, exec.agent) + const gate = await this.ctx.waterfall( + carrier, 'tools/pre-execute', exec, + () => Promise.resolve({ kind: 'allow' }), + ) + const decision = gate.kind === 'ask' ? await this.serviceAsk(exec, gate) : gate + const denialReason = decision.kind === 'allow' + ? this.guardReason(exec) + : decision.reason + if (denialReason !== undefined) { + return await next({ + kind: 'post-result', + exec, + result: { + content: [{ type: 'text', text: `Error: ${denialReason}` }], + isError: true, + }, + }) + } + return await next({ kind: 'dispatch', exec }) } catch (error: unknown) { - // Outer backstop: a throwing pre/post-execute listener, guard, or the - // waterfall machinery becomes an isError result, never a turn failure. - result = this.materializeFinalResult(toolErrorResult(error)) + return next({ kind: 'final-result', exec, result: toolErrorResult(error) }) } - this.notifyResult(execution, result) - return result } - /** Run the transformable pipeline; {@link execute} owns final normalization and notification. */ - private async executePipeline(exec: ToolRunContext, deferredContexts: HookContext[]): Promise { - // --- Gate: tools/pre-execute. An `ask` resolves through the optional - // approval seam (or degrades to deny) before the monotonic guards run. The - // carrier keys dispatch by exec.agent, so an `agent.ctx` listener gates only - // its own agent's calls (agent-less calls are subject-less). - const carrier = scopeTarget(this, exec.agent) - const gate = await this.ctx.waterfall( - carrier, 'tools/pre-execute', exec, - () => Promise.resolve({ kind: 'allow' }), - ) - const decision = gate.kind === 'ask' ? await this.serviceAsk(exec, gate) : gate - const denialReason = decision.kind === 'allow' - ? this.guardReason(exec) - : decision.reason - if (denialReason !== undefined) { - // Every non-grant, including a failed/unavailable approval request, takes - // the same deny path and still reaches post-policy plus result observers. - const denied: ToolExecutionResult = { - content: [{ type: 'text', text: `Error: ${denialReason}` }], - isError: true, - } - return await this.postExecute(exec, denied) - } - - // --- Around-dispatch: tools/execute. The base `next` is the dispatch- - // with-normalization thunk — the tool body's own try/catch turns a throw - // into an isError result so a wrapper (and post-execute) can inspect it; - // an unknown tool routes through the same catch. A `tools/execute` listener - // (e.g. a timeout plugin) wraps this thunk: it may replace `exec.signal` - // before delegating and inspect the normalized result after. Dispatched with the - // same carrier as the gate, so an `agent.ctx` wrapper wraps only its own - // agent's calls. --- - const result = await this.ctx.waterfall( - carrier, 'tools/execute', exec, - async (): Promise => { - try { - // Resolve through the CALLER's visible view ({@link get}): a scoped - // tool shadows its global name-twin for that agent, and a - // restricted-away global tool is exactly as absent as a nonexistent - // one — same UNKNOWN_TOOL result, no capability leak in the error. - const tool = this.get(exec.name, exec.agent) - if (!tool) throw new ToolNotFoundError(exec.name) - // Normalize the two `execute` return shapes: a bare ContentBlock[] (no - // meta) or a { content, meta } object (a tool attaching a private - // presentation payload). An array IS the content; the object carries it. - const returned = await tool.execute(exec.arguments, exec) - const content = Array.isArray(returned) ? returned : returned.content - const meta = Array.isArray(returned) ? undefined : returned.meta - return { content, isError: false, ...meta !== undefined ? { meta } : {} } - } catch (error: unknown) { - return toolErrorResult(error) + /** + * Run around-dispatch and the tool body. Tool and unknown-tool failures still + * receive post-execute; pipeline failures are already final. + * @param exec - the prepared execution. + * @returns whether the result still needs post-execute. + * @internal + */ + private async dispatchScheduledExecution(exec: ToolRunContext): Promise { + try { + const carrier = scopeTarget(this, exec.agent) + const result = await this.ctx.waterfall( + carrier, 'tools/execute', exec, + async (): Promise => { + try { + const tool = this.get(exec.name, exec.agent) + if (!tool) throw new ToolNotFoundError(exec.name) + const returned = await tool.execute(exec.arguments, exec) + const content = Array.isArray(returned) ? returned : returned.content + const meta = Array.isArray(returned) ? undefined : returned.meta + return { content, isError: false, ...meta !== undefined ? { meta } : {} } + } catch (error: unknown) { + return toolErrorResult(error) + } + }, + ) + const deferredContexts = this.deferredContexts.get(exec) + /* v8 ignore next -- dispatch only receives executions minted by this registry's prepare stage */ + if (deferredContexts === undefined) throw new Error('tool registry scheduler invariant violated: unprepared execution') + const resultWithDeferredContexts: ToolExecutionResult = deferredContexts.length === 0 + ? result + : { + ...result, + additionalContexts: [ + ...deferredContexts, + ...result.additionalContexts ?? [], + ], } - }, - ) - const resultWithDeferredContexts: ToolExecutionResult = deferredContexts.length === 0 - ? result - : { - ...result, - additionalContexts: [ - ...deferredContexts, - ...result.additionalContexts ?? [], - ], - } - return await this.postExecute(exec, resultWithDeferredContexts) + return { kind: 'post-result', result: resultWithDeferredContexts } + } catch (error: unknown) { + return { kind: 'final-result', result: toolErrorResult(error) } + } } - /** Notify final-result observers without giving them a mutation/error channel into the outcome. */ + /** + * Run ordered post-execute, then materialize and notify the final outcome. + * @param exec - the prepared execution. + * @param result - dispatch/pre result that still needs post-execute. + * @returns the materialized final result. + * @internal + */ + private async finalizeScheduledExecution(exec: ToolRunContext, result: ToolExecutionResult): Promise { + try { + return this.finishScheduledExecution(exec, await this.postExecute(exec, result)) + } catch (error: unknown) { + return this.finishScheduledExecution(exec, toolErrorResult(error)) + } + } + + /** + * Materialize and notify a final result that must bypass post-execute. + * @param exec - the prepared execution. + * @param result - final result. + * @returns the materialized final result. + * @internal + */ + private finishScheduledExecution(exec: ToolRunContext, result: ToolExecutionResult): ToolExecutionResult { + let finalResult: ToolExecutionResult + try { + finalResult = this.materializeFinalResult(result) + } catch (error: unknown) { + finalResult = this.materializeFinalResult(toolErrorResult(error)) + } + this.notifyResult(exec, finalResult) + return finalResult + } + + /** Notify observers without exposing a mutation or error channel into the outcome. */ private notifyResult(exec: ToolExecution, result: ToolExecutionResult): void { - // The pipeline is over: freeze the remaining mutable signal slot so every - // observer sees the SAME WeakMap-keyable execution without a mutation race. + // Freeze the remaining mutable signal slot before observers receive the + // shared WeakMap-keyable execution object. Object.freeze(exec) const callbacks = this.ctx.events.dispatch('emit', [ scopeTarget(this, exec.agent), 'tools/result', exec, result, @@ -865,7 +1013,7 @@ export class ToolRegistry extends Service { * its {@link PostToolDecision}: `accept` keeps the call successful (replacing * `content` when given), `block` turns it into an `isError` whose content is * the corrective `feedback`. Either decision may attach `additionalContexts`, - * which are ferried on the returned result for the loop's per-step buffer. + * which are ferried on the returned result for the loop's active-batch FIFO. * Context deferred by the tool body survives an accepted result but is * discarded when the outer call is blocked; a block exposes only context the * blocking decision explicitly supplied. diff --git a/packages/core/tools/src/schema.ts b/packages/core/tools/src/schema.ts index 9b8510a768..c61c819618 100644 --- a/packages/core/tools/src/schema.ts +++ b/packages/core/tools/src/schema.ts @@ -283,6 +283,14 @@ export interface DefineToolOptions { * is never sent to the model. */ readonly timeoutMs?: number + /** + * Optional pure synchronous classifier for sibling overlap. It receives typed + * arguments after soft validation; invalid input returns `false` without + * invoking it. See {@link ToolDefinition.isConcurrencySafe}. + * @param args - typed validated arguments. + * @returns whether this call may join a parallel group. + */ + isConcurrencySafe?(args: InferArgs): boolean /** * Tool execution function. `args` is typed as {@link InferArgs} — zero * casts needed. Returns either a bare {@link ContentBlock}`[]` (model-facing @@ -315,7 +323,7 @@ export interface DefineToolOptions { * @param options - the tool's name, description, typed parameter schema, * execute body, and optional presenters. * @returns a registry-ready definition with strict execution validation and - * soft presenter validation for replay compatibility. + * soft presenter and classifier validation for replay compatibility. */ export function defineTool(options: DefineToolOptions): ToolDefinition { // Object-literal execute methods don't use `this`; the reference is safe. @@ -325,6 +333,8 @@ export function defineTool(options: DefineToolOptions): const userPresentCall = options.presentCall // eslint-disable-next-line @typescript-eslint/unbound-method const userPresentResult = options.presentResult + // eslint-disable-next-line @typescript-eslint/unbound-method + const userIsConcurrencySafe = options.isConcurrencySafe if (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0)) { throw new Error(`defineTool(${options.name}): timeoutMs must be a positive finite number`) } @@ -359,5 +369,12 @@ export function defineTool(options: DefineToolOptions): return userPresentResult(args as InferArgs, result) } } + // Invalid arguments fail closed without invoking the typed classifier. + if (userIsConcurrencySafe) { + tool.isConcurrencySafe = (args: unknown): boolean => { + if (validateArgs(options.parameters, args).length > 0) return false + return userIsConcurrencySafe(args as InferArgs) + } + } return tool } diff --git a/packages/core/tools/tests/execution-mode.spec.ts b/packages/core/tools/tests/execution-mode.spec.ts new file mode 100644 index 0000000000..9a12f33a51 --- /dev/null +++ b/packages/core/tools/tests/execution-mode.spec.ts @@ -0,0 +1,136 @@ +/** Covers fail-closed per-call classification and model-schema isolation. */ + +import { describe, expect, expectTypeOf, it } from 'vitest' +import { Context } from 'cordis' +import { CallId } from '@deepseek-ai/dsh-llm' +import SystemPrompt from '@deepseek-ai/dsh-system-prompt' +import ToolRegistry, { + defineTool, + type ToolDefinition, + type ToolExecutionInput, + type ToolExecutionMode, +} from '@deepseek-ai/dsh-tools' + +async function setup() { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + return ctx +} + +function exec(name: string, args: unknown): ToolExecutionInput { + return { callId: CallId('c1'), name, arguments: args } +} + +describe('ToolRegistry.executionMode', () => { + it('returns parallel only for an explicit true classifier', async () => { + const ctx = await setup() + ctx.tools.register(defineTool({ + name: 'safe', + description: 'parallel-safe', + parameters: {}, + isConcurrencySafe: () => true, + async execute() { return [] }, + })) + expect(ctx.tools.executionMode(exec('safe', {}))).toEqual({ kind: 'parallel' }) + }) + + it('defaults to exclusive for a tool with no isConcurrencySafe declaration', async () => { + const ctx = await setup() + ctx.tools.register(defineTool({ + name: 'plain', + description: 'no declaration', + parameters: {}, + async execute() { return [] }, + })) + expect(ctx.tools.executionMode(exec('plain', {}))).toEqual({ kind: 'exclusive' }) + }) + + it('returns exclusive for an unknown tool', async () => { + const ctx = await setup() + expect(ctx.tools.executionMode(exec('nonexistent', {}))).toEqual({ kind: 'exclusive' }) + }) + + it('returns exclusive when the classifier returns false for these args', async () => { + const ctx = await setup() + ctx.tools.register(defineTool({ + name: 'rw', + description: 'read or write', + parameters: { mode: { type: 'string', required: true } }, + isConcurrencySafe: args => args.mode === 'read', + async execute() { return [] }, + })) + expect(ctx.tools.executionMode(exec('rw', { mode: 'read' }))).toEqual({ kind: 'parallel' }) + expect(ctx.tools.executionMode(exec('rw', { mode: 'write' }))).toEqual({ kind: 'exclusive' }) + }) + + it('classifies invalid defineTool arguments as exclusive without throwing', async () => { + const ctx = await setup() + ctx.tools.register(defineTool({ + name: 'needs-mode', + description: 'requires mode', + parameters: { mode: { type: 'string', required: true } }, + isConcurrencySafe: () => true, + async execute() { return [] }, + })) + expect(ctx.tools.executionMode(exec('needs-mode', {}))).toEqual({ kind: 'exclusive' }) + }) + + it('treats a throwing raw classifier as exclusive', async () => { + const ctx = await setup() + const raw: ToolDefinition = { + name: 'thrower', + description: 'classifier throws', + parameters: { type: 'object', properties: {} }, + isConcurrencySafe() { throw new Error('boom') }, + async execute() { return [] }, + } + ctx.tools.register(raw) + expect(ctx.tools.executionMode(exec('thrower', {}))).toEqual({ kind: 'exclusive' }) + }) + + it('treats a truthy non-boolean raw result as exclusive', async () => { + const ctx = await setup() + const raw = { + name: 'truthy', + description: 'classifier returns a truthy string', + parameters: { type: 'object', properties: {} }, + isConcurrencySafe() { return 'yes' }, + async execute() { return [] }, + } as unknown as ToolDefinition + ctx.tools.register(raw) + expect(ctx.tools.executionMode(exec('truthy', {}))).toEqual({ kind: 'exclusive' }) + }) + + it('passes parsed arguments directly to a raw definition', async () => { + const ctx = await setup() + let seen: unknown + ctx.tools.register({ + name: 'raw-safe', + description: 'raw', + parameters: { type: 'object', properties: {} }, + isConcurrencySafe(args) { seen = args; return true }, + async execute() { return [] }, + }) + expect(ctx.tools.executionMode(exec('raw-safe', { anything: 1 }))).toEqual({ kind: 'parallel' }) + expect(seen).toEqual({ anything: 1 }) + }) + + it('isConcurrencySafe never reaches the model-facing schemas() projection', async () => { + const ctx = await setup() + ctx.tools.register(defineTool({ + name: 'safe', + description: 'parallel-safe', + parameters: { x: { type: 'string', required: true } }, + isConcurrencySafe: () => true, + async execute() { return [] }, + })) + const schema = ctx.tools.schemas()[0] as unknown as Record + expect(Object.keys(schema).sort()).toEqual(['description', 'name', 'parameters']) + expect(schema.isConcurrencySafe).toBeUndefined() + }) + + it('ToolExecutionMode is the object-tagged union', () => { + expectTypeOf().toEqualTypeOf<{ kind: 'parallel' } | { kind: 'exclusive' }>() + }) +}) diff --git a/packages/examples/acp-demo/README.md b/packages/examples/acp-demo/README.md index bf6c00e3ce..1dbda9a08a 100644 --- a/packages/examples/acp-demo/README.md +++ b/packages/examples/acp-demo/README.md @@ -27,6 +27,7 @@ Because the package wires no logger entry, an ACP leaf has **nothing to get wron |---|---|---| | `provider` | (required) | the initial provider route for each per-session agent the bridge creates; ACP model selection may replace it per session | | `model` | (required) | the initial model for each per-session agent; ACP clients may switch among adapter-advertised models | +| `maxParallelToolCalls` | agent-loop default | positive-integer concurrent tool-call cap shared by the bundled loop's agents; `1` is serial | | `persona` | — | the deployment persona template (may reference `{{provider}}`/`{{model}}`/`{{cwd}}`), routed to `dsh-system-prompt` | | `toolOrder` | — | explicit model-facing tool order (a name list with one `''` rest entry; absent — lexicographic; an unregistered name fails each turn at prompt assembly), routed to `dsh-system-prompt` | | `dshHome` | `$DSH_HOME` or `~/.dsh` | Harness home exposed to model bash and used by local skill discovery | diff --git a/packages/examples/acp-demo/src/index.ts b/packages/examples/acp-demo/src/index.ts index 257aae5b12..caa6ffd582 100644 --- a/packages/examples/acp-demo/src/index.ts +++ b/packages/examples/acp-demo/src/index.ts @@ -34,6 +34,8 @@ export interface Config { provider: string /** Model name for ACP-created agents (must have a registered adapter). */ model: string + /** Bundled agent-loop concurrency cap; `1` is serial and omission uses its default. */ + maxParallelToolCalls?: number /** Deployment persona (the system-prompt plugin's `persona` config). */ persona?: string /** Explicit model-facing tool order (the system-prompt plugin's `toolOrder` config; see dsh-system-prompt). */ @@ -60,6 +62,7 @@ export interface Config { export const Config: z = z.object({ provider: z.string().required(), model: z.string().required(), + maxParallelToolCalls: z.number().step(1).min(1), persona: z.string(), // The array default is forced to undefined: ABSENT means "lexicographic // order" (the owning dsh-system-prompt schema does the same), while diff --git a/packages/examples/acp-demo/tests/acp-agent.spec.ts b/packages/examples/acp-demo/tests/acp-agent.spec.ts index e717cf57fa..c033056f12 100644 --- a/packages/examples/acp-demo/tests/acp-agent.spec.ts +++ b/packages/examples/acp-demo/tests/acp-agent.spec.ts @@ -127,6 +127,19 @@ describe('dsh-acp-demo composition', () => { await ctx.fiber.dispose() }) + it('forwards maxParallelToolCalls to the bundled agent loop', async () => { + const ctx = await mount({ + provider: 'mock', + model: 'mock', + maxParallelToolCalls: 3, + persistenceRoot: '/tmp/dsh-acp-demo-test-parallel', + skills: await isolatedSkillsConfig(), + workspaceContext: false, + }) + expect(ctx.get('agentLoop')?.config.maxParallelToolCalls).toBe(3) + await ctx.fiber.dispose() + }) + it('forwards bundled tool config into agent-core', async () => { const ctx = await mount({ provider: 'mock', diff --git a/packages/examples/agent-spine-demo/README.md b/packages/examples/agent-spine-demo/README.md index 45797a58c8..9f1b1012f5 100644 --- a/packages/examples/agent-spine-demo/README.md +++ b/packages/examples/agent-spine-demo/README.md @@ -42,11 +42,11 @@ This is the [interface/implementation/consumer seam](../../../docs/rfc/implement ```ts import type { Config } from '@deepseek-ai/dsh-agent-spine-demo' -// { agents?, persona?, toolOrder?, tools?, dshHome?, skills?, workspaceContext, toolBash?, toolTasks? } +// { agents?, maxParallelToolCalls?, persona?, toolOrder?, tools?, dshHome?, skills?, workspaceContext, toolBash?, toolTasks? } // workspaceContext requires { maxBytes } or false; the other owner schemas supply defaults. ``` -The bundle FORWARDS each field to the child that owns it: `agents` to `agent-loop` (default `[]`), so each app supplies its own pre-created agents — a stdio app pre-creates a `main`; the ACP app pre-creates none (it creates agents on demand at `session/new`) — `persona` and `toolOrder` to `dsh-system-prompt`; `tools` to the tool registry for its presentation mode; `skills.registry`, `skills.local`, and `skills.tool` to the skill registry, local provider, and model-facing consumer; the required `workspaceContext` choice to `dsh-workspace-context` (`{ maxBytes }` enables loading and `false` disables it); and `toolBash`/`toolTasks` to the two model-facing tool plugins the bundle owns. It resolves `dshHome` once through [`@deepseek-ai/dsh-home`](../../util/home/README.md) and forwards that absolute value to tool-bash's managed environment and local skill discovery. An absent top-level `dshHome` adopts `skills.local.dshHome`; supplying both with different resolved paths fails loudly. `toolBash.enableRunInBackground` controls only the bash producer, while `toolTasks` controls generic `task_output` wait bounds; independently loaded producers keep their own config. Workspace instructions register before the skill catalog so their session-prefix message renders first. App packages use `pickSpineConfig()` to copy only these bundle-owned fields. +The bundle FORWARDS each field to the child that owns it: `agents` and `maxParallelToolCalls` to `agent-loop` (`agents` defaults to `[]`; the cap defaults there), so each app supplies its own pre-created agents — a stdio app pre-creates `main`, while the ACP app creates agents on demand at `session/new`; `persona` and `toolOrder` to `dsh-system-prompt`; `tools` to the tool registry for its presentation mode; `skills.registry`, `skills.local`, and `skills.tool` to the skill registry, local provider, and model-facing consumer; the required `workspaceContext` choice to `dsh-workspace-context` (`{ maxBytes }` enables loading and `false` disables it); and `toolBash`/`toolTasks` to the two model-facing tool plugins the bundle owns. It resolves `dshHome` once through [`@deepseek-ai/dsh-home`](../../util/home/README.md) and forwards that absolute value to tool-bash's managed environment and local skill discovery. An absent top-level `dshHome` adopts `skills.local.dshHome`; supplying both with different resolved paths fails loudly. `toolBash.enableRunInBackground` controls only the bash producer, while `toolTasks` controls generic `task_output` wait bounds; independently loaded producers keep their own config. Workspace instructions register before the skill catalog so their session-prefix message renders first. App packages use `pickSpineConfig()` to copy only these bundle-owned fields. ## Why a code bundle, not a shared YAML include diff --git a/packages/examples/agent-spine-demo/src/index.ts b/packages/examples/agent-spine-demo/src/index.ts index d8357c6c9a..a4965ca457 100644 --- a/packages/examples/agent-spine-demo/src/index.ts +++ b/packages/examples/agent-spine-demo/src/index.ts @@ -57,6 +57,8 @@ export interface SkillConfig { export interface Config { /** The agent-loop `agents` list (see dsh-agent-loop's `Config`). */ agents?: AgentLoopConfig['agents'] + /** Agent-loop concurrency cap; `1` is serial. */ + maxParallelToolCalls?: AgentLoopConfig['maxParallelToolCalls'] /** The deployment persona (see dsh-system-prompt's `Config`). */ persona?: SystemPromptConfig['persona'] /** The explicit model-facing tool order (see dsh-system-prompt's `Config`). */ @@ -109,6 +111,7 @@ export const Config = z.intersect([ */ export function pickSpineConfig(config: Omit): Omit { return { + ...config.maxParallelToolCalls !== undefined ? { maxParallelToolCalls: config.maxParallelToolCalls } : {}, ...config.persona !== undefined ? { persona: config.persona } : {}, ...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {}, ...config.tools !== undefined ? { tools: config.tools } : {}, @@ -160,5 +163,8 @@ export function apply(ctx: Context, config: Config): void { // rendered order, so workspace instructions must precede the skill catalog. ctx.plugin(toolSkill, config.skills?.tool ?? {}) ctx.plugin(toolTasks, config.toolTasks ?? {}) - ctx.plugin(AgentLoop, { agents: config.agents ?? [] }) + ctx.plugin(AgentLoop, { + agents: config.agents ?? [], + ...config.maxParallelToolCalls !== undefined ? { maxParallelToolCalls: config.maxParallelToolCalls } : {}, + }) } diff --git a/packages/examples/agent-spine-demo/tests/agent-core.spec.ts b/packages/examples/agent-spine-demo/tests/agent-core.spec.ts index 3629fdd838..fdf17286ee 100644 --- a/packages/examples/agent-spine-demo/tests/agent-core.spec.ts +++ b/packages/examples/agent-spine-demo/tests/agent-core.spec.ts @@ -145,6 +145,16 @@ describe('dsh-agent-spine-demo bundle', () => { await ctx.fiber.dispose() }) + it('forwards the global maxParallelToolCalls config to agent-loop', async () => { + const ctx = await mount({ + agents: [{ id: AgentId('main'), provider: 'mock', model: 'mock' }], + maxParallelToolCalls: 3, + workspaceContext: false, + }) + expect(ctx.get('agentLoop')?.config.maxParallelToolCalls).toBe(3) + await ctx.fiber.dispose() + }) + it('tolerates a schema-bypassing direct apply (the ?? fallbacks fire)', async () => { // ctx.plugin validates + defaults the bundle config first; a direct apply // skips the schema, so the forwarding `?? []` / `?? ''` are what fire. diff --git a/packages/examples/stdio-demo/README.md b/packages/examples/stdio-demo/README.md index ba5381bbba..5eb6ea766c 100644 --- a/packages/examples/stdio-demo/README.md +++ b/packages/examples/stdio-demo/README.md @@ -27,6 +27,7 @@ The leaf `cordis.yml` supplies only the **swappable backends** — an LLM adapte |---|---|---| | `provider` | (required) | the pre-created `main` agent's registered provider route | | `model` | (required) | the pre-created `main` agent's model | +| `maxParallelToolCalls` | agent-loop default | positive-integer concurrent tool-call cap shared by the bundled loop's agents; `1` is serial | | `persona` | — | the deployment persona template (may reference `{{provider}}`/`{{model}}`/`{{cwd}}`), routed to `dsh-system-prompt` | | `toolOrder` | — | explicit model-facing tool order (a name list with one `''` rest entry; absent — lexicographic; an unregistered name fails each turn at prompt assembly), routed to `dsh-system-prompt` | | `dshHome` | `$DSH_HOME` or `~/.dsh` | Harness home exposed to model bash and used by local skill discovery | diff --git a/packages/examples/stdio-demo/src/index.ts b/packages/examples/stdio-demo/src/index.ts index 89871cada4..91c377e9f7 100644 --- a/packages/examples/stdio-demo/src/index.ts +++ b/packages/examples/stdio-demo/src/index.ts @@ -39,6 +39,8 @@ export interface Config { provider: string /** Model name for the `main` agent (must have a registered adapter). */ model: string + /** Bundled agent-loop concurrency cap; `1` is serial and omission uses its default. */ + maxParallelToolCalls?: number /** Deployment persona (the system-prompt plugin's `persona` config). */ persona?: string /** Explicit model-facing tool order (the system-prompt plugin's `toolOrder` config; see dsh-system-prompt). */ @@ -70,6 +72,7 @@ export interface Config { export const Config: z = z.object({ provider: z.string().required(), model: z.string().required(), + maxParallelToolCalls: z.number().step(1).min(1), persona: z.string(), // The array default is forced to undefined: ABSENT means "lexicographic // order" (the owning dsh-system-prompt schema does the same), while diff --git a/packages/examples/stdio-demo/tests/stdio-agent.spec.ts b/packages/examples/stdio-demo/tests/stdio-agent.spec.ts index ecbff63d2f..4c81eb93e4 100644 --- a/packages/examples/stdio-demo/tests/stdio-agent.spec.ts +++ b/packages/examples/stdio-demo/tests/stdio-agent.spec.ts @@ -142,6 +142,19 @@ describe('dsh-stdio-demo app', () => { await ctx.fiber.dispose() }) + it('forwards maxParallelToolCalls to the bundled agent loop', async () => { + const ctx = await mount({ + provider: 'mock', + model: 'mock', + maxParallelToolCalls: 3, + persistenceRoot: '/tmp/dsh-stdio-demo-spec-parallel', + skills: await isolatedSkillsConfig(), + workspaceContext: false, + }) + expect(ctx.get('agentLoop')?.config.maxParallelToolCalls).toBe(3) + await ctx.fiber.dispose() + }) + it('forwards bundled tool config into agent-core', async () => { const ctx = await mount({ provider: 'mock', diff --git a/packages/fs/tool-fs/README.md b/packages/fs/tool-fs/README.md index 79ebda87fb..2f116a2b71 100644 --- a/packages/fs/tool-fs/README.md +++ b/packages/fs/tool-fs/README.md @@ -46,6 +46,8 @@ The tool passes `exec` (the tool-execution context) as the opaque `actor` on eve `fs/observed` fires AFTER the read/write/edit already succeeded, via a plain `ctx.emit`. A listener is contractually a synchronous, side-effect-only recorder (`@deepseek-ai/dsh-fs-policy`'s is a `WeakMap.set`); the tool does not guard the emit, so a listener that throws would surface as the tool's `isError` result — async or fallible observation does not belong on this event. +`read` opts into concurrent scheduling because its only mutation is the synchronous version recorder. Recorder races fail closed when a later `write` or `edit` re-checks the version under its target lock; both mutation tools remain exclusive. See the [parallel tool-call RFC](../../../docs/rfc/implemented/feature/2026-07-10-parallel-tool-call-execution.md). + The package root exports only the Cordis plugin contract (`name`, `inject`, `Config`, and `apply`). Read rendering (line windowing + output formatting) lives in `src/read-render.ts` (Cordis-free, independently unit-tested); `src/read.ts`/`write.ts`/`edit.ts` are the tool executors and `src/index.ts` composes them. ## Model Experience diff --git a/packages/fs/tool-fs/src/read.ts b/packages/fs/tool-fs/src/read.ts index 63ba070126..a19b073514 100644 --- a/packages/fs/tool-fs/src/read.ts +++ b/packages/fs/tool-fs/src/read.ts @@ -84,6 +84,8 @@ export function applyReadTool(ctx: Context, caps: ReadToolCaps): void { offset: { type: 'number', description: '1-based first line to return. Defaults to 1.' }, limit: { type: 'number', description: `Maximum number of lines to return. Defaults to ${caps.limit}.` }, }, + // Observation races fail closed because guarded mutations re-check the version in-lock. + isConcurrencySafe: () => true, async execute(args, exec): Promise { const input = parseReadArgs(args, caps.limit) const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec)) diff --git a/packages/fs/tool-fs/tests/integration.spec.ts b/packages/fs/tool-fs/tests/integration.spec.ts index 26a81343ff..6a9e6f3568 100644 --- a/packages/fs/tool-fs/tests/integration.spec.ts +++ b/packages/fs/tool-fs/tests/integration.spec.ts @@ -384,6 +384,33 @@ describe('signal, concurrency, and the fs/observed contract', () => { expect(onDisk === 'ONE value here' || onDisk === 'base TWO here').toBe(true) }) + it('a stale observed version from an older read fails closed at edit CAS', async () => { + await writeFile(join(dir, 'a.txt'), 'older content\n') + const target = await ctx.fs.resolve('a.txt') + const firstInfo = await ctx.fs.stat(target) + if (!firstInfo) throw new Error('expected first stat') + + expect((await callOwned('read', { file_path: 'a.txt' })).isError).toBe(false) + + await writeFile(join(dir, 'a.txt'), 'newer current content\n') + const secondInfo = await ctx.fs.stat(target) + if (!secondInfo) throw new Error('expected second stat') + expect(secondInfo.version).not.toBe(firstInfo.version) + expect((await callOwned('read', { file_path: 'a.txt' })).isError).toBe(false) + + // Reproduce an older concurrent read winning the observation race. + ctx.emit('fs/observed', target, firstInfo.version, { agent: { session } }) + + const edit = await callOwned('edit', { + file_path: 'a.txt', + old_string: 'newer', + new_string: 'edited', + }) + expect(edit.isError).toBe(true) + expect(edit.error).toMatchObject({ code: 'FS_STALE_VERSION' }) + expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('newer current content\n') + }) + it('a throwing fs/observed listener surfaces as isError, but the mutation already hit disk', async () => { // fs/observed is a plain ctx.emit after the write succeeded; a throwing listener cannot // roll the write back — it only turns the tool result into isError. diff --git a/packages/fs/tool-fs/tests/tools.spec.ts b/packages/fs/tool-fs/tests/tools.spec.ts index 27c2d5f672..f08db928af 100644 --- a/packages/fs/tool-fs/tests/tools.spec.ts +++ b/packages/fs/tool-fs/tests/tools.spec.ts @@ -108,6 +108,16 @@ describe('registration', () => { expect(ctx.tools.schemas().map(s => s.name).sort()).toEqual(['edit', 'read', 'write']) }) + it('declares read parallel-safe while write/edit remain exclusive', async () => { + const { ctx } = await setup() + expect(ctx.tools.executionMode({ callId: CallId('read-safe'), name: 'read', arguments: { file_path: 'a.txt' } })) + .toEqual({ kind: 'parallel' }) + expect(ctx.tools.executionMode({ callId: CallId('write-exclusive'), name: 'write', arguments: { file_path: 'a.txt', content: 'x' } })) + .toEqual({ kind: 'exclusive' }) + expect(ctx.tools.executionMode({ callId: CallId('edit-exclusive'), name: 'edit', arguments: { file_path: 'a.txt', old_string: 'x', new_string: 'y' } })) + .toEqual({ kind: 'exclusive' }) + }) + it('registers prompt sections for each tool', async () => { const { ctx } = await setup() const prompt = renderPrompt(await ctx.systemPrompt.assemble()) diff --git a/packages/mcp/mcp-client/tests/fixture-server.ts b/packages/mcp/mcp-client/tests/fixture-server.ts index d127412736..8491b96634 100644 --- a/packages/mcp/mcp-client/tests/fixture-server.ts +++ b/packages/mcp/mcp-client/tests/fixture-server.ts @@ -2,7 +2,7 @@ * Minimal MCP server over stdio for e2e testing of the dsh-mcp-client plugin. * Registers controlled tools with predictable behavior for asserting edge cases. * - * Run: node --import tsx fixture-server.ts + * Run: node fixture-server.ts */ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js' diff --git a/packages/mcp/mcp-client/tests/mcp-client.e2e.ts b/packages/mcp/mcp-client/tests/mcp-client.e2e.ts index 686d51acea..dc783b3edf 100644 --- a/packages/mcp/mcp-client/tests/mcp-client.e2e.ts +++ b/packages/mcp/mcp-client/tests/mcp-client.e2e.ts @@ -26,9 +26,7 @@ import { apply } from '@deepseek-ai/dsh-mcp-client/src/index.ts' import { publicToolName } from '@deepseek-ai/dsh-mcp-client/src/tools.ts' import type { Config } from '@deepseek-ai/dsh-mcp-client' -const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) const fixtureServerPath = fileURLToPath(new URL('./fixture-server.ts', import.meta.url)) -const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url)) // Resolve package-local .bin for pnpm-hoisted MCP server binaries. const packageDir = fileURLToPath(new URL('..', import.meta.url)) @@ -86,8 +84,8 @@ describe('fixture server — controlled scenarios', () => { transport: 'stdio', serverName: 'fixture', command: process.execPath, - args: ['--import', tsxLoader, fixtureServerPath], - env: { TSX_TSCONFIG_PATH: repoTsconfig }, + args: [fixtureServerPath], + env: {}, cwd: packageDir, toolCallTimeoutMs: 15_000, } @@ -170,8 +168,8 @@ describe('fixture server — duplicate serverName', () => { transport: 'stdio', serverName: 'dup', command: process.execPath, - args: ['--import', tsxLoader, fixtureServerPath], - env: { TSX_TSCONFIG_PATH: repoTsconfig }, + args: [fixtureServerPath], + env: {}, cwd: packageDir, toolCallTimeoutMs: 15_000, } @@ -191,8 +189,8 @@ describe('fixture server — disposal', () => { transport: 'stdio', serverName: 'fixture', command: process.execPath, - args: ['--import', tsxLoader, fixtureServerPath], - env: { TSX_TSCONFIG_PATH: repoTsconfig }, + args: [fixtureServerPath], + env: {}, cwd: packageDir, toolCallTimeoutMs: 15_000, }) diff --git a/packages/subagent/subagent-acp/package.json b/packages/subagent/subagent-acp/package.json index 5093e3df40..ec55845f91 100644 --- a/packages/subagent/subagent-acp/package.json +++ b/packages/subagent/subagent-acp/package.json @@ -35,6 +35,7 @@ "devDependencies": { "@deepseek-ai/dsh-agent": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", + "@deepseek-ai/dsh-loader-smoke": "workspace:^", "@deepseek-ai/dsh-subagent": "workspace:^", "@deepseek-ai/dsh-subagent-subprocess": "workspace:^", "@cordisjs/plugin-loader": "^1.0.0-rc.5", diff --git a/packages/subagent/subagent-acp/tests/mock-acp-server.ts b/packages/subagent/subagent-acp/tests/mock-acp-server.ts index 000f6d49f0..1496f882aa 100644 --- a/packages/subagent/subagent-acp/tests/mock-acp-server.ts +++ b/packages/subagent/subagent-acp/tests/mock-acp-server.ts @@ -2,8 +2,8 @@ * Minimal no-network ACP child process for keyless backend tests. Environment variables script its * text and stop reason, a cancel-cooperative or cancel-ignoring hang, permission requests, and a * readiness marker. Disposal fixtures can delay an EOF flush, ignore EOF but exit and mark - * SIGTERM, or trap SIGTERM to require SIGKILL. The specs spawn this non-test module under tsx with - * an explicit tsconfig, mirroring real example boot. + * SIGTERM, or trap SIGTERM to require SIGKILL. The specs run this protocol-only fixture directly + * with Node's type stripping; it imports no harness code or workspace paths. * @module @deepseek-ai/dsh-subagent-acp/tests/mock-acp-server */ diff --git a/packages/subagent/subagent-acp/tests/subagent-acp.e2e.ts b/packages/subagent/subagent-acp/tests/subagent-acp.e2e.ts index 0c20b27fa1..688b1c44aa 100644 --- a/packages/subagent/subagent-acp/tests/subagent-acp.e2e.ts +++ b/packages/subagent/subagent-acp/tests/subagent-acp.e2e.ts @@ -6,6 +6,7 @@ import { afterEach, describe, expect, it } from 'vitest' import { Context } from 'cordis' import type { Agent } from '@deepseek-ai/dsh-agent' import SubagentService from '@deepseek-ai/dsh-subagent' +import { resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke' import * as acp from '../src/index.ts' /** @@ -17,9 +18,22 @@ import * as acp from '../src/index.ts' // The real acp-agent example: its bin + cordis.yml (the live DeepSeek config). const binScript = fileURLToPath(new URL('../../../examples/acp-demo/src/bin.ts', import.meta.url)) const exampleConfig = fileURLToPath(new URL('../../../../examples/acp-agent/cordis.yml', import.meta.url)) -const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url)) +// How to launch the child acp-agent (src via tsx / lib via plain node, per DSH_EXAMPLE_MODE). +// buildChildEnv scrubs ambient creds but keeps these extras, so the model key is +// forwarded explicitly; TSX_TSCONFIG_PATH is added by the resolver in src mode only. +const childLaunch = resolveExampleLaunch({ + srcBin: binScript, + configArgs: ['--config', exampleConfig], + tsconfigPath: repoTsconfig, + env: { + ...process.env.DEEPSEEK_API_KEY !== undefined ? { DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY } : {}, + ...process.env.DEEPSEEK_BASE_URL !== undefined ? { DEEPSEEK_BASE_URL: process.env.DEEPSEEK_BASE_URL } : {}, + DSH_PERMISSION_MODE: 'danger-full-access', + }, +}) + /** The ACP backend ignores the parent, but the seam requires one. */ const fakeParent = { id: 'parent', session: { header: {} } } as unknown as Agent @@ -40,18 +54,11 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('ACP backend with-key e2e (drive await ctx.plugin(SubagentService) await ctx.plugin(acp, { providerName: 'acp', - command: process.execPath, - args: ['--import', tsxLoader, binScript, '--config', exampleConfig], + command: childLaunch.command, + args: childLaunch.args, cwd: workdir, permission: 'reject', - // The child harness needs the key to reach the model; forward it - // explicitly (buildChildEnv scrubs ambient creds but keeps these extras). - env: { - ...process.env.DEEPSEEK_API_KEY !== undefined ? { DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY } : {}, - ...process.env.DEEPSEEK_BASE_URL !== undefined ? { DEEPSEEK_BASE_URL: process.env.DEEPSEEK_BASE_URL } : {}, - TSX_TSCONFIG_PATH: repoTsconfig, - DSH_PERMISSION_MODE: 'danger-full-access', - }, + env: childLaunch.env as Record, }) const run = await ctx.subagents.start('acp', { @@ -76,17 +83,12 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('ACP backend with-key e2e (drive await ctx.plugin(SubagentService) await ctx.plugin(acp, { providerName: 'acp', - command: process.execPath, - args: ['--import', tsxLoader, binScript, '--config', exampleConfig], + command: childLaunch.command, + args: childLaunch.args, cwd: workdir, // The child needs to act (run bash), so approve its permission prompts. permission: 'allow', - env: { - ...process.env.DEEPSEEK_API_KEY !== undefined ? { DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY } : {}, - ...process.env.DEEPSEEK_BASE_URL !== undefined ? { DEEPSEEK_BASE_URL: process.env.DEEPSEEK_BASE_URL } : {}, - TSX_TSCONFIG_PATH: repoTsconfig, - DSH_PERMISSION_MODE: 'danger-full-access', - }, + env: childLaunch.env as Record, }) const run = await ctx.subagents.start('acp', { diff --git a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts index eed3cfe1ed..bfc8476bae 100644 --- a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts +++ b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts @@ -21,8 +21,6 @@ import { acpStopReason, acpContentText, DEFAULT_DISPOSE_EOF_GRACE_MS, DEFAULT_DI */ const mockServer = fileURLToPath(new URL('./mock-acp-server.ts', import.meta.url)) -const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) -const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url)) /** A throwaway parent Agent — the ACP backend ignores it, but the seam requires one. */ const fakeParent = { id: 'parent', session: { header: {} } } as unknown as Agent @@ -46,11 +44,9 @@ async function setup(mockEnv: SetupEnv = {}, permission: 'allow' | 'reject' = 'r await ctx.plugin(acp, { providerName: 'acp', command: process.execPath, - args: ['--import', tsxLoader, mockServer], + args: [mockServer], permission, - // The mock-server scripting vars must reach the child; TSX_TSCONFIG_PATH lets - // tsx resolve @deepseek-ai/* from a child cwd outside the repo. - env: { ...mockEnv, TSX_TSCONFIG_PATH: repoTsconfig }, + env: mockEnv, }) return ctx } @@ -197,10 +193,10 @@ describe('dsh-subagent-acp', () => { try { const spec: AcpRunSpec = { command: process.execPath, - args: ['--import', tsxLoader, mockServer], + args: [mockServer], cwd: process.cwd(), permission: 'reject', - env: { MOCK_TRAP_SIGTERM: '1', MOCK_TEXT: 'x', MOCK_READY_FILE: ready, TSX_TSCONFIG_PATH: repoTsconfig }, + env: { MOCK_TRAP_SIGTERM: '1', MOCK_TEXT: 'x', MOCK_READY_FILE: ready }, // Short on BOTH tiers: the trap ignores EOF and SIGTERM, so dispose must // burn the EOF window, then the SIGTERM window, then SIGKILL — keep each // small so the whole ladder finishes well within the 4000ms bound. @@ -240,7 +236,7 @@ describe('dsh-subagent-acp', () => { try { const spec: AcpRunSpec = { command: process.execPath, - args: ['--import', tsxLoader, mockServer], + args: [mockServer], cwd: process.cwd(), permission: 'reject', // MOCK_HANG so the prompt never resolves on its own — we tear down a live @@ -249,7 +245,7 @@ describe('dsh-subagent-acp', () => { // wider grace. env: { MOCK_HANG: '1', MOCK_TEXT: 'x', MOCK_READY_FILE: ready, - MOCK_FLUSH_ON_EOF: flushed, MOCK_FLUSH_DELAY_MS: '400', TSX_TSCONFIG_PATH: repoTsconfig, + MOCK_FLUSH_ON_EOF: flushed, MOCK_FLUSH_DELAY_MS: '400', }, disposeEofGraceMs: 2000, disposeGraceMs: 50, @@ -280,12 +276,12 @@ describe('dsh-subagent-acp', () => { try { const spec: AcpRunSpec = { command: process.execPath, - args: ['--import', tsxLoader, mockServer], + args: [mockServer], cwd: process.cwd(), permission: 'reject', env: { MOCK_HANG: '1', MOCK_IGNORE_EOF: '1', MOCK_TEXT: 'x', - MOCK_READY_FILE: ready, MOCK_SIGTERM_FILE: sigterm, TSX_TSCONFIG_PATH: repoTsconfig, + MOCK_READY_FILE: ready, MOCK_SIGTERM_FILE: sigterm, }, // Tiny EOF grace so the ignored-EOF window elapses fast, then SIGTERM. disposeEofGraceMs: 150, @@ -404,9 +400,9 @@ describe('dsh-subagent-acp', () => { await ctx.plugin(acp, { providerName: 'acp', command: process.execPath, - args: ['--import', tsxLoader, mockServer], + args: [mockServer], permission: 'reject', - env: { MOCK_TRAP_SIGTERM: '1', MOCK_TEXT: 'x', MOCK_READY_FILE: ready, TSX_TSCONFIG_PATH: repoTsconfig }, + env: { MOCK_TRAP_SIGTERM: '1', MOCK_TEXT: 'x', MOCK_READY_FILE: ready }, disposeEofGraceMs: 150, disposeGraceMs: 150, }) @@ -455,10 +451,10 @@ describe('dsh-subagent-acp', () => { request(), { command: process.execPath, - args: ['--import', tsxLoader, mockServer], + args: [mockServer], cwd: process.cwd(), permission: 'reject', - env: { MOCK_CRASH_ON_PROMPT: '1', TSX_TSCONFIG_PATH: repoTsconfig }, + env: { MOCK_CRASH_ON_PROMPT: '1' }, disposeEofGraceMs: DEFAULT_DISPOSE_EOF_GRACE_MS, disposeGraceMs: DEFAULT_DISPOSE_GRACE_MS, onError: (error, stopReason) => { errors.push({ message: error.message, stopReason }) }, @@ -493,10 +489,10 @@ describe('dsh-subagent-acp', () => { request(), { command: process.execPath, - args: ['--import', tsxLoader, mockServer], + args: [mockServer], cwd: process.cwd(), permission: 'reject', - env: { MOCK_CRASH_ON_PROMPT: '1', TSX_TSCONFIG_PATH: repoTsconfig }, + env: { MOCK_CRASH_ON_PROMPT: '1' }, disposeEofGraceMs: DEFAULT_DISPOSE_EOF_GRACE_MS, disposeGraceMs: DEFAULT_DISPOSE_GRACE_MS, onError: () => { throw new Error('sink boom') }, diff --git a/packages/subagent/subagent-acp/tsconfig.json b/packages/subagent/subagent-acp/tsconfig.json index e415ace1de..5aa28528ac 100644 --- a/packages/subagent/subagent-acp/tsconfig.json +++ b/packages/subagent/subagent-acp/tsconfig.json @@ -28,6 +28,9 @@ }, { "path": "../subagent-subprocess" + }, + { + "path": "../../support/loader-smoke" } ] } diff --git a/packages/subagent/tool-subagent/README.md b/packages/subagent/tool-subagent/README.md index b125839d75..825e252923 100644 --- a/packages/subagent/tool-subagent/README.md +++ b/packages/subagent/tool-subagent/README.md @@ -24,6 +24,10 @@ With `run_in_background: true`, the tool registers the parent-owned task before | `toolFilter` | Per-child global-tool restriction; requires `toolFilter` capability. | | `maxDepth` | Absolute delegation-depth cap; requires `depthLimit` capability. | +## Concurrency + +Foreground and background calls are exclusive. Children may share the parent's workspace or external resources, and a unary classifier cannot prove that sibling delegations have disjoint effects. See the [parallel tool-call RFC](../../../docs/rfc/implemented/feature/2026-07-10-parallel-tool-call-execution.md). + ## Model Experience ### Tool schema diff --git a/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts b/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts index 9a5f369f8b..90f84bfceb 100644 --- a/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts +++ b/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts @@ -96,6 +96,20 @@ describe('dsh-tool-subagent', () => { expect(foreground.isError).toBe(false) }) + it('keeps foreground and background calls exclusive', async () => { + const ctx = await setup({ provider: 'mock' }) + expect(ctx.tools.executionMode({ + callId: CallId('subagent-foreground'), + name: 'subagent', + arguments: { description: 'do work', prompt: 'Reply OK' }, + })).toEqual({ kind: 'exclusive' }) + expect(ctx.tools.executionMode({ + callId: CallId('subagent-background'), + name: 'subagent', + arguments: { description: 'do work', prompt: 'Reply OK', run_in_background: true }, + })).toEqual({ kind: 'exclusive' }) + }) + it.each([ { stopReason: 'aborted' as const, fragment: 'cancelled' }, { stopReason: 'error' as const, fragment: 'failed' }, diff --git a/packages/support/acp-snapshot/package.json b/packages/support/acp-snapshot/package.json index d206b08161..eb6b46deaf 100644 --- a/packages/support/acp-snapshot/package.json +++ b/packages/support/acp-snapshot/package.json @@ -23,7 +23,7 @@ "license": "BSD-3-Clause", "dependencies": { "@agentclientprotocol/sdk": "0.25.1", - "tsx": "^4.22.4", + "@deepseek-ai/dsh-loader-smoke": "workspace:*", "vitest": "^4.1.8" }, "peerDependencies": { diff --git a/packages/support/acp-snapshot/src/harness.ts b/packages/support/acp-snapshot/src/harness.ts index c26cb84299..e2072b6b17 100644 --- a/packages/support/acp-snapshot/src/harness.ts +++ b/packages/support/acp-snapshot/src/harness.ts @@ -11,7 +11,6 @@ import { cp, mkdtemp, readFile, readdir, rm } from 'node:fs/promises' import { existsSync } from 'node:fs' import { tmpdir } from 'node:os' import { join, delimiter } from 'node:path' -import { fileURLToPath } from 'node:url' import { Readable, Writable } from 'node:stream' import { ClientSideConnection, @@ -23,12 +22,7 @@ import { type RequestPermissionResponse, type SessionNotification, } from '@agentclientprotocol/sdk' - -// Resolve tsx's ESM loader to an ABSOLUTE path once: the child runs with its -// cwd in a temp dir OUTSIDE the repo, where a bare `--import tsx` would not -// resolve from node_modules. import.meta.resolve gives this package's tsx -// regardless of the child cwd. -const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) +import { resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke' /** * The agent composition a scenario runs against: which bin to boot and which @@ -37,8 +31,10 @@ const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) * them from its own `import.meta.url`. */ export interface AgentUnderTest { - /** The agent bin entry (e.g. `packages/examples/acp-demo/src/bin.ts`), run unbuilt via tsx. */ + /** The agent bin's SOURCE entry (e.g. `packages/examples/acp-demo/src/bin.ts`); the `lib` bin is derived from it. */ binScript: string + /** Explicit plain-Node entry for `lib` mode; intended for test fixtures outside a package `src/` tree. */ + libBinScript?: string | undefined /** * The example's live `cordis.yml`. Under `DSH_SNAPSHOT=replay` the bin swaps * it for the sibling `cordis.snapshot.yml` (the keyless replay overlay), so @@ -47,10 +43,8 @@ export interface AgentUnderTest { configPath: string /** * The repo-root tsconfig whose `paths` map resolves the unbuilt workspace - * imports. Passed to the child as `TSX_TSCONFIG_PATH`: tsx finds a tsconfig - * by searching UP from the child's cwd — a temp dir outside the repo — so - * without the explicit pin the dsh-* imports fail before the bin writes a - * byte. + * imports in `src` mode (passed to the child as `TSX_TSCONFIG_PATH`). Ignored + * in `lib` mode, where the example resolves plugins through real `exports`. */ tsconfigPath: string } @@ -184,25 +178,32 @@ export async function runScenario(input: InputScript, opts: RunOptions): Promise if (opts.workspaceDir !== undefined && existsSync(opts.workspaceDir)) { await cp(opts.workspaceDir, cwd, { recursive: true }) } - const env: NodeJS.ProcessEnv = { - ...process.env, - TSX_TSCONFIG_PATH: opts.agent.tsconfigPath, - DSH_SNAPSHOT: opts.mode, - DSH_SNAPSHOT_FILE: opts.fixtureFile, - DSH_SNAPSHOT_SESSIONS_ROOT: sessionsRoot, - DSH_SNAPSHOT_SPILL_ROOT: spillRoot, - DSH_HOME: join(cwd, '.dsh'), - DSH_AGENTS_HOME: join(cwd, '.agents'), - ...opts.overrideFile !== undefined ? { DSH_SNAPSHOT_OVERRIDE: opts.overrideFile } : {}, - ...opts.childFiles !== undefined && opts.childFiles.length > 0 - ? { DSH_SNAPSHOT_CHILD_FILES: opts.childFiles.join(delimiter) } - : {}, - } + // Boot the agent in the environment's mode (DSH_EXAMPLE_MODE): `src` runs the + // source bin under tsx with the paths map; `lib` runs the built bin under plain + // Node, resolving plugins through the example's workspace node_modules → lib. + const launch = resolveExampleLaunch({ + srcBin: opts.agent.binScript, + libBin: opts.agent.libBinScript, + configArgs: ['--config', opts.configPath ?? opts.agent.configPath], + tsconfigPath: opts.agent.tsconfigPath, + env: { + DSH_SNAPSHOT: opts.mode, + DSH_SNAPSHOT_FILE: opts.fixtureFile, + DSH_SNAPSHOT_SESSIONS_ROOT: sessionsRoot, + DSH_SNAPSHOT_SPILL_ROOT: spillRoot, + DSH_HOME: join(cwd, '.dsh'), + DSH_AGENTS_HOME: join(cwd, '.agents'), + ...opts.overrideFile !== undefined ? { DSH_SNAPSHOT_OVERRIDE: opts.overrideFile } : {}, + ...opts.childFiles !== undefined && opts.childFiles.length > 0 + ? { DSH_SNAPSHOT_CHILD_FILES: opts.childFiles.join(delimiter) } + : {}, + }, + }) child = spawn( - process.execPath, - ['--import', tsxLoader, opts.agent.binScript, '--config', opts.configPath ?? opts.agent.configPath], - { cwd, env, stdio: ['pipe', 'pipe', 'pipe'] }, + launch.command, + launch.args, + { cwd, env: { ...process.env, ...launch.env }, stdio: ['pipe', 'pipe', 'pipe'] }, ) child.stderr.setEncoding('utf8') diff --git a/packages/support/acp-snapshot/tests/harness.spec.ts b/packages/support/acp-snapshot/tests/harness.spec.ts index 42ccbd7de4..1d953f5e95 100644 --- a/packages/support/acp-snapshot/tests/harness.spec.ts +++ b/packages/support/acp-snapshot/tests/harness.spec.ts @@ -14,10 +14,12 @@ import { runScenario, type AgentUnderTest, type InputStep } from '../src/harness * assertions read plain `rawStdout`. */ +const fakeAgent = fileURLToPath(new URL('./fixtures/fake-acp-agent.ts', import.meta.url)) const AGENT: AgentUnderTest = { - binScript: fileURLToPath(new URL('./fixtures/fake-acp-agent.ts', import.meta.url)), + binScript: fakeAgent, + libBinScript: fakeAgent, // The fake bin ignores its config argv; any real path documents the shape. - configPath: fileURLToPath(new URL('./fixtures/fake-acp-agent.ts', import.meta.url)), + configPath: fakeAgent, tsconfigPath: fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url)), } diff --git a/packages/support/acp-snapshot/tests/suite.spec.ts b/packages/support/acp-snapshot/tests/suite.spec.ts index 89af6c6614..4cedc1cdfb 100644 --- a/packages/support/acp-snapshot/tests/suite.spec.ts +++ b/packages/support/acp-snapshot/tests/suite.spec.ts @@ -32,9 +32,11 @@ import { * spec once with `ACP_SNAPSHOT_SPEC_BOOTSTRAP=1`, then review and commit the resulting tree. */ +const fakeAgent = fileURLToPath(new URL('./fixtures/fake-acp-agent.ts', import.meta.url)) const AGENT = { - binScript: fileURLToPath(new URL('./fixtures/fake-acp-agent.ts', import.meta.url)), - configPath: fileURLToPath(new URL('./fixtures/fake-acp-agent.ts', import.meta.url)), + binScript: fakeAgent, + libBinScript: fakeAgent, + configPath: fakeAgent, tsconfigPath: fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url)), } diff --git a/packages/support/acp-snapshot/tsconfig.json b/packages/support/acp-snapshot/tsconfig.json index 749cb0208e..9120df0ad1 100644 --- a/packages/support/acp-snapshot/tsconfig.json +++ b/packages/support/acp-snapshot/tsconfig.json @@ -7,5 +7,7 @@ "include": [ "src" ], - "references": [] + "references": [ + { "path": "../loader-smoke" } + ] } diff --git a/packages/support/loader-smoke/README.md b/packages/support/loader-smoke/README.md index ea197b25d0..04f519b4c1 100644 --- a/packages/support/loader-smoke/README.md +++ b/packages/support/loader-smoke/README.md @@ -1,10 +1,10 @@ # `@deepseek-ai/dsh-loader-smoke` -Shared subprocess harness for keyless example smokes that boot the real stdio-agent bin and a real `cordis.yml` through the Cordis Loader. A test supplies absolute bin/config/tsconfig paths, optional environment overrides, and stdin lines; `runLoaderSmoke` owns the isolated cwd, DSH homes, tsx path resolution, 30-second process deadline, captured diagnostics, forced kill, EOF, and cleanup. +Shared subprocess harness for tests that boot an app and `cordis.yml` through the Cordis Loader. `resolveExampleLaunch` selects local `src` mode (tsx and root tsconfig paths) or CI `lib` mode (plain Node and package exports) from an explicit mode or `DSH_EXAMPLE_MODE`. -Successful runs return stdout and stderr only after a zero exit. Non-zero exits and deadlines reject with both captured streams. `LOADER_SMOKE_TEST_TIMEOUT_MS` leaves Vitest enough room for the process-owned diagnostic timeout to fire first. +`runLoaderSmoke` owns the isolated cwd, DSH homes, stdin, diagnostics, deadline, termination, and cleanup. It returns both streams after a zero exit and rejects with both streams on failure. -This is support-tier test infrastructure, not product API. The consumers are the Loader-path smokes under `examples/{echo-agent,coding-agent,cordis-agent}`. +This is support-tier test infrastructure, not product API. ## Model Experience @@ -12,6 +12,6 @@ None, as this test-only harness boots example processes and inspects their strea ## Known Limitations and Deferred Work -- **Only the unbuilt tsx/Loader path is exercised** — built-bin artifacts remain the responsibility of their separate e2e smokes. +- **Built mode requires a prior build** — the config must also resolve every named package upward through `examples/node_modules`. - **Captured stdout and stderr are unbounded** — a runaway child can consume memory until the deadline kills it. - **Timeout kills only the direct child** — a process tree spawned by a faulty fixture can outlive the smoke and needs external cleanup. diff --git a/packages/support/loader-smoke/src/index.ts b/packages/support/loader-smoke/src/index.ts index 72839c6a05..edbe39d8ca 100644 --- a/packages/support/loader-smoke/src/index.ts +++ b/packages/support/loader-smoke/src/index.ts @@ -2,6 +2,14 @@ * Shared subprocess harness for keyless example smokes that boot a real * `cordis.yml` through the stdio-agent bin and Cordis Loader. * + * It also owns the mode-aware launch resolver every example subprocess harness shares + * ({@link resolveExampleLaunch}): booting an example bin from TypeScript source under `tsx` (the + * zero-build dev path, resolving `@deepseek-ai/dsh-*` / `@cordisjs/*` through the tsconfig `paths` + * map) or from built `lib/` under plain Node (resolving bare packages through real `exports`, as an + * installed consumer does, while Node type-strips relative example-local TypeScript plugins). + * Consolidating that spawn glue here retires the copies in the ACP snapshot harness and the example + * e2e drivers (the `TODO(acp-test-harness)`). + * * @module @deepseek-ai/dsh-loader-smoke */ @@ -9,26 +17,125 @@ import { spawn } from 'node:child_process' import { mkdtemp, rm } from 'node:fs/promises' import { tmpdir } from 'node:os' import { join } from 'node:path' -import { fileURLToPath } from 'node:url' const DEFAULT_PROCESS_TIMEOUT_MS = 30_000 -const TSX_LOADER = fileURLToPath(import.meta.resolve('tsx')) /** Vitest deadline that leaves room for the subprocess-owned 30-second diagnostic timeout. */ export const LOADER_SMOKE_TEST_TIMEOUT_MS = DEFAULT_PROCESS_TIMEOUT_MS + 15_000 +/** Which artifact an example bin is booted from: unbuilt `src` via tsx, or built `lib` via plain Node. */ +export type ExampleMode = 'src' | 'lib' + +/** Environment variable selecting the mode; CI and pre-push set it to `lib`, dev leaves it unset (`src`). */ +export const EXAMPLE_MODE_ENV = 'DSH_EXAMPLE_MODE' + +/** + * Parse an {@link ExampleMode} from a raw string, defaulting to `src` when absent so an unset + * environment reproduces the dev/tsx behavior. Throws on any other value rather than silently + * falling back, so a typo in a gate's env fails loud. + * @param raw - the raw value; defaults to `process.env.DSH_EXAMPLE_MODE`. + * @returns the validated mode. + */ +export function resolveExampleMode(raw: string | undefined = process.env[EXAMPLE_MODE_ENV]): ExampleMode { + switch (raw) { + case undefined: + case '': + case 'src': + return 'src' + case 'lib': + return 'lib' + default: + throw new Error(`${EXAMPLE_MODE_ENV} must be 'src' or 'lib', got ${JSON.stringify(raw)}.`) + } +} + +/** Inputs to {@link resolveExampleLaunch}. */ +export interface ExampleLaunchOptions { + /** Absolute path to the example bin's TypeScript source entry (`/src/bin.ts`); the `lib` bin is derived from it. */ + readonly srcBin: string + /** Explicit plain-Node entry for `lib` mode; test fixtures may point this at Node-type-strippable TypeScript. */ + readonly libBin?: string | undefined + /** Arguments passed after the bin — the config, positional (`[configPath]`) or flagged (`['--config', configPath]`). */ + readonly configArgs?: readonly string[] + /** The mode to launch in; defaults to {@link resolveExampleMode} of the environment. */ + readonly mode?: ExampleMode + /** Absolute repo tsconfig whose `paths` map resolves unbuilt workspace imports. Required in `src` mode, ignored in `lib`. */ + readonly tsconfigPath?: string + /** Prepend `--expose-internals` (the Cordis Loader's bare-plugin resolver needs it for some bins); defaults to `false`. */ + readonly exposeInternals?: boolean + /** Extra environment entries the mode-specific ones layer over; the caller then merges the result over `process.env`. */ + readonly env?: NodeJS.ProcessEnv +} + +/** The resolved spawn: `spawn(command, args, { env: { ...process.env, ...env } })`. */ +export interface ExampleLaunch { + /** The executable to spawn — always the current Node binary. */ + readonly command: string + /** Node flags, the resolved bin, then the caller's `configArgs`. */ + readonly args: string[] + /** Mode-specific environment (`TSX_TSCONFIG_PATH` in `src`, nothing added in `lib`) layered over the caller's `env`. */ + readonly env: NodeJS.ProcessEnv +} + +/** Derive the built-lib bin (`/lib/.js`) from a source bin (`/src/.ts`). */ +function toLibBin(srcBin: string): string { + const markerLength = '/src/'.length + const cut = Math.max(srcBin.lastIndexOf('/src/'), srcBin.lastIndexOf('\\src\\')) + if (cut === -1) { + throw new Error(`resolveExampleLaunch: expected a "/src/" segment or Windows equivalent in bin path ${JSON.stringify(srcBin)}.`) + } + const separator = srcBin.slice(cut, cut + 1) + const tail = srcBin.slice(cut + markerLength).replace(/\.ts$/, '.js') + return `${srcBin.slice(0, cut)}${separator}lib${separator}${tail}` +} + +/** + * Resolve how to spawn an example bin in the selected mode. + * + * `src` yields `node [--expose-internals] --import ` with `TSX_TSCONFIG_PATH` + * set so the tsconfig `paths` map resolves workspace imports to source. `lib` yields + * `node [--expose-internals] ` under plain Node with no tsx and no paths map, so + * bare package plugins resolve through real package `exports` into built `lib/`; relative example-local + * TypeScript plugins remain source files loaded through Node's built-in type stripping. Bare resolution + * requires the config to live below a workspace that declares its `cordis.yml` package dependencies. + * + * @param options - the source bin, config arguments, mode, and environment. + * @returns the command, argument vector, and mode-specific environment to spawn with. + */ +export function resolveExampleLaunch(options: ExampleLaunchOptions): ExampleLaunch { + const mode = options.mode ?? resolveExampleMode() + const configArgs = options.configArgs ?? [] + const flags = options.exposeInternals === true ? ['--expose-internals'] : [] + const env: NodeJS.ProcessEnv = { ...options.env } + + if (mode === 'src') { + if (options.tsconfigPath === undefined) { + throw new Error("resolveExampleLaunch: 'src' mode needs tsconfigPath for the workspace paths map.") + } + const tsxLoader = import.meta.resolve('tsx') + env.TSX_TSCONFIG_PATH = options.tsconfigPath + return { command: process.execPath, args: [...flags, '--import', tsxLoader, options.srcBin, ...configArgs], env } + } + + return { command: process.execPath, args: [...flags, options.libBin ?? toLibBin(options.srcBin), ...configArgs], env } +} + /** Inputs that vary between real-Loader example smokes. */ export interface LoaderSmokeOptions { /** Human-readable example name used in failure diagnostics. */ readonly label: string /** Prefix for the isolated temporary process cwd. */ readonly tempDirPrefix: string - /** Absolute stdio-agent bin path. */ + /** Absolute stdio-agent bin SOURCE path (`/src/bin.ts`); the `lib` bin is derived from it. */ readonly binScript: string + /** Explicit plain-Node entry for `lib` mode; intended for test fixtures outside a package `src/` tree. */ + readonly libBinScript?: string | undefined /** Absolute real Loader config path. */ readonly configPath: string - /** Absolute repo tsconfig path used for unbuilt workspace-package resolution. */ + /** Absolute repo tsconfig path used for unbuilt workspace-package resolution (required in `src` mode). */ readonly tsconfigPath: string + /** Boot from source via tsx (`src`) or built lib via plain Node (`lib`); defaults to the environment's mode. */ + readonly mode?: ExampleMode /** Environment overrides layered over the parent and isolated DSH homes. */ readonly env?: Readonly /** Lines written to stdin before EOF; omitted means immediate EOF. */ @@ -48,30 +155,29 @@ export interface LoaderSmokeResult { /** * Boot one real Loader tree from an isolated cwd, write the requested stdin * script, close stdin, and await a clean exit. The helper owns process kill and - * temp-directory cleanup on every outcome. - * @param options - example paths, environment, stdin, and diagnostic identity. + * temp-directory cleanup on every outcome, and picks src/lib via {@link resolveExampleLaunch}. + * @param options - example paths, mode, environment, stdin, and diagnostic identity. * @returns captured stdout and stderr after a zero exit. */ export async function runLoaderSmoke(options: LoaderSmokeOptions): Promise { const cwd = await mkdtemp(join(tmpdir(), options.tempDirPrefix)) const processTimeoutMs = options.processTimeoutMs ?? DEFAULT_PROCESS_TIMEOUT_MS + const launch = resolveExampleLaunch({ + srcBin: options.binScript, + libBin: options.libBinScript, + configArgs: [options.configPath], + ...options.mode !== undefined ? { mode: options.mode } : {}, + tsconfigPath: options.tsconfigPath, + exposeInternals: true, + env: { DSH_HOME: join(cwd, '.dsh'), DSH_AGENTS_HOME: join(cwd, '.agents'), ...options.env }, + }) try { return await new Promise((resolve, reject) => { - const child = spawn( - process.execPath, - ['--expose-internals', '--import', TSX_LOADER, options.binScript, options.configPath], - { - cwd, - env: { - ...process.env, - DSH_HOME: join(cwd, '.dsh'), - DSH_AGENTS_HOME: join(cwd, '.agents'), - ...options.env, - TSX_TSCONFIG_PATH: options.tsconfigPath, - }, - stdio: ['pipe', 'pipe', 'pipe'], - }, - ) + const child = spawn(launch.command, launch.args, { + cwd, + env: { ...process.env, ...launch.env }, + stdio: ['pipe', 'pipe', 'pipe'], + }) let stdout = '' let stderr = '' let deferredFailure: Error | undefined diff --git a/packages/support/loader-smoke/tests/example-launch.spec.ts b/packages/support/loader-smoke/tests/example-launch.spec.ts new file mode 100644 index 0000000000..20520e6fb6 --- /dev/null +++ b/packages/support/loader-smoke/tests/example-launch.spec.ts @@ -0,0 +1,111 @@ +import { afterEach, describe, expect, it } from 'vitest' +import { + EXAMPLE_MODE_ENV, + resolveExampleLaunch, + resolveExampleMode, +} from '@deepseek-ai/dsh-loader-smoke' + +const SRC_BIN = '/repo/packages/examples/stdio-demo/src/bin.ts' +const TSCONFIG = '/repo/tsconfig.json' + +const originalMode = process.env[EXAMPLE_MODE_ENV] +afterEach(() => { + if (originalMode === undefined) Reflect.deleteProperty(process.env, EXAMPLE_MODE_ENV) + else process.env[EXAMPLE_MODE_ENV] = originalMode +}) + +describe('resolveExampleMode', () => { + it('defaults absent/empty/src to src', () => { + Reflect.deleteProperty(process.env, EXAMPLE_MODE_ENV) + expect(resolveExampleMode()).toBe('src') + expect(resolveExampleMode('')).toBe('src') + expect(resolveExampleMode('src')).toBe('src') + }) + + it('accepts lib', () => { + expect(resolveExampleMode('lib')).toBe('lib') + }) + + it('throws on any other value', () => { + expect(() => resolveExampleMode('prod')).toThrow(/must be 'src' or 'lib'/) + }) + + it('reads the environment when no argument is given', () => { + process.env[EXAMPLE_MODE_ENV] = 'lib' + expect(resolveExampleMode()).toBe('lib') + Reflect.deleteProperty(process.env, EXAMPLE_MODE_ENV) + expect(resolveExampleMode()).toBe('src') + }) +}) + +describe('resolveExampleLaunch', () => { + it('src mode: --import tsx on the source bin with the tsconfig paths env', () => { + const { command, args, env } = resolveExampleLaunch({ + srcBin: SRC_BIN, + configArgs: ['./cordis.yml'], + mode: 'src', + tsconfigPath: TSCONFIG, + }) + expect(command).toBe(process.execPath) + expect(args).toContain('--import') + expect(args).toContain(SRC_BIN) + expect(args[args.length - 1]).toBe('./cordis.yml') + expect(args).not.toContain('--expose-internals') + expect(env.TSX_TSCONFIG_PATH).toBe(TSCONFIG) + }) + + it('src mode: throws without a tsconfig path', () => { + expect(() => resolveExampleLaunch({ srcBin: SRC_BIN, mode: 'src' })).toThrow(/needs tsconfigPath/) + }) + + it('lib mode: plain node on the derived lib bin, no tsx and no paths env', () => { + const { args, env } = resolveExampleLaunch({ + srcBin: SRC_BIN, + configArgs: ['--config', './cordis.yml'], + mode: 'lib', + env: { DSH_HOME: '/tmp/home' }, + }) + expect(args).not.toContain('--import') + expect(args).toContain('/repo/packages/examples/stdio-demo/lib/bin.js') + expect(args.slice(-2)).toEqual(['--config', './cordis.yml']) + expect(env.TSX_TSCONFIG_PATH).toBeUndefined() + expect(env.DSH_HOME).toBe('/tmp/home') + }) + + it('lib mode: uses an explicit plain-Node bin when provided', () => { + const fixture = '/repo/fixture.ts' + const { args } = resolveExampleLaunch({ srcBin: fixture, libBin: fixture, mode: 'lib' }) + expect(args).toContain(fixture) + }) + + it('prepends --expose-internals when requested', () => { + const { args } = resolveExampleLaunch({ srcBin: SRC_BIN, mode: 'lib', exposeInternals: true }) + expect(args[0]).toBe('--expose-internals') + }) + + it('lib mode: rewrites only the last /src/ segment', () => { + const { args } = resolveExampleLaunch({ + srcBin: '/repo/src/packages/examples/acp-demo/src/bin.ts', + mode: 'lib', + }) + expect(args).toContain('/repo/src/packages/examples/acp-demo/lib/bin.js') + }) + + it('lib mode: derives the built bin from a Windows source path', () => { + const { args } = resolveExampleLaunch({ + srcBin: String.raw`D:\repo\src\packages\examples\acp-demo\src\bin.ts`, + mode: 'lib', + }) + expect(args).toContain(String.raw`D:\repo\src\packages\examples\acp-demo\lib\bin.js`) + }) + + it('lib mode: throws when the bin has no /src/ segment', () => { + expect(() => resolveExampleLaunch({ srcBin: '/repo/lib/bin.js', mode: 'lib' })).toThrow(/"\/src\/" segment/) + }) + + it('defaults the mode from the environment', () => { + process.env[EXAMPLE_MODE_ENV] = 'lib' + const { args } = resolveExampleLaunch({ srcBin: SRC_BIN }) + expect(args).toContain('/repo/packages/examples/stdio-demo/lib/bin.js') + }) +}) diff --git a/packages/support/loader-smoke/tests/loader-smoke.spec.ts b/packages/support/loader-smoke/tests/loader-smoke.spec.ts index 4cc9f878f9..b99d810188 100644 --- a/packages/support/loader-smoke/tests/loader-smoke.spec.ts +++ b/packages/support/loader-smoke/tests/loader-smoke.spec.ts @@ -16,6 +16,7 @@ describe('runLoaderSmoke', () => { binScript: fixture('success'), configPath, tsconfigPath, + mode: 'src', env: { LOADER_SMOKE_MARKER: 'present' }, stdinLines: ['one', 'two'], }) @@ -43,6 +44,7 @@ describe('runLoaderSmoke', () => { label: 'failure fixture', tempDirPrefix: 'loader-smoke-fail-', binScript: fixture('fail'), + libBinScript: fixture('fail'), configPath, tsconfigPath, })).rejects.toThrow('failure fixture exited 7. stdout:\n\nstderr:\nfixture failed') @@ -53,6 +55,7 @@ describe('runLoaderSmoke', () => { label: 'hanging fixture', tempDirPrefix: 'loader-smoke-hang-', binScript: fixture('hang'), + libBinScript: fixture('hang'), configPath, tsconfigPath, processTimeoutMs: 100, diff --git a/packages/web/tool-web/README.md b/packages/web/tool-web/README.md index 4935751082..ecc3d3e218 100644 --- a/packages/web/tool-web/README.md +++ b/packages/web/tool-web/README.md @@ -11,6 +11,8 @@ Each tool is registered independently; a product that wants only one disables th | `web_search` | `query` (string) | Discovery. Returns an optional answer plus source URLs. `max_results` is **not** model-facing — the tool sets the bound (the `searchMaxResults` config, default 8) and passes it to the seam. | | `web_fetch` | `url` (string) | Retrieves a specific URL. HTML bodies are rendered to markdown-ish text; text bodies pass through. A non-2xx status is reported, not an error. The tool-call timeout is deployment policy (`dsh-timeout-policy`), not a model argument. | +Both tools opt into concurrent scheduling because provider reads return content without mutating parent-agent state. + ## Config | Key | Default | Meaning | diff --git a/packages/web/tool-web/src/fetch.ts b/packages/web/tool-web/src/fetch.ts index a6b8883f4d..83358251fb 100644 --- a/packages/web/tool-web/src/fetch.ts +++ b/packages/web/tool-web/src/fetch.ts @@ -92,6 +92,8 @@ export function applyWebFetchTool(ctx: Context, timeoutMs: number): void { url: { type: 'string', required: true, description: 'The HTTP(S) URL to fetch.' }, }, timeoutMs, + // Provider reads do not mutate parent-agent state. + isConcurrencySafe: () => true, async execute(args, exec): Promise { const input = parseFetchArgs(args) const result = await ctx.web.fetch( diff --git a/packages/web/tool-web/src/search.ts b/packages/web/tool-web/src/search.ts index 6db829b7fc..af8753720d 100644 --- a/packages/web/tool-web/src/search.ts +++ b/packages/web/tool-web/src/search.ts @@ -109,6 +109,8 @@ export function applyWebSearchTool(ctx: Context, maxResults: number, timeoutMs: query: { type: 'string', required: true, description: 'The search query.' }, }, timeoutMs, + // Provider reads do not mutate parent-agent state. + isConcurrencySafe: () => true, async execute(args, exec): Promise { const input = parseSearchArgs(args) const result = await ctx.web.search( diff --git a/packages/web/tool-web/tests/tool-web.spec.ts b/packages/web/tool-web/tests/tool-web.spec.ts index a9f66d3746..088ace395e 100644 --- a/packages/web/tool-web/tests/tool-web.spec.ts +++ b/packages/web/tool-web/tests/tool-web.spec.ts @@ -166,6 +166,10 @@ describe('tool-web registration', () => { const names = ctx.tools.schemas().map(s => s.name) expect(names).toContain('web_search') expect(names).toContain('web_fetch') + expect(ctx.tools.executionMode({ callId: CallId('search-safe'), name: 'web_search', arguments: { query: 'q' } })) + .toEqual({ kind: 'parallel' }) + expect(ctx.tools.executionMode({ callId: CallId('fetch-safe'), name: 'web_fetch', arguments: { url: 'https://a.test' } })) + .toEqual({ kind: 'parallel' }) await fiber.dispose() expect(ctx.tools.schemas().map(s => s.name)).not.toContain('web_search') }) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 8d6081cd07..9810a9a61e 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -90,6 +90,120 @@ importers: specifier: ^4.1.8 version: 4.1.8(@types/node@22.20.0)(@vitest/coverage-v8@4.1.8)(jsdom@29.1.1)(vite@8.0.16(@types/node@22.20.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0)) + examples: + dependencies: + '@cordisjs/plugin-hmr': + specifier: workspace:* + version: link:../vendor/hmr + '@cordisjs/plugin-include': + specifier: workspace:* + version: link:../vendor/include + '@deepseek-ai/dsh-acp-demo': + specifier: workspace:* + version: link:../packages/examples/acp-demo + '@deepseek-ai/dsh-bash-local': + specifier: workspace:* + version: link:../packages/bash/bash-local + '@deepseek-ai/dsh-bash-sandbox': + specifier: workspace:* + version: link:../packages/bash/bash-sandbox + '@deepseek-ai/dsh-code-runtime-worker': + specifier: workspace:* + version: link:../packages/code-runtime/code-runtime-worker + '@deepseek-ai/dsh-compact-basic': + specifier: workspace:* + version: link:../packages/compact/compact-basic + '@deepseek-ai/dsh-fs-local': + specifier: workspace:* + version: link:../packages/fs/fs-local + '@deepseek-ai/dsh-fs-policy': + specifier: workspace:* + version: link:../packages/fs/fs-policy + '@deepseek-ai/dsh-hooks-claude': + specifier: workspace:* + version: link:../packages/hooks/hooks-claude + '@deepseek-ai/dsh-hooks-codex': + specifier: workspace:* + version: link:../packages/hooks/hooks-codex + '@deepseek-ai/dsh-llm': + specifier: workspace:* + version: link:../packages/llm/llm + '@deepseek-ai/dsh-llm-deepseek': + specifier: workspace:* + version: link:../packages/llm/llm-deepseek + '@deepseek-ai/dsh-llm-replay': + specifier: workspace:* + version: link:../packages/support/llm-replay + '@deepseek-ai/dsh-permission': + specifier: workspace:* + version: link:../packages/ui/permission + '@deepseek-ai/dsh-repeat-tool-guard': + specifier: workspace:* + version: link:../packages/guard/repeat-tool-guard + '@deepseek-ai/dsh-sandbox-local': + specifier: workspace:* + version: link:../packages/sandbox/sandbox-local + '@deepseek-ai/dsh-spill-local': + specifier: workspace:* + version: link:../packages/spill/spill-local + '@deepseek-ai/dsh-spill-policy': + specifier: workspace:* + version: link:../packages/spill/spill-policy + '@deepseek-ai/dsh-stdio-demo': + specifier: workspace:* + version: link:../packages/examples/stdio-demo + '@deepseek-ai/dsh-subagent': + specifier: workspace:* + version: link:../packages/subagent/subagent + '@deepseek-ai/dsh-subagent-fork': + specifier: workspace:* + version: link:../packages/subagent/subagent-fork + '@deepseek-ai/dsh-subagent-spawn': + specifier: workspace:* + version: link:../packages/subagent/subagent-spawn + '@deepseek-ai/dsh-time-context': + specifier: workspace:* + version: link:../packages/context/time-context + '@deepseek-ai/dsh-timeout-policy': + specifier: workspace:* + version: link:../packages/timeout/timeout-policy + '@deepseek-ai/dsh-token-meter': + specifier: workspace:* + version: link:../packages/llm/token-meter + '@deepseek-ai/dsh-tool-cordis': + specifier: workspace:* + version: link:../packages/cordis/tool-cordis + '@deepseek-ai/dsh-tool-fs': + specifier: workspace:* + version: link:../packages/fs/tool-fs + '@deepseek-ai/dsh-tool-fs-search': + specifier: workspace:* + version: link:../packages/fs/tool-fs-search + '@deepseek-ai/dsh-tool-subagent': + specifier: workspace:* + version: link:../packages/subagent/tool-subagent + '@deepseek-ai/dsh-tool-todo': + specifier: workspace:* + version: link:../packages/todo/tool-todo + '@deepseek-ai/dsh-tool-workflow': + specifier: workspace:* + version: link:../packages/workflow/tool-workflow + '@deepseek-ai/dsh-tools': + specifier: workspace:* + version: link:../packages/core/tools + '@deepseek-ai/dsh-user-approval': + specifier: workspace:* + version: link:../packages/ui/user-approval + '@deepseek-ai/dsh-web': + specifier: workspace:* + version: link:../packages/web/web + '@deepseek-ai/dsh-web-fetch-local': + specifier: workspace:* + version: link:../packages/web/web-fetch-local + '@deepseek-ai/dsh-workflow-workerthread': + specifier: workspace:* + version: link:../packages/workflow/workflow-workerthread + packages/bash/bash: devDependencies: '@deepseek-ai/dsh-sandbox': @@ -293,6 +407,9 @@ importers: '@deepseek-ai/dsh-llm': specifier: workspace:^ version: link:../../llm/llm + '@deepseek-ai/dsh-loader-smoke': + specifier: workspace:^ + version: link:../../support/loader-smoke '@deepseek-ai/dsh-session': specifier: workspace:^ version: link:../../core/session @@ -1352,6 +1469,9 @@ importers: '@deepseek-ai/dsh-llm': specifier: workspace:^ version: link:../../llm/llm + '@deepseek-ai/dsh-loader-smoke': + specifier: workspace:^ + version: link:../../support/loader-smoke '@deepseek-ai/dsh-subagent': specifier: workspace:^ version: link:../subagent @@ -1532,9 +1652,9 @@ importers: '@agentclientprotocol/sdk': specifier: 0.25.1 version: 0.25.1(zod@4.4.3) - tsx: - specifier: ^4.22.4 - version: 4.22.4 + '@deepseek-ai/dsh-loader-smoke': + specifier: workspace:* + version: link:../loader-smoke vitest: specifier: ^4.1.8 version: 4.1.8(@types/node@25.9.3)(@vitest/coverage-v8@4.1.8)(jsdom@29.1.1)(vite@8.0.16(@types/node@25.9.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0)) diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 07182c9959..8f93814899 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -2,6 +2,13 @@ packages: - vendor/* - packages/*/* - website + # The runnable demo leaves join as ONE workspace member: examples/package.json + # declares the union of every leaf's cordis.yml plugins as workspace:*, so a + # plain-node (`:lib`) boot of any leaf (examples//cordis.yml) resolves its + # plugins through real package `exports`→lib by walking up to examples/node_modules. + # Members for DEPENDENCY RESOLUTION only — NOT build targets: tsdown's explicit + # globs (vendor/*, packages/*/*) exclude them. See the example-execute-over-tsx RFC. + - examples # Deploy root of the single-exe build: a pure dependency manifest whose # closure is what the exe bundles and what the Python runtime distributes. - python/sdk-runtime diff --git a/scripts/doc-budgets.manifest.json b/scripts/doc-budgets.manifest.json index f8a39137aa..3b99ad454a 100644 --- a/scripts/doc-budgets.manifest.json +++ b/scripts/doc-budgets.manifest.json @@ -4,8 +4,8 @@ "docs/architecture.md": 1790, "docs/cordis-primer.md": 600, "docs/defensive-patterns.md": 550, - "docs/testing.md": 800, - "examples/AGENTS.md": 200, + "docs/testing.md": 960, + "examples/AGENTS.md": 310, "packages/AGENTS.md": 290, "packages/README.md": 760 } diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts index 2c31d95f52..66bc33851b 100644 --- a/scripts/gen-cordis-catalog.ts +++ b/scripts/gen-cordis-catalog.ts @@ -38,6 +38,7 @@ export const LINK_MAP: Record = { TurnEndReason: 'session.md', ToolDefinition: 'tools.md', ToolExecution: 'tools.md', + ToolExecutionMode: 'tools.md', ToolExecutionInput: 'tools.md', ToolExecutionResult: 'tools.md', ToolExecutionToken: 'tools.md', diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts index 0e6d930590..f6aaa6c2d9 100644 --- a/scripts/gen-doc-graphs.ts +++ b/scripts/gen-doc-graphs.ts @@ -847,10 +847,19 @@ function renderLifecycle(): string { ` Session-->>SDK: ${mermaidCode('session/event')} ${mermaidCode('assistant/chunk')}*`, ` Driver->>Hooks: ${mermaidCode('agent/step-result')} waterfall`, ` Driver->>Session: ${mermaidCode('assistant/message')}`, - ` Driver->>Session: ${mermaidCode('tool/call')}`, - ' Driver->>Tools: execute through pre and post waterfalls', - ' Tools-->>Session: tool-owned events when applicable', - ` Driver->>Session: ${mermaidCode('tool/result')} and ${mermaidCode('step/end')}`, + ' Driver->>Tools: classify pending call by executionMode', + ' loop barriers and bounded rolling pool, reclassify before start', + ' opt call starts', + ` Driver->>Session: ${mermaidCode('tool/call')}`, + ' Driver->>Tools: ordered pre, concurrent execute', + ' Tools-->>Session: tool-owned events when applicable', + ' end', + ' opt next model-order result ready', + ' Driver->>Tools: ordered post', + ` Driver->>Session: ${mermaidCode('tool/result')}`, + ' end', + ' end', + ` Driver->>Session: ${mermaidCode('step/end')}`, ` Driver->>Hooks: ${mermaidCode('agent/turn-continuation')} waterfall`, ` Driver->>Hooks: ${mermaidCode('agent/turn-stop')} serial terminal checkpoint`, ` Driver->>Session: ${mermaidCode('turn/end')}`, @@ -887,9 +896,9 @@ function renderToolPipeline(): string { ` owned["Tool-owned session events
${mermaidCode('todo/write')}, ${mermaidCode('fs/observed')}, ${mermaidCode('hook/invoked')}, ${mermaidCode('hook/result')}, ${mermaidCode('tool/code-dispatch')}"]`, ` post["${mermaidCode('tools/post-execute')} waterfall
accept, block, replace, add context"]`, ` final["${mermaidCode('tools/result')} synchronous notification
frozen authoritative outcome"]`, - ' context["Buffered additionalContexts
context/message after all tool results"]', + ' context["Active-batch additionalContexts FIFO
context/message after recorded tool results"]', ` toolResult["Session event: ${mermaidCode('tool/result')}
single model-facing outcome"]`, - ' allResults["All calls in the step settled
and tool/result events recorded"]', + ' allResults["Tool batch settled
recorded tool/result events complete"]', ' presentResult["UI completed card
presentResult(args, result)"]', ' model --> toolCall', ' toolCall --> presentCall', diff --git a/scripts/gen-persistence-catalog.ts b/scripts/gen-persistence-catalog.ts index 9469081607..8762b8529e 100644 --- a/scripts/gen-persistence-catalog.ts +++ b/scripts/gen-persistence-catalog.ts @@ -1,7 +1,7 @@ /** * Generate `docs/persistence-catalog.md` from every `SessionEventMap` merge and - * the owning `SurfaceEventType` union. This is the durable-record vocabulary, - * not the live Cordis bus. Event declarations must be unique, explicitly typed, + * the owning event-envelope types. This is the durable-record vocabulary, not + * the live Cordis bus. Event declarations must be unique, explicitly typed, * documented, inheritance-free, and free of Cordis-only `@mode` tags; every * surface-union member must resolve to one. `--check` verifies the artifact. */ @@ -14,13 +14,23 @@ import { parseJsDoc, pointer, rawJsDoc, reportViolations } from './jsdoc.ts' const root = resolve(import.meta.dirname, '..') const OUT = 'docs/persistence-catalog.md' -/** The fenced-block info string for generated payload blocks (skipped by - * doc-typecheck, since a bare payload fragment is not standalone-compilable). */ +/** The fenced-block info string for generated declaration blocks (skipped by + * doc-typecheck, since their imported types are not standalone-compilable). */ const FENCE = 'ts persistence-catalog' /** The package whose module id plugin merges augment (`declare module '…'`). */ const SESSION_MODULE = '@deepseek-ai/dsh-session' +/** Event-envelope declarations rendered before the per-event vocabulary. */ +const EVENT_ENVELOPE_TYPE_NAMES = [ + 'SessionEventType', + 'SurfaceEventType', + 'SurfaceOp', + 'SessionEvent', +] as const + +type EventEnvelopeTypeName = typeof EVENT_ENVELOPE_TYPE_NAMES[number] + /** Primary core-data-structures page for linked payload types. */ const LINK_MAP: Record = { CallId: 'core.md', @@ -41,6 +51,8 @@ export interface LogEventEntry { scope: string /** Payload type text (the member's type annotation, whitespace-collapsed). */ payload: string + /** Source member declaration and complete JSDoc, dedented from its container. */ + declaration: string /** Description prose (the member's JSDoc), one line per paragraph. */ doc: string /** Source pointer `packages/…/file.ts:line` of the declaration. */ @@ -53,6 +65,16 @@ export interface AnnotatedLogEventEntry extends LogEventEntry { surface: boolean } +/** One owning event-envelope declaration pasted into the generated catalog. */ +export interface EventEnvelopeTypeEntry { + /** Exported declaration name. */ + name: EventEnvelopeTypeName + /** Verbatim type declaration, including its complete leading JSDoc. */ + declaration: string + /** Source pointer `packages/…/file.ts:line` of the declaration. */ + source: string +} + const printer = ts.createPrinter({ removeComments: true }) /** @@ -67,6 +89,24 @@ function payloadText(type: ts.TypeNode, sf: ts.SourceFile): string { .trim() } +/** + * Copy a declaration from its leading JSDoc through its closing token while + * removing only the indentation imposed by its containing interface/module. + */ +function declarationText(text: string, sf: ts.SourceFile, node: ts.Node): string { + const raw = rawJsDoc(text, node) + const nodeStart = node.getStart(sf) + const start = raw ? text.lastIndexOf(raw, nodeStart) : nodeStart + const { line } = sf.getLineAndCharacterOfPosition(start) + const lineStart = sf.getPositionOfLineAndCharacter(line, 0) + const indent = text.slice(lineStart, start) + return text.slice(lineStart, node.end) + .split('\n') + .map(lineText => lineText.startsWith(indent) ? lineText.slice(indent.length) : lineText) + .join('\n') + .trimEnd() +} + /** * Every `interface SessionEventMap` declaration in a source file: the owning * top-level declaration (in `@deepseek-ai/dsh-session`) and any declaration @@ -177,7 +217,8 @@ export function collectLogEvents(scanRoot: string = root): LogEventEntry[] { if (!doc) { violations.push(`${where} has no description prose. Say what the event records and what its payload means — the JSDoc becomes the catalog entry.`) } - entries.push({ name, scope: name.split('/')[0] ?? name, payload, doc, source: src }) + const declaration = declarationText(text, sf, member) + entries.push({ name, scope: name.split('/')[0] ?? name, payload, declaration, doc, source: src }) } } } @@ -185,6 +226,51 @@ export function collectLogEvents(scanRoot: string = root): LogEventEntry[] { return entries } +/** + * Collect the exported declarations that compose the persisted event envelope, + * preserving their source JSDoc and declaration text. + */ +export function collectEventEnvelopeTypes(scanRoot: string = root): EventEnvelopeTypeEntry[] { + const found = new Map() + const violations: string[] = [] + const wanted = new Set(EVENT_ENVELOPE_TYPE_NAMES) + for (const rel of globSync('packages/*/*/src/**/*.ts', { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) { + const abs = resolve(scanRoot, rel) + const text = readFileSync(abs, 'utf8') + if (!EVENT_ENVELOPE_TYPE_NAMES.some(name => text.includes(name))) continue + if (packageNameFor(rel, scanRoot) !== SESSION_MODULE) continue + const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true) + for (const stmt of sf.statements) { + if (!ts.isTypeAliasDeclaration(stmt) || !wanted.has(stmt.name.text)) continue + const name = stmt.name.text as EventEnvelopeTypeName + const src = pointer(rel, sf, stmt) + const where = `event-envelope type '${name}' (${src})` + const prior = found.get(name) + if (prior) { + violations.push(`${where} is already declared at ${prior.source}; the persisted envelope type has exactly one owner.`) + continue + } + if (!(stmt.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) ?? false)) { + violations.push(`${where} is not exported.`) + } + const { doc, hasMode } = parseJsDoc(rawJsDoc(text, stmt)) + if (hasMode) violations.push(`${where} carries an @mode tag, but a persisted type has no dispatch mode.`) + if (!doc) violations.push(`${where} has no description prose. The full JSDoc is part of the generated catalog.`) + found.set(name, { name, declaration: declarationText(text, sf, stmt), source: src }) + } + } + const missing = EVENT_ENVELOPE_TYPE_NAMES.filter(name => !found.has(name)) + if (missing.length > 0) { + violations.push(`missing event-envelope declaration(s): ${missing.join(', ')}.`) + } + reportViolations('gen-persistence-catalog', violations) + return EVENT_ENVELOPE_TYPE_NAMES.map((name) => { + const entry = found.get(name) + if (!entry) throw new Error(`gen-persistence-catalog: missing checked event-envelope declaration '${name}'.`) + return entry + }) +} + /** * Parse the `SurfaceEventType` union — the surface-eligible subset of event * types — from source. Hard-errors when the alias is missing, declared more @@ -246,8 +332,7 @@ function typeLinks(payload: string): string { /** Render one log event entry. */ function renderEvent(e: AnnotatedLogEventEntry): string[] { const out = [`#### \`${e.name}\` — ${e.surface ? 'surface' : 'log-only'}`, ''] - if (e.doc) out.push(e.doc, '') - out.push('```' + FENCE, `'${e.name}': ${e.payload}`, '```', '') + out.push('```' + FENCE, e.declaration, '```', '') const links = typeLinks(e.payload) if (links) out.push(links, '') out.push(`Source: [\`${e.source}\`](../${e.source.split(':')[0]})`, '') @@ -255,18 +340,26 @@ function renderEvent(e: AnnotatedLogEventEntry): string[] { } /** Render the full catalog (pure, deterministic given the collected inputs). */ -export function render(events: AnnotatedLogEventEntry[]): string { +export function render(events: AnnotatedLogEventEntry[], envelopeTypes: EventEnvelopeTypeEntry[]): string { const lines: string[] = [ '', '', - '# Persistence Log Event Catalog', + '# Session Persistence Event Catalog', '', - 'Every event type that can appear in a session\'s durable event log: each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with the payload it carries, its surface badge, and the declaration it comes from. It complements [session.md](core-data-structures/session.md) (the `SessionEvent` envelope, surface list, and `deriveMessages()` projection), [persistence.md](core-data-structures/persistence.md) (how the log is made durable), and the [cordis events catalog](cordis-catalog/events.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).', + 'Every event type that can appear in a session\'s durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](core-data-structures/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](core-data-structures/persistence.md) (how the log is made durable), and the [cordis events catalog](cordis-catalog/events.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).', '', - 'This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Payload blocks use a `ts persistence-catalog` fence (skipped by doc-typecheck, since a bare payload fragment is not standalone-compilable). Type names in a payload link to the page that documents them. See [the persistence-log-catalog RFC](rfc/implemented/process/2026-07-04-persistence-log-catalog.md).', + 'This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks retain the source declaration and nested property JSDoc, removing only the indentation imposed by a containing interface/module, and use a `ts persistence-catalog` fence (skipped by doc-typecheck because declarations reference types from their owning modules). Type names in a payload link to the page that documents them. See [the persistence-log-catalog RFC](rfc/implemented/process/2026-07-04-persistence-log-catalog.md).', '', - 'The on-disk envelope around every payload is `SessionEvent` — `type`, monotonic `seq`, epoch-ms `time`, the `data` documented here, plus `surfaceOp`/`sourceEventSeqs` on **surface** events only ([envelope](core-data-structures/session.md#sessioneventt--one-log-entry)). **surface** marks a `SurfaceEventType` member: it produces an LLM message and declares how it joins the surface list. **log-only** marks everything else: durable, replayable record with no derived-history contribution. Every payload is JSON-serializable (enforced at `Session.append`), and the whole format is pinned at `SESSION_FORMAT_VERSION = 0` — pre-release, no compatibility implied ([the version stance](core-data-structures/persistence.md)). Scope: the packages in this repo; a downstream plugin can merge further event types, which are outside this catalog by construction.', + 'The envelope declarations below compose each event\'s `type`, monotonic `seq`, epoch-ms `time`, `data`, and the conditional `surfaceOp`/`sourceEventSeqs` fields. **surface** marks a `SurfaceEventType` member: it produces an LLM message and declares how it joins the surface list. **log-only** marks everything else: a durable, replayable record with no derived-history contribution. Every payload is JSON-serializable (enforced at `Session.append`), and the whole format is pinned at `SESSION_FORMAT_VERSION = 0` — pre-release, no compatibility implied ([the version stance](core-data-structures/persistence.md)). Scope: the packages in this repo; a downstream plugin can merge further event types, which are outside this catalog by construction.', + '', + '## Event envelope', + '', + '```' + FENCE, + envelopeTypes.map(entry => entry.declaration).join('\n\n'), + '```', + '', + `Sources: ${envelopeTypes.map(entry => `[\`${entry.source}\`](../${entry.source.split(':')[0]})`).join(' · ')}`, '', '## Events', '', @@ -285,7 +378,7 @@ export function render(events: AnnotatedLogEventEntry[]): string { * is stale. Guarded behind an entry-point check so importing this module for * tests neither regenerates the committed file nor calls process.exit. */ function main(): void { - const content = render(annotateSurface(collectLogEvents(), collectSurfaceEventTypes())) + const content = render(annotateSurface(collectLogEvents(), collectSurfaceEventTypes()), collectEventEnvelopeTypes()) if (process.argv.includes('--check')) { let committed: string | null = null try { diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts index fde83ff5ea..ed575858a6 100644 --- a/scripts/run-gates.ts +++ b/scripts/run-gates.ts @@ -163,11 +163,13 @@ function gatesForMode(selected: Mode): Gate[] { ] case 'ci-coverage': return [ + pnpmScript('build', 'build'), coverageGate(), ] case 'ci-snapshot': return [ - pnpmScript('snapshot', 'test:snapshot'), + pnpmScript('build', 'build'), + snapshotGate(), ] case 'ci-artifacts': return ciArtifactGates() @@ -186,7 +188,7 @@ function gatesForMode(selected: Mode): Gate[] { pnpmScript('cordis-config', 'verify-cordis-config', { label: 'Cordis config' }), pnpmScript('test', 'test'), pnpmScript('duplication', 'duplication'), - pnpmScript('snapshot', 'test:snapshot'), + snapshotGate(), pnpmScript('build', 'build'), ...hygieneLeafGates({ artifactNeeds: ['build'] }), ...docSyncLeafGates({ @@ -207,7 +209,7 @@ function ciPrimaryGates(): Gate[] { lintGate(), pnpmScript('duplication', 'duplication'), coverageGate(), - pnpmScript('snapshot', 'test:snapshot'), + snapshotGate(), demoSmokeGate({ needs: ['lint'] }), ...docSyncLeafGates(), pnpmScript('module-graph', 'verify-module-graph', { label: 'module graph' }), @@ -281,6 +283,18 @@ function coverageGate(): Gate { ...positiveIntArg('DSH_COVERAGE_MAX_WORKERS', '--maxWorkers'), ], { label: 'test:coverage', + env: { DSH_EXAMPLE_MODE: 'lib' }, + needs: ['build'], + }) +} + +// The snapshot suite boots the example bins in `lib` mode (built artifact under plain Node, +// plugins via real exports) — CI and pre-push already build, so they exercise what ships rather +// than the tsx/source path dev uses. It therefore waits on `build`. +function snapshotGate(): Gate { + return pnpmScript('snapshot', 'test:snapshot', { + env: { DSH_EXAMPLE_MODE: 'lib' }, + needs: ['build'], }) } diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json index 91d2543d1b..c16245f7cf 100644 --- a/scripts/type-equiv.manifest.json +++ b/scripts/type-equiv.manifest.json @@ -72,6 +72,7 @@ { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolExecutionToken", "source": "packages/core/tools/src/index.ts" }, { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolExecutionInput", "source": "packages/core/tools/src/index.ts" }, { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolExecution", "source": "packages/core/tools/src/index.ts" }, + { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolExecutionMode", "source": "packages/core/tools/src/index.ts" }, { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolRunContext", "source": "packages/core/tools/src/index.ts" }, { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolGuard", "source": "packages/core/tools/src/index.ts" }, { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolRestriction", "source": "packages/core/tools/src/index.ts" }, diff --git a/scripts/verify-cordis-config.ts b/scripts/verify-cordis-config.ts index 131bcf0e58..88615ee57a 100644 --- a/scripts/verify-cordis-config.ts +++ b/scripts/verify-cordis-config.ts @@ -1,18 +1,32 @@ /** - * Reject JavaScript expressions in Cordis Loader entry metadata. + * Validate Cordis Loader entry metadata and example package resolution. * * The Loader interpolates only a plugin entry's `config`; expression objects in * fields such as `disabled` remain truthy data and silently change composition. + * Example configs run from built packages, so every named package must resolve + * from the examples workspace and every local package must be in the root + * TypeScript project graph. */ import { globSync, readFileSync } from 'node:fs' -import { resolve } from 'node:path' +import { dirname, relative, resolve } from 'node:path' import * as yaml from 'js-yaml' +import ts from 'typescript' interface JsExpr { __jsExpr: string } +interface PackageManifest { + name?: string + dependencies?: Record +} + +interface PluginReference { + file: string + name: string +} + const root = resolve(import.meta.dirname, '..') const metadataFields = ['id', 'name', 'group', 'disabled', 'inject', 'intercept', 'isolate'] as const const jsExprType = new yaml.Type('tag:yaml.org,2002:js', { @@ -30,6 +44,7 @@ const files = globSync(['**/*cordis*.yml', '**/*cordis*.yaml'], { exclude: ['.claude/**', 'node_modules/**', 'vendor/**'], }).sort() const errors: string[] = [] +const examplePluginReferences: PluginReference[] = [] for (const file of files) { const document: unknown = yaml.load(readFileSync(resolve(root, file), 'utf8'), { schema }) @@ -42,8 +57,10 @@ for (const file of files) { } } +errors.push(...validateExampleResolution()) + if (errors.length > 0) { - console.error('verify-cordis-config: Loader entry metadata is static; move !!js under plugin config or select an explicit overlay.') + console.error('verify-cordis-config: invalid Loader metadata or example package resolution:') for (const error of errors) console.error(`- ${error}`) process.exitCode = 1 } else { @@ -55,6 +72,7 @@ function validateEntry(value: unknown, file: string, path: string): void { errors.push(`${file}${path}: entry must be an object`) return } + recordExamplePlugin(value, file) validateMetadata(value, file, path) if ((value.group === true || value.name === '@cordisjs/plugin-group') && isUnknownArray(value.config)) { for (let index = 0; index < value.config.length; index++) { @@ -68,6 +86,7 @@ function validateEntry(value: unknown, file: string, path: string): void { const patch = config.patches[index] const patchPath = `${path}.config.patches[${index}]` if (!isRecord(patch)) continue + recordExamplePlugin(patch, file) validateMetadata(patch, file, patchPath) if (!isUnknownArray(patch.insert)) continue for (let insertIndex = 0; insertIndex < patch.insert.length; insertIndex++) { @@ -76,6 +95,83 @@ function validateEntry(value: unknown, file: string, path: string): void { } } +function recordExamplePlugin(entry: Record, file: string): void { + if (file.startsWith('examples/') && typeof entry.name === 'string') { + examplePluginReferences.push({ file, name: entry.name }) + } +} + +function validateExampleResolution(): string[] { + const violations: string[] = [] + const exampleManifest = readManifest('examples/package.json') + const dependencies = exampleManifest.dependencies ?? {} + const localPackages = localPackageDirectories() + const rootReferences = rootProjectReferences() + const requiredPackages = new Map>() + + for (const reference of examplePluginReferences) { + const packageName = packageNameFromSpecifier(reference.name) + if (packageName === undefined) continue + const locations = requiredPackages.get(packageName) ?? new Set() + locations.add(reference.file) + requiredPackages.set(packageName, locations) + } + + for (const [packageName, locations] of requiredPackages) { + if (!(packageName in dependencies)) { + violations.push(`${[...locations].join(', ')}: ${packageName} must be declared in examples/package.json dependencies`) + } + } + + const localExamplePackages = new Set([ + ...Object.keys(dependencies), + ...requiredPackages.keys(), + ]) + for (const packageName of localExamplePackages) { + const packageDirectory = localPackages.get(packageName) + if (packageDirectory === undefined || rootReferences.has(packageDirectory)) continue + const repoPath = relative(root, packageDirectory).replaceAll('\\', '/') + violations.push(`tsconfig.json: missing project reference for ${packageName} (${repoPath})`) + } + + return violations +} + +function readManifest(path: string): PackageManifest { + return JSON.parse(readFileSync(resolve(root, path), 'utf8')) as PackageManifest +} + +function localPackageDirectories(): Map { + const manifests = globSync(['packages/*/*/package.json', 'vendor/*/package.json'], { cwd: root }) + const packages = new Map() + for (const manifestPath of manifests) { + const manifest = readManifest(manifestPath) + if (manifest.name !== undefined) packages.set(manifest.name, resolve(root, dirname(manifestPath))) + } + return packages +} + +function rootProjectReferences(): Set { + const config = ts.readConfigFile(resolve(root, 'tsconfig.json'), path => ts.sys.readFile(path)) + if (config.error !== undefined) { + throw new Error(ts.flattenDiagnosticMessageText(config.error.messageText, '\n')) + } + const references = (config.config as { references?: Array<{ path?: unknown }> }).references ?? [] + return new Set(references.flatMap((reference) => { + if (typeof reference.path !== 'string') return [] + return [resolve(root, reference.path)] + })) +} + +function packageNameFromSpecifier(specifier: string): string | undefined { + if (specifier.startsWith('.') || specifier.startsWith('/') || specifier.startsWith('file:')) return undefined + const segments = specifier.split('/') + if (specifier.startsWith('@')) { + return segments.length >= 2 ? `${segments[0]}/${segments[1]}` : undefined + } + return segments[0] || undefined +} + function validateMetadata(entry: Record, file: string, path: string): void { for (const field of metadataFields) { if (!(field in entry)) continue diff --git a/website/zh-CN/api/harness/agent-loop.md b/website/zh-CN/api/harness/agent-loop.md index 9c99b81fc6..413cc4f7c8 100644 --- a/website/zh-CN/api/harness/agent-loop.md +++ b/website/zh-CN/api/harness/agent-loop.md @@ -6,7 +6,7 @@ Concrete ReactLoopAgent factory and driver service. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L335) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L352) ### ctx.agentLoop.create(id, options?, meta?) @@ -22,7 +22,7 @@ Create an agent on a fresh per-run session, owned by the accessing fiber. Constr **Returns** the published running agent. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L391) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L412) ### ctx.agentLoop.createAgent(ownerCtx, options) @@ -37,7 +37,7 @@ Create an owned agent on a caller-supplied session id. **Returns** the published handle. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L414) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L435) ### ctx.agentLoop.resume(ownerCtx, options) @@ -52,4 +52,4 @@ Resume an owned agent from the configured persistence service. **Returns** the published handle. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L445) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L467) diff --git a/website/zh-CN/api/harness/events.md b/website/zh-CN/api/harness/events.md index cee0b34c72..5f99cb4f32 100644 --- a/website/zh-CN/api/harness/events.md +++ b/website/zh-CN/api/harness/events.md @@ -18,7 +18,7 @@ A fully configured agent and live session were published. Setup is composition-o - `agent` — the newly registered agent with its live session and completed setup. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L153) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L154) ### agent/disposed @@ -32,7 +32,7 @@ An agent left the registry; AgentLoop emits this after driver quiescence but bef - `agent` — the exact agent removed from the registry. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L162) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L163) ### agent/error @@ -49,7 +49,7 @@ A step or turn errored. The loop reports a failure here (plus the logger) even w - `step` — the step at which the failure surfaced. - `error` — the failure, verbatim. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L297) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L298) ### agent/pre-step @@ -68,7 +68,7 @@ Awaited serial checkpoint for session-surface mutation after prompt assembly and - `sessionPrefix` — the frozen request prefix. - `signal` — the turn abort signal. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L216) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L217) ### agent/prompt-submit @@ -84,7 +84,7 @@ Allow, rewrite, or block one drained prompt before it becomes a user message. Ca - `content` — the drained message's blocks, as queued. - `source` — the message's resolved source. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L226) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L227) ### agent/queued @@ -100,7 +100,7 @@ Detached, frozen content entered the agent's inbox. Source defaults have already - `content` — the accepted content blocks retained by the inbox. - `info` — the accepted source plus whether it entered as steering. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L181) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L182) ### agent/request @@ -117,7 +117,7 @@ Replace the frozen call configuration. Model-visible content must use logged cha - `step` — the step whose request this is. - `config` — the config the loop would use (frozen); return a replacement to switch. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L238) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L239) ### agent/session-prefix @@ -133,7 +133,7 @@ Compose request-only messages placed before derived history. The frozen result i - `prefix` — the frozen seed; return an extended replacement. - `signal` — aborts composition when the step is torn down. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L253) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L254) ### agent/session-start @@ -148,7 +148,7 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to - `agent` — the agent whose session lifecycle began. - `source` — why the session started (fresh startup, resume, …). Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L194) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L195) ### agent/status @@ -163,7 +163,7 @@ Agent status changed (`idle` ⇄ `running`, or → `disposed`). `send()` does no - `agent` — the agent whose status flipped. - `status` — the status just entered (the transition's destination). Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L171) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L172) ### agent/step-result @@ -180,7 +180,7 @@ Waterfall: post-process the assembled assistant Message before tool dispatch (va - `step` — the step that produced the message. - `message` — the assistant message as assembled from the stream. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L264) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L265) ### agent/turn-continuation @@ -196,7 +196,7 @@ Override whether the turn continues. The default continues after tool calls or s - `turn` — the turn being continued or stopped. - `defaultDecision` — what the loop would do absent an override. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L274) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L275) ### agent/turn-stop @@ -211,7 +211,7 @@ Monotonic terminal-stop checkpoint after continuation and steering are folded; a - `agent` — the agent whose composed continuation outcome may be stopped. - `turn` — the turn at its terminal-stop checkpoint. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L284) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L285) ## approval/* diff --git a/website/zh-CN/api/harness/tools.md b/website/zh-CN/api/harness/tools.md index 9d127b174a..6ed4ce024d 100644 --- a/website/zh-CN/api/harness/tools.md +++ b/website/zh-CN/api/harness/tools.md @@ -6,7 +6,7 @@ Tool registry and execution pipeline. Scoped registrations shadow globals; one visibility resolver feeds presentation, lookup, and dispatch. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L378) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L438) ### ctx.tools.register(definition) @@ -20,7 +20,7 @@ Register globally or in the calling agent scope. Scoped tools shadow globals; du **Returns** the exact disposer that unregisters the tool. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L468) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L538) ### ctx.tools.restrict(filter) @@ -34,7 +34,7 @@ Restrict global tools for the calling agent scope. Empty filters, unknown names, **Returns** the exact disposer that lifts this restriction. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L508) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L578) ### ctx.tools.guard(guard) @@ -48,7 +48,7 @@ Register a monotonic guard after the extensible `tools/pre-execute` waterfall. A **Returns** the exact disposer that unregisters the guard. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L559) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L629) ### ctx.tools.get(name, scope?) @@ -63,7 +63,7 @@ Look up a tool as one scope sees it (scoped shadows global; a restricted-away gl **Returns** the definition the scope resolves, or undefined when none is visible. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L661) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L731) ### ctx.tools.schemas(scope?) @@ -77,7 +77,21 @@ Project visible definitions onto the allowlisted model-facing schema fields, exc **Returns** one deep-cloned schema per visible tool. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L671) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L741) + +### ctx.tools.executionMode(exec) + +```ts website-api +executionMode(exec: ToolExecutionInput): ToolExecutionMode +``` + +Classify a pending call through the caller's visible tool definition. Only an exact `true` is parallel; unknown, hidden, undeclared, invalid, or throwing classifiers are exclusive. + +- `exec` — call name, parsed arguments, and optional agent scope. + +**Returns** the fail-closed scheduling mode. + +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L762) ### ctx.tools.execute(exec) @@ -91,4 +105,4 @@ Execute through pre-policy, guards, around-dispatch, post-policy, and final noti **Returns** the materialized final result. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L694) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L782)